Package com.exonum.binding.core.service

Interface Service

All Known Implementing Classes:
AbstractService
public interface Service
An Exonum service.

You shall usually subclass an AbstractService which implements some of the methods declared in this interface.

  • Method Details

    • initialize

      default void initialize​(ExecutionContext context, Configuration configuration)
      Performs an initial configuration of the service instance. This method is called once after the service instance is added to the blockchain and allows initializing some persistent data of the service.

      As Exonum passes the configuration parameters only once and does not persist them for later access, this service method must make any needed changes to the database based on these parameters. For example, it may initialize some collections in its schema (including one-off initialization that does not depend on the parameters); or save all or some configuration parameters as is for later retrieval in transactions and/or read requests.

      Parameters:
      context - the execution context
      configuration - the service configuration parameters
      Throws:
      ExecutionException - if the configuration parameters are not valid (e.g., malformed, or do not meet the preconditions). Exonum will stop the service if its initialization fails. It will save the error into Blockchain.getCallRecords(long) the registry of call errors}
      See Also:
      Configurable

    • resume

      default void resume​(ExecutionContext context, byte[] arguments)
      Resumes the previously stopped service instance. This method is called when a stopped service instance is restarted.

      This method may perform any changes to the database. For example, update some service parameters, deprecate old entries etc.

      Also, note that performing any bulk operations or data migration is not recommended here, because this method is invoked synchronously when the block is committed.

      Parameters:
      context - the execution context
      arguments - the service arguments
      Throws:
      ExecutionException - if the arguments are not valid (e.g., malformed, or do not meet the preconditions)

    • createPublicApiHandlers

      void createPublicApiHandlers​(Node node, io.vertx.ext.web.Router router)
      Creates handlers that make up the public HTTP API of this service. The handlers are added to the given router, which is then mounted at the following path: /api/services/<service-name>.

      Please note that the path prefix shown above is stripped from the request path when it is forwarded to the given router. For example, if your service name is «timestamping», and you have an endpoint «/timestamp», use «/timestamp» as the endpoint name when defining the handler and it will be available by path «/api/services/timestamping/timestamp»: 

      
 router.get("/timestamp").handler((rc) -> {
   rc.response().end("2019-04-01T10:15:30+02:00[Europe/Kiev]");
 });

      Please remember that Java services use a separate server from Rust services. The Java server TCP port is specified on node start, see documentation for details.

      Parameters:
      node - a set-up Exonum node, providing an interface to access the current blockchain state and submit transactions. Note that a node gets closed automatically by the runtime when the service stops
      router - a router responsible for handling requests to this service
      See Also:
      Documentation on service API

    • beforeTransactions

      default void beforeTransactions​(ExecutionContext context)
      An optional callback method invoked by the blockchain before any transactions in a block are executed. See afterTransactions(ExecutionContext) for details.
      See Also:
      afterTransactions(ExecutionContext), Transaction

    • afterTransactions

      default void afterTransactions​(ExecutionContext context)
      Handles the changes made by all transactions included in the upcoming block.

      This handler is an optional callback method invoked by the blockchain after all transactions in a block are executed, but before it is committed. The service can modify its state in this handler, therefore, implementations must be deterministic and use only the current database state as their input.

      This method is invoked synchronously from the thread that commits the block, therefore, implementations of this method must not perform any blocking or long-running operations.

      Any exceptions in this method will revert any changes made to the database by it, but will not affect the processing of this block. Exceptions are saved in the registry of call errors with appropriate error kinds.

      Parameters:
      context - the execution context
      Throws:
      ExecutionException - if an error occurs during the method execution; it is saved as a call error of kind "service". Any other exceptions are considered unexpected. They are saved with kind "unexpected".
      See Also:
      beforeTransactions(ExecutionContext), Transaction

    • afterCommit

      default void afterCommit​(BlockCommittedEvent event)
      Handles read-only block commit event. This handler is an optional callback method which is invoked by the blockchain after each block commit. For example, a service can create one or more transactions if a specific condition has occurred.

      This method is invoked synchronously from the thread that commits the block, therefore, implementations of this method must not perform any blocking or long-running operations.

      Any exceptions in this method will be swallowed and will not affect the processing of transactions or blocks.

      Parameters:
      event - the read-only context allowing to access the blockchain state as of that committed block