com.scalar.dl.client.service

Class GenericContractClientService

java.lang.Object

com.scalar.dl.client.service.GenericContractClientService

@Immutable
public class GenericContractClientService
extends java.lang.Object

A thread-safe client that interacts with Ledger and Auditor components to register certificates, register contracts, execute contracts, and validate data in a generic-contract environment.

Usage Examples

Here is a simple example to demonstrate how to use GenericContractClientService. GenericContractClientService should always be created with ClientServiceFactory, which reuses internal instances as much as possible for better performance and less resource usage.

 ClientServiceFactory factory = new ClientServiceFactory(); // the factory should be reused

 GenericContractClientService service =
         factory.createForGenericContract(new ClientConfig(new File(properties));
 try {
   JsonNode jsonArgument = ...; // create an application-specific argument
   ContractExecutionResult result = service.executeContract(contractId, jsonArgument);
   result.getContractResult().ifPresent(System.out::println);
 } catch (ClientException e) {
   System.err.println(e.getStatusCode());
   System.err.println(e.getMessage());
 }

 factory.close();
 

Constructor Summary

Constructors

Constructor and Description
GenericContractClientService(ClientService clientService) Constructs a GenericContractClientService with the specified ClientService.

Method Summary

Modifier and Type	Method and Description
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 contractId, com.fasterxml.jackson.databind.JsonNode contractArgument) Executes the specified contract with the specified argument.
com.scalar.dl.ledger.model.ContractExecutionResult	executeContract(java.lang.String contractId, com.fasterxml.jackson.databind.JsonNode contractArgument, java.lang.String functionId, com.fasterxml.jackson.databind.JsonNode functionArgument) Executes the specified contract (and functions) with the specified arguments.
com.scalar.dl.ledger.model.ContractExecutionResult	executeContract(java.lang.String contractId, javax.json.JsonObject contractArgument) Executes the specified contract (and functions) with the specified argument.
com.scalar.dl.ledger.model.ContractExecutionResult	executeContract(java.lang.String contractId, javax.json.JsonObject contractArgument, java.lang.String functionId, javax.json.JsonObject functionArgument) Executes the specified contract (and function) with the specified arguments.
com.scalar.dl.ledger.model.ContractExecutionResult	executeContract(java.lang.String contractId, java.lang.String contractArgument) Executes the specified contract with the specified argument.
com.scalar.dl.ledger.model.ContractExecutionResult	executeContract(java.lang.String contractId, java.lang.String contractArgument, java.lang.String functionId, java.lang.String functionArgument) Executes the specified contract (and function) with the specified arguments.
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 for digital signature authentication.
void	registerCertificate(byte[] serializedBinary) Registers the certificate specified with the serialized byte array of a CertificateRegistrationRequest for digital signature authentication.
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) Registers the specified contract for the certificate holder specified in ClientConfig.
void	registerContract(java.lang.String id, java.lang.String name, byte[] contractBytes, com.fasterxml.jackson.databind.JsonNode properties) Registers the specified contract for the certificate holder specified in ClientConfig.
void	registerContract(java.lang.String id, java.lang.String name, byte[] contractBytes, 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, byte[] contractBytes, java.lang.String 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) 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, com.fasterxml.jackson.databind.JsonNode 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, 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.lang.String 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.
void	registerSecret() Registers the secret key specified in the given ClientConfig for HMAC authentication.
void	registerSecret(byte[] serializedBinary) Registers the secret key specified with the serialized byte array of a SecretRegistrationRequest for HMAC authentication.
com.scalar.dl.ledger.model.LedgerValidationResult	validateLedger(com.scalar.dl.genericcontracts.AssetType type, java.util.List<java.lang.String> keys) Validates the specified asset in the ledger.
com.scalar.dl.ledger.model.LedgerValidationResult	validateLedger(com.scalar.dl.genericcontracts.AssetType type, java.util.List<java.lang.String> keys, int startAge, int endAge) Validates the specified asset between the specified ages in the ledger.
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.

Methods inherited from class java.lang.Object

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

Constructor Detail

GenericContractClientService

public GenericContractClientService(ClientService clientService)

Constructs a GenericContractClientService with the specified ClientService.

Parameters:

clientService - a client service

Method Detail

registerCertificate

public void registerCertificate()

Registers the certificate specified in the given ClientConfig for digital signature authentication.

Throws:

ClientException - if a request fails for some reason

registerCertificate

public void registerCertificate(byte[] serializedBinary)

Registers the certificate specified with the serialized byte array of a CertificateRegistrationRequest for digital signature authentication.

Parameters:

serializedBinary - a serialized byte array of CertificateRegistrationRequest.

Throws:

ClientException - if a request fails for some reason

registerSecret

public void registerSecret()

Registers the secret key specified in the given ClientConfig for HMAC authentication.

Throws:

ClientException - if a request fails for some reason

registerSecret

public void registerSecret(byte[] serializedBinary)

Registers the secret key specified with the serialized byte array of a SecretRegistrationRequest for HMAC authentication.

Parameters:

serializedBinary - a serialized byte array of SecretRegistrationRequest.

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. To execute the function, you need to use the corresponding executeContract methods that match the type of the 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. To execute the function, you need to use the corresponding executeContract methods that match the type of the 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)

Registers the specified contract for the certificate holder specified in ClientConfig. To execute the contract, you need to use the corresponding executeContract methods that match the type of the contract.

