Skip to content
Branch: master
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
.mvn
src
CHANGELOG.md
README.md
checkstyle-suppressions.xml
generate-javadocs.sh
pom.xml

README.md

Exonum Java Light Client

Maven Central

Java client for Exonum blockchain.

Overview

Exonum light client is Java library for working with Exonum blockchain from the client side and can be easily integrated to an existing Java application.
Also, Exonum light client provides access to common utils (com.exonum.binding.common.* packages) toolkit which contains some helpful functions for hashing, cryptography, serialization, etc.

Capabilities

By using the client you are able to perform the following operations:

  • Submit transactions to the node
  • Receive transaction information
  • Receive blockchain blocks information
  • Receive node system information
  • Receive node status information
  • Receive list of started service instances

Please see the examples below and the Javadocs for details.

Compatibility

The following table shows versions compatibility:

Light Client Exonum Exonum Java
0.5.0 0.13.* 0.9.*
0.4.0 0.12.* 0.8.0
0.3.0 0.11.* 0.6.0-0.7.0
0.2.0 0.11.* 0.6.0
0.1.0 0.10.* 0.4

System Dependencies

  • Java 8 or above is required for using this client
  • Maven 3.5 or above (only if you need to build it locally)

QuickStart

If you are using Maven, add this to your pom.xml file

<dependency>
  <groupId>com.exonum.client</groupId>
  <artifactId>exonum-light-client</artifactId>
  <version>0.5.0</version>
</dependency>

If you are using Gradle, add this to your dependencies

compile 'com.exonum.client:exonum-light-client:0.5.0'

Examples

This section contains most frequently used operations with the blockchain. Please navigate to Exonum client API documentation to see all supported operations.

Exonum Client Initialization

The following example shows how to create the instance of exonum client which will work with Exonum node at http://localhost:8080 address:

    ExonumClient exonumClient = ExonumClient.newBuilder()
        .setExonumHost("http://localhost:8080")
        .build();

The next example shows how to use a custom configuration of the http-client:

    OkHttpClient httpClient = new OkHttpClient.Builder()
        .callTimeout(Duration.ofSeconds(3))
        .build();

    ExonumClient exonumClient = ExonumClient.newBuilder()
        .setExonumHost("http://localhost:8080")
        .setHttpClient(httpClient)
        .build();

Creating Transaction Message

The following example shows how to create the transaction message. In addition please read about transaction message structure.

    TransactionMessage txMessage = TransactionMessage.builder()
        .serviceId(serviceId)
        .transactionId(2)
        .payload(data)
        .sign(keys);
  • serviceId can be obtained, if needed, by the service name:
    int serviceId = exonumClient.findServiceInfo(serviceName)
        .map(ServiceInfo::getId)
        .orElseThrow(() -> new IllegalStateException("No service" 
            + " with the given name found: " + serviceName);
  • data is a bytes array which contains transactional information/parameters in a service-defined format. It can be any object which should be serialized to bytes in advance. We recommend to use Google Protobuf for serialization, but it is always an option of your choice. Also, common package provides StandardSerializers utility class which can be helpful for serialization.
  • keys is a key pair of private and public keys which is used for message signature.

Sending Transaction

To send the transaction just call a submitTransaction.
Make notice that it works in a blocking way i.e. your thread will be blocked till the response is received.

HashCode txHash = exonumClient.submitTransaction(tx);

Be aware that this method submits the transaction to the pool of uncommitted transactions and doesn't wait for the transaction acceptance to a new block.

Also, you can take a look at the integration test for the full example of how to create a transaction message and send it to Exonum node.

Transaction Info

The following method provides a possibility to get information on a transaction by its hash - status of the transaction, details of the message containing the transaction and, if available, transaction location and result:

Optional<TransactionResponse> response = exonumClient.getTransaction(txHash);
  • txHash is a hash of the transaction to search.

Retrieving service info

To retrieve the list of all started service instances:

List<ServiceInfo> response = exonumClient.getServiceInfoList();

How to Build

To build the client locally, clone the repository, and run next commands from the project's root i.e. exonum-java-binding directory:

export RUSTFLAGS=none
mvn install -pl exonum-light-client -am

It'll build Exonum Light client and the exonum-java-binding-common artifact which is required for the client.

License

Apache 2.0 - see LICENSE for more information.

You can’t perform that action at this time.