com.scalar.dl.client.service

Class ClientService

java.lang.Object

com.scalar.dl.client.service.ClientService

All Implemented Interfaces:

java.lang.AutoCloseable

@Immutable
public class ClientService
extends java.lang.Object
implements java.lang.AutoCloseable

A thread-safe client that interacts with the ledger components to register certificates, register contracts, and execute contracts.

Usage Examples

Here is a simple example to demonstrate how to use them. ClientService should always be initialized with Guice, which maintains application-level singleton. Using this with a try-with-resources statement is also recommended to close it properly.

 Injector injector = Guice.createInjector(new ClientModule(new ClientConfig(new File(properties))));

 try (ClientService service = injector.getInstance(ClientService.class)) {
   JsonObject jsonArgument = Json.createReader(new StringReader(contractArgument)).readObject();
   ContractExecutionResult result = service.executeContract(contractId, jsonArgument);
   result.getResult().ifPresent(System.out::println);
 } catch (ClientException e) {
   System.err.println(e.getStatusCode());
   System.err.println(e.getMessage());
 }
 

Constructor Summary

Constructors

Constructor and Description
ClientService(ClientConfig config, AbstractLedgerClient client, RequestSigner signer) Constructs a ClientService with the specified ClientConfig, AbstractLedgerClient and RequestSigner.

Method Summary

Modifier and Type	Method and Description
void	close() Releases resources such as TCP connections.
com.scalar.dl.ledger.model.ContractExecutionResult	executeContract(byte[] serializedBinary) Executes the specified contract with the specified serialized byte array of a ContractExecutionRequest.
com.scalar.dl.ledger.model.ContractExecutionResult	executeContract(java.lang.String id, javax.json.JsonObject argument) Executes the specified contract with the specified argument for the certificate holder specified in ClientConfig.
com.scalar.dl.ledger.model.ContractExecutionResult	executeContract(java.lang.String id, javax.json.JsonObject argument, java.util.Optional<javax.json.JsonObject> functionArgument) Executes the specified contract with the specified argument for the certificate holder specified in ClientConfig.
javax.json.JsonObject	listContracts(byte[] serializedBinary) Retrieves a list of contracts with the specified serialized byte array of a ContractsListingRequest.
javax.json.JsonObject	listContracts(java.lang.String id) Retrieves a list of contracts for the certificate holder specified in ClientConfig.
void	registerCertificate() Registers the certificate specified in the given ClientConfig.
void	registerCertificate(byte[] serializedBinary) Registers the certificate with the specified serialized byte array of a CertificateRegistrationRequest.
void	registerContract(byte[] serializedBinary) Registers the contract with the specified serialized byte array of a ContractRegistrationRequest.
void	registerContract(java.lang.String id, java.lang.String name, byte[] contractBytes, java.util.Optional<javax.json.JsonObject> properties) Registers the specified contract for the certificate holder specified in ClientConfig.
void	registerContract(java.lang.String id, java.lang.String name, java.lang.String contractPath, java.util.Optional<javax.json.JsonObject> properties) Registers the specified contract for the certificate holder specified in ClientConfig.
void	registerFunction(byte[] serializedBinary) Registers the function with the specified serialized byte array of a FunctionRegistrationRequest.
void	registerFunction(java.lang.String id, java.lang.String name, byte[] functionBytes) Registers the specified function.
void	registerFunction(java.lang.String id, java.lang.String name, java.lang.String functionPath) Registers the specified function.
com.scalar.dl.ledger.model.LedgerValidationResult	validateLedger(byte[] serializedBinary) Validates the specified asset in the ledger with the specified serialized byte array of a LedgerValidationRequest.
com.scalar.dl.ledger.model.LedgerValidationResult	validateLedger(java.lang.String assetId) Validates the specified asset in the ledger for the certificate holder specified in ClientConfig.
com.scalar.dl.ledger.model.LedgerValidationResult	validateLedger(java.lang.String assetId, int startAge, int endAge) Validates the specified asset between the specified ages in the ledger for the certificate holder specified in ClientConfig.
com.scalar.dl.ledger.model.LedgersValidationResult	validateLedgers(byte[] serializedBinary) Validates the specified asset in multiple ledgers with the specified serialized byte array of a LedgersValidationRequest.
com.scalar.dl.ledger.model.LedgersValidationResult	validateLedgers(java.lang.String assetId) Validates the specified asset in multiple ledgers for the certificate holder specified in ClientConfig.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ClientService

@Inject
public ClientService(ClientConfig config,
                             AbstractLedgerClient client,
                             @Nullable
                             RequestSigner signer)

Constructs a ClientService with the specified ClientConfig, AbstractLedgerClient and RequestSigner. This constructor shouldn't be called explicitly and should be called implicitly by Guice.

Parameters:

config - a configuration for the client

client - a client for the ledger server

signer - a request signer for requests

Method Detail

registerCertificate

public void registerCertificate()

Registers the certificate specified in the given ClientConfig.

Throws:

ClientException - if a request fails for some reason

registerCertificate

public void registerCertificate(byte[] serializedBinary)

Registers the certificate with the specified serialized byte array of a CertificateRegistrationRequest. request.

Parameters:

serializedBinary - a serialized byte array of CertificateRegistrationRequest.

Throws:

ClientException - if a request fails for some reason

registerFunction

public void registerFunction(java.lang.String id,
                             java.lang.String name,
                             byte[] functionBytes)

Registers the specified function.

Parameters:

id - an ID of the function

name - the binary name of the function class

functionBytes - the byte code of the function class

Throws:

ClientException - if a request fails for some reason

registerFunction

