Package convex.api

Class Convex

java.lang.Object
convex.api.Convex
Direct Known Subclasses:
ConvexLocal, ConvexRemote
public abstract class Convex extends Object
Class representing a client API to the Convex network. 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

    • timeout

      protected long timeout

    • keyPair

      protected AKeyPair keyPair
      Key pair for this Client

    • address

      protected Address address
      Current Address for this Client

    • sequence

      protected Long sequence
      Sequence number for this client, or null if not yet known. Used to number new transactions if not otherwise specified.

    • awaiting

      protected HashMap<Long,CompletableFuture<Result>> awaiting
      Map of results awaiting completion.

    • internalHandler

      protected final Consumer<Message> internalHandler
      Result Consumer for messages received back from a client connection

  • Constructor Details

  • Method Details

    • connect

      public static ConvexRemote 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 ConvexRemote 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 due to IO error
      TimeoutException - If connection attempt times out

    • connect

      public static ConvexRemote 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 due to IO error
      TimeoutException - If connection attempt times out

    • setAddress

      public void setAddress(Address address)
      Sets the Address for this connection. This will be used for subsequent transactions and queries. User should also set a new keypair if a different keypair is required for the new Address.
      Parameters:
      address - Address to use

    • setAddress

      public void setAddress(Address address, AKeyPair kp)
      Sets the Address and Keypair for this connection. This will be used for subsequent transactions and queries.
      Parameters:
      address - Address to use
      kp - Keypair to use for the given Address

    • 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. Will attempt to acquire the sequence number from the network if not known. The next valid sequence number will be one higher than the result.
      Returns:
      Sequence number as a Long value (zero or positive)

    • getSequence

      public long getSequence(Address addr) throws TimeoutException, IOException
      Gets the current sequence number for an account, which is the sequence number of the last transaction observed for the Account. Will attempt to acquire the sequence number from the network if not known.
      Parameters:
      addr - Address for which to query the sequence number
      Returns:
      Sequence number as a Long value (zero or positive)
      Throws:
      IOException - If an IO error occurs
      TimeoutException - If the request times out

    • maybeUpdateSequence

      protected void maybeUpdateSequence(SignedData<ATransaction> signed)
      Called after a transaction is submitted to update sequence (if possible)
      Parameters:
      value -

    • signData

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

    • 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 abstract boolean isConnected()
      Checks if this Convex client instance has an open connection.
      Returns:
      true if connected, false otherwise

    • 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. May block briefly if the send buffer is full.
      Parameters:
      transaction - Transaction to execute
      Returns:
      A Future for the result of the transaction
      Throws:
      IOException - If an IO Exception occurs (most likely the connection is broken)

    • transact

      public CompletableFuture<Result> transact(String code) throws IOException
      Executes a transaction, compiling the given source code as an Invoke.
      Parameters:
      code - Code to execute
      Returns:
      A Future for the result of the transaction
      Throws:
      IOException - If the connection is broken, or the send buffer is full

    • transactSync

      public Result transactSync(String code) throws IOException, TimeoutException
      Executes a transaction, compiling the given source code as an Invoke.
      Parameters:
      code - Code to execute
      Returns:
      A Future for the result of the transaction
      Throws:
      IOException - If the connection is broken, or the send buffer is full
      TimeoutException - If the transaction times out

    • transact

      public abstract 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. Updates cached sequence number on best effort basis.
      Parameters:
      signed - Signed transaction to execute
      Returns:
      A Future for the result of the transaction
      Throws:
      IOException - If the connection is broken or send buffer is full

    • 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, if received
      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 CompletableFuture<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

    • query

      public CompletableFuture<Result> query(String 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 String containing one or more forms
      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> CompletableFuture<T> acquire(Hash hash)
      Attempts to asynchronously acquire a complete persistent data structure for the given hash from the remote peer. Uses the current store configured for the calling thread.
      Parameters:
      hash - Hash of value to acquire.
      Returns:
      Future for the cell being acquired

    • acquire

      public abstract <T extends ACell> CompletableFuture<T> acquire(Hash hash, AStore store)
      Attempts to acquire a complete persistent data structure for the given hash from the connected 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. May fail exceptionally or timeout if the given data cannot be acquired (most likely missing from the peer's store)

    • requestStatusSync

      public Result requestStatusSync(long timeoutMillis) throws IOException, TimeoutException
      Request status using a sync operation. This request will automatically get any missing data with the status request
      Parameters:
      timeoutMillis - Milliseconds to wait for request timeout
      Returns:
      Status Vector from target Peer
      Throws:
      IOException - If an IO Error occurs
      TimeoutException - If operation times out

    • requestStatus

      public abstract CompletableFuture<Result> requestStatus()
      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

    • awaitResult

      protected CompletableFuture<Result> awaitResult(long id, long timeout)
      Method to start waiting for a complete result. Should be called with lock on `awaiting` map to prevent risk of missing results before it is called.
      Parameters:
      id - ID of result message to await
      Returns:

    • requestChallenge

      public abstract CompletableFuture<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 abstract CompletableFuture<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(String query) throws TimeoutException, IOException
      Executes a query synchronously and waits for the Result
      Parameters:
      query - Query to execute, as a String that contains one or more readable forms. Multiple forms will be wrapped in a `do` block
      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 abstract void close()
      Disconnects the client from the network, releasing any connection resources.

    • 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 ConvexLocal connect(Server server, Address address, AKeyPair keyPair)
      Connect to a local Server, using given address and keypair
      Parameters:
      server - Server to connect to
      address - Address to use
      keyPair - Keypair to use
      Returns:
      New Client Connection

    • acquireState

      public abstract CompletableFuture<State> acquireState() throws TimeoutException
      Gets the consensus state from the remote Peer
      Returns:
      Future for consensus state
      Throws:
      TimeoutException - If initial status request times out

    • setTimeout

      public void setTimeout(long timeout)
      Sets the timeout for this Convex client instance.
      Parameters:
      timeout - timeout in milliseconds

    • toString

      public abstract String toString()
      Overrides:
      toString in class Object

    • getKeyPair

      public AKeyPair getKeyPair()

    • getLocalServer

      public abstract Server getLocalServer()
      Gets the local Server instance, or null is not a local connection
      Returns:
      Server instance (or null)

    • getHostAddress

      public abstract InetSocketAddress getHostAddress()
      Gets the remote address for this Convex client instance
      Returns:
      Socket address