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 Summary

Constructors

Constructor and Description
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.

Method Summary

Modifier and Type	Method and Description
void	afterCommit(BlockCommittedEvent event) Notifies the services in the runtime of the block commit event.
void	beforeCommit(int serviceId, Fork fork) Performs the before commit operation on the specified service in this runtime.
void	close()
void	commitService(ServiceInstanceSpec instanceSpec) Adds a service instance to the runtime after it has been successfully initialized in startAddingService(Fork, ServiceInstanceSpec, byte[]).
void	deployArtifact(ServiceArtifactId id, String filename) Loads a Java service artifact from the specified file.
void	executeTransaction(int serviceId, String interfaceName, int txId, byte[] arguments, Fork fork, int callerServiceId, com.exonum.binding.common.hash.HashCode txMessageHash, com.exonum.binding.common.crypto.PublicKey authorPublicKey) Executes a transaction belonging to the given service.
ServiceRuntimeProtos.ServiceRuntimeStateHashes	getStateHashes(Snapshot snapshot) Returns the state hashes of this runtime and the services registered in it as a protobuf message.
void	initialize(Node node) Initializes the runtime with the given node.
boolean	isArtifactDeployed(ServiceArtifactId id) Returns true if an artifact with the given id is currently deployed in this runtime.
void	shutdown() Stops this runtime.
void	startAddingService(Fork fork, ServiceInstanceSpec instanceSpec, byte[] configuration) Starts registration of a new service instance with the given specification.
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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

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 Detail

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,
                               com.exonum.binding.common.hash.HashCode txMessageHash,
                               com.exonum.binding.common.crypto.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