public void registerFunction(java.lang.String id,
                             java.lang.String name,
                             java.lang.String functionPath)

Registers the specified function.

Parameters:

id - an ID of the function

name - the binary name of the function class

functionPath - the relative path of the function class

Throws:

ClientException - if a request fails for some reason

registerFunction

public void registerFunction(byte[] serializedBinary)

Registers the function with the specified serialized byte array of a FunctionRegistrationRequest.

Parameters:

serializedBinary - a serialized byte array of FunctionRegistrationRequest.

Throws:

ClientException - if a request fails for some reason

registerContract

public void registerContract(java.lang.String id,
                             java.lang.String name,
                             byte[] contractBytes,
                             java.util.Optional<javax.json.JsonObject> properties)

Registers the specified contract for the certificate holder specified in ClientConfig.

Parameters:

id - an ID of the contract

name - the binary name of the contract class

contractBytes - the byte code of the contract class

properties - a contract properties

Throws:

ClientException - if a request fails for some reason

registerContract

public void registerContract(java.lang.String id,
                             java.lang.String name,
                             java.lang.String contractPath,
                             java.util.Optional<javax.json.JsonObject> properties)

Registers the specified contract for the certificate holder specified in ClientConfig.

Parameters:

id - an ID for the contract

name - the binary name of the contract class

contractPath - the relative path of the contract class

properties - a contract properties

Throws:

ClientException - if a request fails for some reason

registerContract

public void registerContract(byte[] serializedBinary)

Registers the contract with the specified serialized byte array of a ContractRegistrationRequest.

Parameters:

serializedBinary - a serialized byte array of ContractRegistrationRequest.

Throws:

ClientException - if a request fails for some reason

listContracts

public javax.json.JsonObject listContracts(java.lang.String id)

Retrieves a list of contracts for the certificate holder specified in ClientConfig. If specified with a contract ID, it will return the matching contract only.

Parameters:

id - a contract ID

Returns:

JsonObject

Throws:

ClientException - if a request fails for some reason

listContracts

public javax.json.JsonObject listContracts(byte[] serializedBinary)

Retrieves a list of contracts with the specified serialized byte array of a ContractsListingRequest.

Parameters:

serializedBinary - a serialized byte array of ContractsListingRequest.

Returns:

JsonObject

Throws:

ClientException - if a request fails for some reason

executeContract

public com.scalar.dl.ledger.model.ContractExecutionResult executeContract(java.lang.String id,
                                                                          javax.json.JsonObject argument)

Executes the specified contract with the specified argument for the certificate holder specified in ClientConfig.

Parameters:

id - an ID of the contract

argument - an argument of the contract

Returns:

ContractExecutionResult

Throws:

ClientException - if a request fails for some reason

executeContract

public com.scalar.dl.ledger.model.ContractExecutionResult executeContract(java.lang.String id,
                                                                          javax.json.JsonObject argument,
                                                                          java.util.Optional<javax.json.JsonObject> functionArgument)

Executes the specified contract with the specified argument for the certificate holder specified in ClientConfig.

Parameters:

id - an ID of the contract

argument - an argument of the contract

functionArgument - an argument of the function

Returns:

ContractExecutionResult

Throws:

ClientException - if a request fails for some reason

executeContract

public com.scalar.dl.ledger.model.ContractExecutionResult executeContract(byte[] serializedBinary)

Executes the specified contract with the specified serialized byte array of a ContractExecutionRequest.

Parameters:

serializedBinary - a serialized byte array of ContractExecutionRequest.

Returns:

ContractExecutionResult

Throws:

ClientException - if a request fails for some reason

validateLedger

public com.scalar.dl.ledger.model.LedgerValidationResult validateLedger(java.lang.String assetId)

Validates the specified asset in the ledger for the certificate holder specified in ClientConfig.

Parameters:

assetId - an asset ID

Returns:

LedgerValidationResult

Throws:

ClientException - if a request fails for some reason

validateLedger

public com.scalar.dl.ledger.model.LedgerValidationResult validateLedger(java.lang.String assetId,
                                                                        int startAge,
                                                                        int endAge)

Validates the specified asset between the specified ages in the ledger for the certificate holder specified in ClientConfig.

Parameters:

assetId - an asset ID

startAge - an age to be validated from (inclusive)

endAge - an age to be validated to (inclusive)

Returns:

LedgerValidationResult

Throws:

ClientException - if a request fails for some reason

validateLedger

public com.scalar.dl.ledger.model.LedgerValidationResult validateLedger(byte[] serializedBinary)

Validates the specified asset in the ledger with the specified serialized byte array of a LedgerValidationRequest.

Parameters:

serializedBinary - a serialized byte array of LedgerValidationRequest.

Returns:

LedgerValidationResult

Throws:

ClientException - if a request fails for some reason

validateLedgers

public com.scalar.dl.ledger.model.LedgersValidationResult validateLedgers(java.lang.String assetId)

Validates the specified asset in multiple ledgers for the certificate holder specified in ClientConfig.

Parameters:

assetId - an asset ID

Returns:

LedgersValidationResult

Throws:

ClientException - if a request fails for some reason

validateLedgers

public com.scalar.dl.ledger.model.LedgersValidationResult validateLedgers(byte[] serializedBinary)

Validates the specified asset in multiple ledgers with the specified serialized byte array of a LedgersValidationRequest.

Parameters:

serializedBinary - a serialized byte array of LedgersValidationRequest.

Returns:

LedgersValidationResult

Throws:

ClientException - if a request fails for some reason

close

public void close()

Releases resources such as TCP connections.

Specified by:

close in interface java.lang.AutoCloseable