org.hyperledger.fabric.gateway

Interface Contract

public interface Contract

Represents a smart contract instance in a network. Applications should get a Contract instance from a Network using the getContract method.

The Contract allows applications to:

• Submit transactions that store state to the ledger using submitTransaction(String, String...).
• Evaluate transactions that query state from the ledger using evaluateTransaction(String, String...).
• Listen for new events emitted by the smart contract using addContractListener(Consumer).
• Replay previous events emitted by the smart contract using addContractListener(long, Consumer).

If more control over transaction invocation is required, such as including transient data, createTransaction(String) can be used to build a transaction request that is submitted to or evaluated by the smart contract.

See Also:

Developing Fabric Applications - Construct request

Method Summary

Modifier and Type	Method and Description
Consumer<ContractEvent>	addContractListener(Checkpointer checkpointer, Consumer<ContractEvent> listener) Add a listener to receive all contract events emitted by committed transactions with checkpointing.
Consumer<ContractEvent>	addContractListener(Checkpointer checkpointer, Consumer<ContractEvent> listener, Pattern eventNamePattern) Add a listener to receive contract events emitted by committed transactions with checkpointing.
Consumer<ContractEvent>	addContractListener(Checkpointer checkpointer, Consumer<ContractEvent> listener, String eventName) Add a listener to receive contract events emitted by committed transactions with checkpointing.
Consumer<ContractEvent>	addContractListener(Consumer<ContractEvent> listener) Add a listener to receive all contract events emitted by committed transactions.
Consumer<ContractEvent>	addContractListener(Consumer<ContractEvent> listener, Pattern eventNamePattern) Add a listener to receive contract events emitted by committed transactions.
Consumer<ContractEvent>	addContractListener(Consumer<ContractEvent> listener, String eventName) Add a listener to receive contract events emitted by committed transactions.
Consumer<ContractEvent>	addContractListener(long startBlock, Consumer<ContractEvent> listener) Add a listener to replay contract events emitted by committed transactions.
Consumer<ContractEvent>	addContractListener(long startBlock, Consumer<ContractEvent> listener, Pattern eventNamePattern) Add a listener to replay contract events emitted by committed transactions.
Consumer<ContractEvent>	addContractListener(long startBlock, Consumer<ContractEvent> listener, String eventName) Add a listener to replay contract events emitted by committed transactions.
Transaction	createTransaction(String name) Create an object representing a specific invocation of a transaction function implemented by this contract, and provides more control over the transaction invocation.
byte[]	evaluateTransaction(String name, String... args) Evaluate a transaction function and return its results.
void	removeContractListener(Consumer<ContractEvent> listener) Remove a previously registered contract listener.
byte[]	submitTransaction(String name, String... args) Submit a transaction to the ledger.

Method Detail

createTransaction

Transaction createTransaction(String name)

Create an object representing a specific invocation of a transaction function implemented by this contract, and provides more control over the transaction invocation. A new transaction object must be created for each transaction invocation.

Parameters:

name - Transaction function name.

Returns:

A transaction object.

submitTransaction

byte[] submitTransaction(String name,
                         String... args)
                  throws ContractException,
                         TimeoutException,
                         InterruptedException

Submit a transaction to the ledger. The transaction function name will be evaluated on the endorsing peers and then submitted to the ordering service for committing to the ledger. This function is equivalent to calling createTransaction(name).submit().

Parameters:

name - Transaction function name.

args - Transaction function arguments.

Returns:

Payload response from the transaction function.

Throws:

ContractException - if the transaction is rejected.

TimeoutException - If the transaction was successfully submitted to the orderer but timed out before a commit event was received from peers.

InterruptedException - if the current thread is interrupted while waiting.

GatewayRuntimeException - if an underlying infrastructure failure occurs.

See Also:

Developing Fabric Applications - Submit transaction

evaluateTransaction

byte[] evaluateTransaction(String name,
                           String... args)
                    throws ContractException

Evaluate a transaction function and return its results. The transaction function name will be evaluated on the endorsing peers but the responses will not be sent to the ordering service and hence will not be committed to the ledger. This is used for querying the world state. This function is equivalent to calling createTransaction(name).evaluate().

Parameters:

name - Transaction function name.

args - Transaction function arguments.

Returns:

Payload response from the transaction function.

Throws:

ContractException - if no peers are reachable or an error response is returned.

addContractListener

Consumer<ContractEvent> addContractListener(Consumer<ContractEvent> listener)

