Package com.exonum.binding.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 Detail

      • getId

        short getId()
        Returns the id of the service.

      • getName

        java.lang.String getName()
        Returns the name of the service.

      • initialize

        default java.util.Optional<java.lang.String> initialize​(Fork fork)
        Initializes the service. This method is called once when a genesis block is created and is supposed to
        • (a) initialize the database schema of this service, and
        • (b) provide an initial global configuration of the service.

        The service configuration parameters must be provided as a JSON string. It is recorded in a table of global configuration parameters of each service deployed in the network.

        Parameters:
        fork - a database fork to apply changes to. Not valid after this method returns
        Returns:
        a global configuration of the service, or Optional.empty() if the service does not have any configuration parameters.
        See Also:
        Genesis block handler

      • convertToTransaction

        Transaction convertToTransaction​(RawTransaction rawTransaction)
        Converts an Exonum raw transaction to an executable transaction of this service.
        Parameters:
        rawTransaction - a raw transaction to be converted
        Returns:
        an executable transaction
        Throws:
        java.lang.IllegalArgumentException - if the raw transaction is malformed or it doesn't belong to this service
        java.lang.NullPointerException - if raw transaction is null

      • getStateHashes

        default java.util.List<com.exonum.binding.common.hash.HashCode> getStateHashes​(Snapshot snapshot)
        Returns a list of root hashes of all Merklized tables defined by this service, as of the given snapshot of the blockchain state. If the service doesn't have any Merklized tables, returns an empty list.

        The core uses this list to aggregate hashes of tables defined by all services into a single Merklized meta-map. The hash of this meta-map is considered the hash of the entire blockchain state and is recorded as such in blocks and Precommit messages.

        Parameters:
        snapshot - a snapshot of the blockchain state. Not valid after this method returns
        See Also:
        ProofListIndexProxy.getRootHash(), ProofMapIndexProxy.getRootHash()

      • createPublicApiHandlers

        void createPublicApiHandlers​(Node node,
                             io.vertx.ext.web.Router router)
        Creates handlers that makes up the public API of this service. The handlers are added to the given router, which is then mounted at a path, equal to the service name.

        Please note that the path prefix is stripped from the request path when it is forwarded to the given router. For example, if your service name is «cryptocurrency», and you have two endpoints «/send-money» and «/balance», use these names when defining handlers, and they will be available by paths «/cryptocurrency/send-money» and «/cryptocurrency/balance»: 

        
 router.get("/balance").handler((rc) -> {
   rc.response().end("$1’000’000");
 });
        Parameters:
        node - a set-up Exonum node, providing an interface to access the current blockchain state and submit transactions
        router - a router responsible for handling requests to this service

      • 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