Package com.exonum.client

Interface ExonumClient

public interface ExonumClient
Main interface for Exonum Light client. Provides a convenient way for interaction with Exonum framework APIs. All the methods of the interface work in a blocking way, i.e., invoke underlying request immediately, and block until the response can be processed or an error occurs. In case the thread is interrupted, the blocked methods will complete exceptionally.

Implementations of this interface are required to be thread-safe.

  • Method Details

    • submitTransaction

      HashCode submitTransaction​(TransactionMessage tx)
      Submits the transaction message to an Exonum node.
      Returns:
      transaction message hash
      Throws:
      RuntimeException - if the client is unable to submit the transaction (e.g., in case of connectivity problems)

    • getUnconfirmedTransactionsCount

      int getUnconfirmedTransactionsCount()
      Returns a number of unconfirmed transactions which are currently located in the unconfirmed transactions pool and are waiting for acceptance to a block.
      Throws:
      RuntimeException - if the client is unable to complete a request (e.g., in case of connectivity problems)

    • healthCheck

      HealthCheckInfo healthCheck()
      Returns the node health check information.
      Throws:
      RuntimeException - if the client is unable to complete a request (e.g., in case of connectivity problems)

    • getUserAgentInfo

      String getUserAgentInfo()
      Returns string containing information about Exonum, Rust and OS version.
      Throws:
      RuntimeException - if the client is unable to complete a request (e.g., in case of connectivity problems)

    • getTransaction

      Optional<TransactionResponse> getTransaction​(HashCode id)
      Returns the information about the transaction; or Optional.empty() if the requested transaction is not found.
      Parameters:
      id - transaction message hash
      Throws:
      RuntimeException - if the client is unable to complete a request (e.g., in case of connectivity problems)

    • getBlockchainHeight

      long getBlockchainHeight()
      Returns the blockchain height which is the height of the latest committed block in the blockchain. The block height is a distance between the last block and the "genesis", or initial, block. Therefore, the blockchain height is equal to the number of blocks plus one.
      Throws:
      RuntimeException - if the client is unable to complete a request (e.g., in case of connectivity problems)

    • getBlockByHeight

      BlockResponse getBlockByHeight​(long height)
      Returns the information about the block with transaction hashes included at this block.
      Parameters:
      height - blockchain height starting from 0 (genesis block)
      Returns:
      block information response
      Throws:
      IllegalArgumentException - if the given height is negative; or greater than the actual blockchain height
      RuntimeException - if the client is unable to complete a request (e.g., in case of connectivity problems)

    • getBlocks

      List<Block> getBlocks​(long fromHeight, long toHeight, BlockFilteringOption blockFilter, BlockTimeOption timeOption)
      Returns blockchain blocks in the requested closed range. The blocks are returned in ascending order by their height.
      Parameters:
      fromHeight - the height of the first block to include. Must be non-negative
      toHeight - the height of the last block to include. Must be greater than or equal to fromHeight and less than or equal to the blockchain height.
      blockFilter - controls whether to skip blocks with no transactions
      timeOption - controls whether to include the block commit time
      Returns:
      blocks in the requested range
      Throws:
      IllegalArgumentException - if fromHeight or toHeight are not valid: out of range [0, blockchainHeight]; fromHeight > toHeight
      RuntimeException - if the client is unable to complete a request (e.g., in case of connectivity problems)

    • getLastBlocks

      BlocksRange getLastBlocks​(int size, BlockFilteringOption blockFilter, BlockTimeOption timeOption)
      Returns the range of the most recent blockchain blocks in ascending order by their height. More precisely, returns the blocks in the closed range [max(0, blockchainHeight - size + 1), blockchainHeight] of size max(blockchainHeight + 1, size).
      Parameters:
      size - the size of the range. If it exceeds the number of blocks in the blockchain, this method will return all blocks (blockchainHeight + 1)
      blockFilter - controls whether to skip blocks with no transactions. If filtering is applied, the actual number of blocks may be smaller than size; but the range of blocks will not be extended beyond blockchainHeight - size + 1. If a certain number of non-empty blocks is needed (not a certain range), use findNonEmptyBlocks(int, BlockTimeOption)
      timeOption - controls whether to include the block commit time
      Returns:
      blocks information response
      Throws:
      RuntimeException - if the client is unable to complete a request (e.g., in case of connectivity problems)
      IllegalArgumentException - if size is non-positive
      See Also:
      findNonEmptyBlocks(int, BlockTimeOption)

    • findNonEmptyBlocks

      List<Block> findNonEmptyBlocks​(int numBlocks, BlockTimeOption timeOption)
      Returns up to the given number of the most recent non-empty blocks in ascending order by their height. The search range is not limited, i.e., spans the whole blockchain.
      Parameters:
      numBlocks - the maximum number of blocks to return. Must be positive. If the number of non-empty blocks in the blockchain is less than numBlocks, all such blocks will be returned
      timeOption - controls whether to include the block commit time
      Returns:
      a list of the most recent non-empty blocks
      Throws:
      RuntimeException - if the client is unable to complete a request (e.g., in case of connectivity problems)
      IllegalArgumentException - if numBlocks is non-positive
      See Also:
      getLastBlocks(int, BlockFilteringOption, BlockTimeOption), BlockFilteringOption.SKIP_EMPTY

    • getLastBlock

      Block getLastBlock()
      Returns the last block in the blockchain.
      Throws:
      RuntimeException - if the client is unable to complete a request (e.g., in case of connectivity problems)

    • getLastNonEmptyBlock

      Optional<Block> getLastNonEmptyBlock()
      Returns the last block in the blockchain which contains transactions; or Optional.empty() if there are no blocks with transactions in the blockchain.
      Throws:
      RuntimeException - if the client is unable to complete a request (e.g., in case of connectivity problems)

    • findServiceInfo

      Optional<ServiceInstanceInfo> findServiceInfo​(String serviceName)
      Returns the service info of a started service instance with a given name; or Optional.empty() if there is no service instance with such name.
      Parameters:
      serviceName - the name of a service instance

    • getServiceInfoList

      List<ServiceInstanceInfo> getServiceInfoList()
      Returns information on all started service instances.
      See Also:
      findServiceInfo(java.lang.String)

    • newBuilder

      static ExonumClient.Builder newBuilder()
      Returns Exonum client builder.