Package convex.api

Class Convex

java.lang.Object
convex.api.Convex
public class Convex extends Object
Class representing the client API to the Convex network when connected directly using the binary protocol. This can be more efficient than using a REST API. An Object of the type Convex represents a stateful client connection to the Convex network that can issue transactions both synchronously and asynchronously. This can be used by both peers and JVM-based clients. "I'm doing a (free) operating system (just a hobby, won't be big and professional like gnu)" - Linus Torvalds

  • Field Details

    • keyPair

      protected AKeyPair keyPair
      Key pair for this Client

    • address

      protected Address address
      Current address for this Client

    • connection

      protected Connection connection
      Current Connection to a Peer, may be null or a closed connection.

    • sequence

      protected Long sequence
      Sequence number for this client, or null if not yet known

  • Method Details

    • connect

      public static Convex connect​(InetSocketAddress hostAddress) throws IOException, TimeoutException
      Creates an anonymous connection to a Peer, suitable for queries
      Parameters:
      hostAddress - Address of Peer
      Returns:
      New Convex client instance
      Throws:
      IOException - If IO Error occurs
      TimeoutException - If connection attempt times out

    • connect

      public static Convex connect​(InetSocketAddress peerAddress, Address address, AKeyPair keyPair) throws IOException, TimeoutException
      Create a Convex client by connecting to the specified Peer using the given key pair
      Parameters:
      peerAddress - Address of Peer
      address - Address of Account to use for Client
      keyPair - Key pair to use for client transactions
      Returns:
      New Convex client instance
      Throws:
      IOException - If connection fails
      TimeoutException - If connection attempt times out

    • connect

      public static Convex connect​(InetSocketAddress peerAddress, Address address, AKeyPair keyPair, AStore store) throws IOException, TimeoutException
      Create a Convex client by connecting to the specified Peer using the given key pair and using a given store
      Parameters:
      peerAddress - Address of Peer
      address - Address of Account to use for Client
      keyPair - Key pair to use for client transactions
      store - Store to use for this connection
      Returns:
      New Convex client instance
      Throws:
      IOException - If connection fails
      TimeoutException - If connection attempt times out

    • setAddress

      public void setAddress​(Address address)
      Sets the Address for this connection. This will be used by default for subsequent transactions and queries
      Parameters:
      address - Address to use

    • setAddress

      public void setAddress​(Address addr, AKeyPair kp)

    • setKeyPair

      public void setKeyPair​(AKeyPair kp)

    • setNextSequence

      public void setNextSequence​(long nextSequence)

    • setHandler

      public void setHandler​(Consumer<Message> handler)

    • getSequence

      public long getSequence()
      Gets the current sequence number for this Client, which is the sequence number of the last transaction observed for the current client's Account.
      Returns:
      Sequence number as a Long value, zero or positive

    • signData

      public <T extends ACell> SignedData<T> signData​(T value)
      Signs a value on behalf of this client.
      Type Parameters:
      T - Type of value to sign
      Parameters:
      value - Value to sign
      Returns:
      SignedData instance

    • getRemoteAddress

      public InetSocketAddress getRemoteAddress()
      Gets the Internet address of the currently connected remote
      Returns:
      Remote socket address

    • createAccountSync

      public Address createAccountSync​(AccountKey publicKey) throws TimeoutException, IOException
      Creates a new account with the given public key
      Parameters:
      publicKey - Public key to set for the new account
      Returns:
      Address of account created
      Throws:
      TimeoutException - If attempt times out
      IOException - If IO error occurs

    • createAccount

      public CompletableFuture<Address> createAccount​(AccountKey publicKey) throws TimeoutException, IOException
      Creates a new account with the given public key
      Parameters:
      publicKey - Public key to set for the new account
      Returns:
      Address of account created
      Throws:
      TimeoutException - If attempt times out
      IOException - If IO error occurs

    • isConnected

      public boolean isConnected()
      Checks if this Convex client instance has an open connection.
      Returns:
      true if connected, false otherwise

    • getConnection

      public Connection getConnection()
      Gets the underlying Connection instance for this Client. May be null if not connected.
      Returns:
      Connection instance or null

    • transact

      public CompletableFuture<Result> transact​(ATransaction transaction) throws IOException
      Submits a transaction to the Convex network, returning a future once the transaction has been successfully queued. Signs the transaction with the currently set key pair Should be thread safe as long as multiple clients do not attempt to submit transactions for the same account concurrently.
      Parameters:
      transaction - Transaction to execute
      Returns:
      A Future for the result of the transaction
      Throws:
      IOException - If the connection is broken, or the send buffer is full

    • transact

      public CompletableFuture<Result> transact​(SignedData<ATransaction> signed) throws IOException
      Submits a signed transaction to the Convex network, returning a future once the transaction has been successfully queued.
      Parameters:
      signed - Signed transaction to execute
      Returns:
      A Future for the result of the transaction
      Throws:
      IOException - If the connection is broken

    • transfer

      public CompletableFuture<Result> transfer​(Address target, long amount) throws IOException
      Submits a transfer transaction to the Convex network, returning a future once the transaction has been successfully queued.
      Parameters:
      target - Destination address for transfer
      amount - Amount of Convex Coins to transfer
      Returns:
      A Future for the result of the transaction
      Throws:
      IOException - If the connection is broken, or the send buffer is full

    • transferSync

      public Result transferSync​(Address target, long amount) throws IOException, TimeoutException
      Submits a transfer transaction to the Convex network peer, and waits for confirmation of the result
      Parameters:
      target - Destination address for transfer
      amount - Amount of Convex Coins to transfer
      Returns:
      Result of the transaction
      Throws:
      IOException - If the connection is broken, or the send buffer is full
      TimeoutException - If the transaction times out

    • transactSync

      public Result transactSync​(SignedData<ATransaction> transaction) throws TimeoutException, IOException
      Submits a transaction synchronously to the Convex network, returning a Result
      Parameters:
      transaction - Transaction to execute
      Returns:
      The result of the transaction
      Throws:
      IOException - If the connection is broken
      TimeoutException - If the attempt to transact with the network is not confirmed within a reasonable time

    • transactSync

      public Result transactSync​(ATransaction transaction) throws TimeoutException, IOException
      Submits a transaction synchronously to the Convex network, returning a Result
      Parameters:
      transaction - Transaction to execute
      Returns:
      The result of the transaction
      Throws:
      IOException - If the connection is broken
      TimeoutException - If the attempt to transact with the network is not confirmed within a reasonable time

    • transactSync

      public Result transactSync​(ATransaction transaction, long timeout) throws TimeoutException, IOException
      Submits a signed transaction synchronously to the Convex network, returning a Result
      Parameters:
      transaction - Transaction to execute
      timeout - Number of milliseconds for timeout
      Returns:
      The result of the transaction
      Throws:
      IOException - If the connection is broken
      TimeoutException - If the attempt to transact with the network is not confirmed by the specified timeout

    • transactSync

      public Result transactSync​(SignedData<ATransaction> transaction, long timeout) throws TimeoutException, IOException
      Submits a signed transaction synchronously to the Convex network, returning a Result
      Parameters:
      transaction - Transaction to execute
      timeout - Number of milliseconds for timeout
      Returns:
      The result of the transaction
      Throws:
      IOException - If the connection is broken
      TimeoutException - If the attempt to transact with the network is not confirmed by the specified timeout

    • query

      public Future<Result> query​(ACell query) throws IOException
      Submits a query to the Convex network, returning a Future once the query has been successfully queued.
      Parameters:
      query - Query to execute, as a Form or Op
      Returns:
      A Future for the result of the query
      Throws:
      IOException - If the connection is broken, or the send buffer is full

    • acquire

      public <T extends ACell> Future<T> acquire​(Hash hash)
      Attempts to acquire a complete persistent data structure for the given hash from the remote peer. Uses the store configured for the calling thread.
      Parameters:
      hash - Hash of value to acquire.
      Returns:
      Future for the cell being acquired

    • acquire

      public <T extends ACell> Future<T> acquire​(Hash hash, AStore store)
      Attempts to acquire a complete persistent data structure for the given hash from the remote peer. Uses the store provided as a destination.
      Parameters:
      hash - Hash of value to acquire.
      store - Store to acquire the persistent data to.
      Returns:
      Future for the Cell being acquired

    • requestStatus

      public Future<Result> requestStatus() throws IOException
      Submits a status request to the Convex network peer, returning a Future once the request has been successfully queued.
      Returns:
      A Future for the result of the requestStatus
      Throws:
      IOException - If the connection is broken, or the send buffer is full

    • requestChallenge

      public Future<Result> requestChallenge​(SignedData<ACell> data) throws IOException
      Request a challenge. This is request is made by any peer that needs to find out if another peer can be trusted.
      Parameters:
      data - Signed data to send to the peer for the challenge.
      Returns:
      A Future for the result of the requestChallenge
      Throws:
      IOException - if the connection fails.

    • query

      public Future<Result> query​(ACell query, Address address) throws IOException
      Submits a query to the Convex network, returning a Future once the query has been successfully queued.
      Parameters:
      query - Query to execute, as a Form or Op
      address - Address to use for the query
      Returns:
      A Future for the result of the query
      Throws:
      IOException - If the connection is broken, or the send buffer is full

    • querySync

      public Result querySync​(ACell query) throws TimeoutException, IOException
      Executes a query synchronously and waits for the Result
      Parameters:
      query - Query to execute. Map be a form or Op
      Returns:
      Result of synchronous query
      Throws:
      TimeoutException - If the synchronous request timed out
      IOException - In case of network error

    • querySync

      public Result querySync​(ACell query, long timeoutMillis) throws IOException, TimeoutException
      Executes a query synchronously and waits for the Result
      Parameters:
      timeoutMillis - Timeout to wait for query result. Will throw TimeoutException if not received in this time
      query - Query to execute, as a Form or Op
      Returns:
      Result of query
      Throws:
      TimeoutException - If the synchronous request timed out
      IOException - In case of network error

    • querySync

      public Result querySync​(ACell query, Address address) throws IOException, TimeoutException
      Executes a query synchronously and waits for the Result
      Parameters:
      address - Address to use for the query
      query - Query to execute, as a Form or Op
      Returns:
      Result of query
      Throws:
      TimeoutException - If the synchronous request timed out
      IOException - In case of network error

    • querySync

      public Result querySync​(ACell query, Address address, long timeoutMillis) throws TimeoutException, IOException
      Executes a query synchronously and waits for the Result
      Parameters:
      timeoutMillis - Timeout to wait for query result. Will throw TimeoutException if not received in this time
      address - Address to use for the query
      query - Query to execute, as a Form or Op
      Returns:
      Result of query
      Throws:
      TimeoutException - If the synchronous request timed out
      IOException - In case of network error

    • getAccountKey

      public AccountKey getAccountKey()
      Returns the current AcountKey for the client using the API.
      Returns:
      AcountKey instance

    • getAddress

      public Address getAddress()
      Returns the current Address for the client using the API.
      Returns:
      Address instance

    • close

      public void close()
      Disconnects the client from the network.

    • finalize

      public void finalize()
      Overrides:
      finalize in class Object

    • isAutoSequence

      protected boolean isAutoSequence()
      Determines if this Client is configured to automatically generate sequence numbers
      Returns:

    • setAutoSequence

      protected void setAutoSequence​(boolean autoSequence)
      Configures auto-generation of sequence numbers
      Parameters:
      autoSequence - true to enable auto-sequencing, false otherwise

    • getBalance

      public Long getBalance​(Address address) throws IOException
      Throws:
      IOException

    • connect

      public static Convex connect​(Server server) throws IOException, TimeoutException
      Connect to a local Server, using the Peer's address and keypair
      Parameters:
      server - Server to connect to
      Returns:
      New Client Connection
      Throws:
      TimeoutException - If connection attempt times out
      IOException - If IO error occurs

    • wrap

      public static Convex wrap​(Connection c)
      Wraps a connection as a Convex client instance
      Parameters:
      c - Connection to wrap
      Returns:
      New Convex client instance using underlying connection

    • acquireState

      public Future<State> acquireState() throws TimeoutException
      Throws:
      TimeoutException

    • closeButMaintainConnection

      public void closeButMaintainConnection()
      Close without affecting the connection