Parameters:

id - an ID for the contract

name - the binary name of the contract class

contractBytes - the byte array of the contract class

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)

Registers the specified contract for the certificate holder specified in ClientConfig. To execute the contract, you need to use the corresponding executeContract methods that match the type of the contract.

Parameters:

id - an ID for the contract

name - the binary name of the contract class

contractPath - the relative path of the contract class

Throws:

ClientException - if a request fails for some reason

registerContract

public void registerContract(java.lang.String id,
                             java.lang.String name,
                             byte[] contractBytes,
                             @Nullable
                             javax.json.JsonObject properties)

Registers the specified contract for the certificate holder specified in ClientConfig. To execute the contract, you need to use the corresponding executeContract methods that match the type of the contract.

Parameters:

id - an ID for the contract

name - the binary name of the contract class

contractBytes - the byte array 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,
                             @Nullable
                             javax.json.JsonObject properties)

Registers the specified contract for the certificate holder specified in ClientConfig. To execute the contract, you need to use the corresponding executeContract methods that match the type of the contract.

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(java.lang.String id,
                             java.lang.String name,
                             byte[] contractBytes,
                             @Nullable
                             com.fasterxml.jackson.databind.JsonNode properties)

Registers the specified contract for the certificate holder specified in ClientConfig. To execute the contract, you need to use the corresponding executeContract methods that match the type of the contract.

Parameters:

id - an ID for the contract

name - the binary name of the contract class

contractBytes - the byte array 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,
                             @Nullable
                             com.fasterxml.jackson.databind.JsonNode properties)

Registers the specified contract for the certificate holder specified in ClientConfig. To execute the contract, you need to use the corresponding executeContract methods that match the type of the contract.

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(java.lang.String id,
                             java.lang.String name,
                             java.lang.String contractPath,
                             @Nullable
                             java.lang.String properties)

Registers the specified contract for the certificate holder specified in ClientConfig. To execute the contract, you need to use the corresponding executeContract methods that match the type of the contract.

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(java.lang.String id,
                             java.lang.String name,
                             byte[] contractBytes,
                             @Nullable
                             java.lang.String properties)

Registers the specified contract for the certificate holder specified in ClientConfig. To execute the contract, you need to use the corresponding executeContract methods that match the type of the contract.

Parameters:

id - an ID for the contract

name - the binary name of the contract class

contractBytes - the byte array 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 contractId,
                                                                          javax.json.JsonObject contractArgument)

Executes the specified contract (and functions) with the specified argument. The contract and functions have to be based on JSONP, such as JsonpBasedContract and JsonpBasedFunction.

Parameters:

contractId - an ID of the contract

contractArgument - 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 contractId,
                                                                          javax.json.JsonObject contractArgument,
                                                                          @Nullable
                                                                          java.lang.String functionId,
                                                                          @Nullable
                                                                          javax.json.JsonObject functionArgument)

Executes the specified contract (and function) with the specified arguments. The contract and functions have to be based on JSONP, such as JsonpBasedContract and JsonpBasedFunction.

Parameters:

contractId - an ID of the contract

contractArgument - an argument of the contract

functionId - an ID of the function

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(java.lang.String contractId,
                                                                          com.fasterxml.jackson.databind.JsonNode contractArgument)

Executes the specified contract with the specified argument. The contract and functions have to be based on Jackson, such as JacksonBasedContract and JacksonBasedFunction.

Parameters:

contractId - an ID of the contract

contractArgument - 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 contractId,
                                                                          com.fasterxml.jackson.databind.JsonNode contractArgument,
                                                                          @Nullable
                                                                          java.lang.String functionId,
                                                                          @Nullable
                                                                          com.fasterxml.jackson.databind.JsonNode functionArgument)

Executes the specified contract (and functions) with the specified arguments. The contract and functions have to be based on Jackson, such as JacksonBasedContract and JacksonBasedFunction.

Parameters:

contractId - an ID of the contract

contractArgument - an argument of the contract

functionId - an ID of the function

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(java.lang.String contractId,
                                                                          java.lang.String contractArgument)

Executes the specified contract with the specified argument. The contract has to be based on String (i.e., StringBasedContract).

Parameters:

contractId - an ID of the contract

contractArgument - 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 contractId,
                                                                          java.lang.String contractArgument,
                                                                          @Nullable
                                                                          java.lang.String functionId,
                                                                          @Nullable
                                                                          java.lang.String functionArgument)

Executes the specified contract (and function) with the specified arguments. The contract and functions have to be based on String, such as StringBasedContract and StringBasedFunction.

Parameters:

contractId - an ID of the contract

contractArgument - an argument of the contract

functionId - an ID of the function

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(com.scalar.dl.genericcontracts.AssetType type,
                                                                        java.util.List<java.lang.String> keys)

Validates the specified asset in the ledger.

Parameters:

type - a type of the asset

keys - a list of keys that uniquely identify the asset

Returns:

LedgerValidationResult

Throws:

ClientException - if a request fails for some reason

validateLedger

public com.scalar.dl.ledger.model.LedgerValidationResult validateLedger(com.scalar.dl.genericcontracts.AssetType type,
                                                                        java.util.List<java.lang.String> keys,
                                                                        int startAge,
                                                                        int endAge)

Validates the specified asset between the specified ages in the ledger.

Parameters:

type - a type of the asset

keys - a list of keys that uniquely identify the asset

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