Add a listener to receive all contract events emitted by committed transactions.

Parameters:

listener - A contract listener.

Returns:

The contract listener argument.

addContractListener

Consumer<ContractEvent> addContractListener(Consumer<ContractEvent> listener,
                                            String eventName)

Add a listener to receive contract events emitted by committed transactions. The listener is only notified of events with exactly the given name.

Parameters:

listener - A contract listener.

eventName - Event name.

Returns:

The contract listener argument.

addContractListener

Consumer<ContractEvent> addContractListener(Consumer<ContractEvent> listener,
                                            Pattern eventNamePattern)

Add a listener to receive contract events emitted by committed transactions. The listener is only notified of events with names that entirely match the given pattern.

Parameters:

listener - A contract listener.

eventNamePattern - Event name pattern.

Returns:

The contract listener argument.

addContractListener

Consumer<ContractEvent> addContractListener(Checkpointer checkpointer,
                                            Consumer<ContractEvent> listener)
                                     throws IOException

Add a listener to receive all contract events emitted by committed transactions with checkpointing. Re-adding a listener with the same checkpointer on subsequent application invocations will resume listening from the previous block and transaction position.

Parameters:

checkpointer - Checkpointer to persist block and transaction position.

listener - A contract listener.

Returns:

The contract listener argument.

Throws:

IOException - if an error occurs establishing checkpointing.

GatewayRuntimeException - if an underlying infrastructure failure occurs.

addContractListener

Consumer<ContractEvent> addContractListener(Checkpointer checkpointer,
                                            Consumer<ContractEvent> listener,
                                            String eventName)
                                     throws IOException

Add a listener to receive contract events emitted by committed transactions with checkpointing. The listener is only notified of events with names that exactly match the given pattern. Re-adding a listener with the same checkpointer on subsequent application invocations will resume listening from the previous block and transaction position.

Parameters:

checkpointer - Checkpointer to persist block and transaction position.

listener - A contract listener.

eventName - Event name.

Returns:

The contract listener argument.

Throws:

IOException - if an error occurs establishing checkpointing.

GatewayRuntimeException - if an underlying infrastructure failure occurs.

addContractListener

Consumer<ContractEvent> addContractListener(Checkpointer checkpointer,
                                            Consumer<ContractEvent> listener,
                                            Pattern eventNamePattern)
                                     throws IOException

Add a listener to receive contract events emitted by committed transactions with checkpointing. The listener is only notified of events with names that entirely match the given pattern. Re-adding a listener with the same checkpointer on subsequent application invocations will resume listening from the previous block and transaction position.

Parameters:

checkpointer - Checkpointer to persist block and transaction position.

listener - A contract listener.

eventNamePattern - Event name pattern.

Returns:

The contract listener argument.

Throws:

IOException - if an error occurs establishing checkpointing.

GatewayRuntimeException - if an underlying infrastructure failure occurs.

addContractListener

Consumer<ContractEvent> addContractListener(long startBlock,
                                            Consumer<ContractEvent> listener)

Add a listener to replay contract events emitted by committed transactions.

Parameters:

startBlock - The number of the block from which events should be replayed.

listener - A contract listener.

Returns:

The contract listener argument.

Throws:

GatewayRuntimeException - if an underlying infrastructure failure occurs.

addContractListener

Consumer<ContractEvent> addContractListener(long startBlock,
                                            Consumer<ContractEvent> listener,
                                            String eventName)

Add a listener to replay contract events emitted by committed transactions. The listener is only notified of events with names that exactly match the given pattern.

Parameters:

startBlock - The number of the block from which events should be replayed.

listener - A contract listener.

eventName - Event name.

Returns:

The contract listener argument.

Throws:

GatewayRuntimeException - if an underlying infrastructure failure occurs.

addContractListener

Consumer<ContractEvent> addContractListener(long startBlock,
                                            Consumer<ContractEvent> listener,
                                            Pattern eventNamePattern)

Add a listener to replay contract events emitted by committed transactions. The listener is only notified of events with names that entirely match the given pattern.

Parameters:

startBlock - The number of the block from which events should be replayed.

listener - A contract listener.

eventNamePattern - Event name pattern.

Returns:

The contract listener argument.

Throws:

GatewayRuntimeException - if an underlying infrastructure failure occurs.

removeContractListener

void removeContractListener(Consumer<ContractEvent> listener)

Remove a previously registered contract listener.

Parameters:

listener - A contract listener.