Package com.exonum.binding.core.runtime

Class ServiceRuntime

java.lang.Object
com.exonum.binding.core.runtime.ServiceRuntime
All Implemented Interfaces:
AutoCloseable
public final class ServiceRuntime
extends Object
implements AutoCloseable
A service runtime. It manages the services required for operation of Exonum services (e.g., a Server; allows the native code to load and unload artifacts (JAR archives with Exonum services), create and stop services defined in the loaded artifacts.

This class is thread-safe and does not support client-side locking. The thread-safety is provided because the class is a singleton and may be provided to other objects. Currently, however, there is a single injection point where ServiceRuntime is instantiated (during bootstrap) and it is used by the native runtime only in a single-threaded context, hence thread-safety isn't strictly required, but rather provided to avoid possible errors if it is ever accessed by other objects.

  • Constructor Details

    • ServiceRuntime

      @Inject public ServiceRuntime​(com.exonum.binding.core.runtime.ServiceLoader serviceLoader, com.exonum.binding.core.runtime.ServicesFactory servicesFactory, RuntimeTransport runtimeTransport, Path artifactsDir)
      Creates a new Java service runtime.
      Parameters:
      serviceLoader - a loader of service artifacts
      servicesFactory - the factory of services
      runtimeTransport - a web server providing transport to Java services
      artifactsDir - the directory in which administrators place and from which the service runtime loads service artifacts; may not exist at instantiation time

  • Method Details

    • initialize

      public void initialize​(Node node)
      Initializes the runtime with the given node. Starts the transport for Java services.

    • deployArtifact

      public void deployArtifact​(ServiceArtifactId id, String filename) throws ServiceLoadingException
      Loads a Java service artifact from the specified file. The loading involves verification of the artifact (i.e., that it is a valid Exonum service; includes a valid service factory).
      Parameters:
      id - a service artifact identifier; artifacts with non-equal ids will be rejected
      filename - a filename of the service artifact in the directory for artifacts
      Throws:
      ServiceLoadingException - if it failed to load an artifact; or if the given artifact is already loaded

    • isArtifactDeployed

      public boolean isArtifactDeployed​(ServiceArtifactId id)
      Returns true if an artifact with the given id is currently deployed in this runtime.
      Parameters:
      id - a service artifact identifier

    • startAddingService

      public void startAddingService​(Fork fork, ServiceInstanceSpec instanceSpec, byte[] configuration)
      Starts registration of a new service instance with the given specification. It involves the initial configuration of the service instance with the given parameters. The instance is not registered until commitService(ServiceInstanceSpec) is invoked.
      Parameters:
      fork - a database view to apply configuration
      instanceSpec - a service instance specification; must reference a deployed artifact
      configuration - service instance configuration parameters as a serialized protobuf message
      Throws:
      IllegalArgumentException - if the service is already started; or its artifact is not deployed
      RuntimeException - if it failed to instantiate the service; or if the service initialization failed

    • commitService

      public void commitService​(ServiceInstanceSpec instanceSpec)
      Adds a service instance to the runtime after it has been successfully initialized in startAddingService(Fork, ServiceInstanceSpec, byte[]). This operation completes the service instance registration, allowing subsequent operations on it: transactions, API requests.
      Parameters:
      instanceSpec - a service instance specification; must reference a deployed artifact
      Throws:
      IllegalArgumentException - if the service is already started; or its artifact is not deployed

    • executeTransaction

      public void executeTransaction​(int serviceId, String interfaceName, int txId, byte[] arguments, Fork fork, int callerServiceId, HashCode txMessageHash, PublicKey authorPublicKey) throws TransactionExecutionException
      Executes a transaction belonging to the given service.
      Parameters:
      serviceId - the numeric identifier of the service instance to which the transaction belongs
      interfaceName - a fully-qualified name of the interface in which the transaction is defined, or empty string if it is defined in the service directly (implicit interface)
      txId - the transaction type identifier
      arguments - the serialized transaction arguments
      fork - a native fork object
      callerServiceId - the id of the caller service if transaction is invoked by other service. Currently only applicable to invocations of Configure interface methods
      txMessageHash - the hash of the transaction message
      authorPublicKey - the public key of the transaction author
      Throws:
      TransactionExecutionException

    • getStateHashes

      public ServiceRuntimeProtos.ServiceRuntimeStateHashes getStateHashes​(Snapshot snapshot)
      Returns the state hashes of this runtime and the services registered in it as a protobuf message.
      Parameters:
      snapshot - the snapshot of the current database state

    • beforeCommit

      public void beforeCommit​(int serviceId, Fork fork)
      Performs the before commit operation on the specified service in this runtime.
      Parameters:
      serviceId - the id of the service on which to perform the operation
      fork - a fork allowing the runtime and the service to modify the database state.

    • afterCommit

      public void afterCommit​(BlockCommittedEvent event)
      Notifies the services in the runtime of the block commit event.

    • verifyTransaction

      public void verifyTransaction​(int serviceId, int txId, byte[] arguments)
      Verifies that an Exonum raw transaction can be correctly converted to an executable transaction of given service.
      Parameters:
      serviceId - the id of the service
      txId - the transaction type identifier within the service
      arguments - the serialized transaction arguments
      Throws:
      IllegalArgumentException - if there is no service with such id in this runtime, or if the transaction is not known to the service, or the arguments are not valid: e.g., cannot be deserialized, or do not meet the preconditions

    • shutdown

      public void shutdown() throws InterruptedException
      Stops this runtime. It will stop the server providing transport to services, remove all services and unload their artifacts. The operation is irreversible; the runtime may not be used after this operation completes.
      Throws:
      InterruptedException - if an interrupt was requested

    • close

      public void close() throws InterruptedException
      Specified by:
      close in interface AutoCloseable
      Throws:
      InterruptedException