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 Summary

Modifier and Type	Method and Description
Transaction	convertToTransaction(BinaryMessage message) Converts an Exonum transaction message to an executable transaction of this service.
void	createPublicApiHandlers(Node node, io.vertx.ext.web.Router router) Creates handlers that makes up the public API of this service.
short	getId() Returns the id of the service.
java.lang.String	getName() Returns the name of the service.
default java.util.List<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.
default java.util.Optional<java.lang.String>	initialize(Fork fork) Initializes the service.

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(BinaryMessage message)

Converts an Exonum transaction message to an executable transaction of this service.

Parameters:

message - a transaction message (i.e., whose message type is a transaction and service id is set to the id of this service)

Returns:

an executable transaction

Throws:

java.lang.IllegalArgumentException - if the message is not a transaction of this service

java.lang.NullPointerException - if message is null

getStateHashes

default java.util.List<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