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

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:

  • Method Details

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

    • 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.