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 Summary

Modifier and Type	Method and Description
default void	afterCommit(BlockCommittedEvent event) Handles read-only block commit event.
Transaction	convertToTransaction(RawTransaction rawTransaction) Converts an Exonum raw transaction to an executable transaction of this service.
void	createPublicApiHandlers(Node node, io.vertx.ext.web.Router router) Creates handlers that make up the public HTTP API of this service.
short	getId() Returns the id of the service.
String	getName() Returns the name of the service.
default List<com.exonum.binding.common.hash.HashCode>	getStateHashes(Snapshot snapshot) Returns a list of root hashes of all Merkelized tables defined by this service, as of the given snapshot of the blockchain state.
default Optional<String>	initialize(Fork fork) Initializes the service.

Method Detail

getId

short getId()

Returns the id of the service.

getName

String getName()

Returns the name of the service.

initialize

default Optional<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:

Initialization 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:

IllegalArgumentException - if the raw transaction is malformed or it doesn't belong to this service

NullPointerException - if raw transaction is null

getStateHashes

default List<com.exonum.binding.common.hash.HashCode> getStateHashes(Snapshot snapshot)

Returns a list of root hashes of all Merkelized tables defined by this service, as of the given snapshot of the blockchain state. If the service doesn't have any Merkelized tables, returns an empty list.

The core uses this list to aggregate hashes of tables defined by all services into a single Merkelized 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 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]");
 });
 

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

See Also:

Documentation on service API

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