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 instance 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 Summary

Fields

Modifier and Type	Field	Description
protected Address	address	Current Address for this Client
protected HashMap<Long,CompletableFuture<Message>>	awaiting	Map of results awaiting completion.
protected AKeyPair	keyPair	Key pair for this Client
protected final Consumer<Message>	messageHandler	Result Consumer for messages received back from a client connection
protected Long	sequence	Sequence number for this client, or null if not yet known.
protected long	timeout

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	Convex(Address address, AKeyPair keyPair)

Method Summary

Modifier and Type	Method	Description
<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.
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.
abstract CompletableFuture<State>	acquireState()	Gets the consensus state from the remote Peer
protected CompletableFuture<Result>	awaitResult(long id, long timeout)	Method to start waiting for a complete result.
abstract void	close()	Disconnects the client from the network, releasing any connection resources.
static ConvexLocal	connect(Server server)	Connect to a local Server, with no address and keypair set
static ConvexLocal	connect(Server server, Address address, AKeyPair keyPair)	Connect to a local Server, using given address and keypair
static ConvexRemote	connect(InetSocketAddress hostAddress)	Creates an anonymous connection to a Peer, suitable for queries
static ConvexRemote	connect(InetSocketAddress peerAddress, Address address, AKeyPair keyPair)	Create a Convex client by connecting to the specified Peer using the given key pair
static ConvexRemote	connect(InetSocketAddress peerAddress, Address address, AKeyPair keyPair, AStore store)	Create a Convex client by connecting to the specified Peer using the given key pair and using a given store
CompletableFuture<Address>	createAccount(AccountKey publicKey)	Creates a new account with the given public key
Address	createAccountSync(AccountKey publicKey)	Creates a new account with the given public key
void	finalize()
AccountKey	getAccountKey()	Returns the current AccountKey for the client using the API.
AccountKey	getAccountKey(Address a)	Returns the current AccountKey for the specified address.
Address	getAddress()	Returns the current Address for the client using the API.
Long	getBalance()	Query the balance for the current account
Long	getBalance(Address address)
abstract InetSocketAddress	getHostAddress()	Gets the remote address for this Convex client instance
AKeyPair	getKeyPair()	Get the keypair for this Convex connection.
abstract Server	getLocalServer()	Gets the local Server instance, or null if not a local connection
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.
long	getSequence(Address addr)	Gets the current sequence number for an account, which is the sequence number of the last transaction observed for the Account.
protected boolean	isAutoSequence()	Determines if this Client is configured to automatically generate sequence numbers
abstract boolean	isConnected()	Checks if this Convex client instance has an open connection.
long	lookupSequence(Address origin)	Look up the sequence number for an account
protected void	maybeUpdateSequence(SignedData<ATransaction> signed)	Called after a transaction is submitted to update sequence (if possible)
SignedData<ATransaction>	prepareTransaction(ATransaction transaction)	Prepares a transaction for network submission - Sets origin account if needed - Sets sequence number (if autosequencing is enabled) - Signs transaction with current key pair
CompletableFuture<Result>	query(ACell query)	Submits a query to the Convex network, returning a Future once the query has been successfully queued.
abstract CompletableFuture<Result>	query(ACell query, Address address)	Submits a query to the Convex network, returning a Future once the query has been successfully queued.
CompletableFuture<Result>	query(String query)	Submits a query to the Convex network, returning a Future once the query has been successfully queued.
Result	querySync(ACell query)	Executes a query synchronously and waits for the Result
Result	querySync(ACell query, long timeoutMillis)	Executes a query synchronously and waits for the Result
Result	querySync(ACell query, Address address)	Executes a query synchronously and waits for the Result
Result	querySync(ACell query, Address address, long timeoutMillis)	Executes a query synchronously and waits for the Result
Result	querySync(String query)	Executes a query synchronously and waits for the Result
abstract CompletableFuture<Result>	requestChallenge(SignedData<ACell> data)	Request a challenge.
abstract CompletableFuture<Result>	requestStatus()	Submits a status request to the Convex network peer, returning a Future once the request has been successfully queued.
Result	requestStatusSync(long timeoutMillis)	Request status using a sync operation.
CompletableFuture<ACell>	resolve(String cnsName)	Attempts to resolve a CNS name
void	setAddress(Address address)	Sets the Address for this connection.
void	setAddress(Address address, AKeyPair kp)	Sets the Address and Keypair for this connection.
protected void	setAutoSequence(boolean autoSequence)	Configures auto-generation of sequence numbers
void	setHandler(Consumer<Message> handler)	Sets a handler for messages that are received but not otherwise processed (transaction/query results will be relayed instead to the appropriate handler )
void	setKeyPair(AKeyPair kp)
void	setNextSequence(long nextSequence)
void	setTimeout(long timeout)	Sets the default timeout for this Convex client instance.
<T extends ACell> SignedData<T>	signData(T value)	Signs a value on behalf of this client, using the currently assigned keypair.
abstract String	toString()
CompletableFuture<Result>	transact(ACell code)	Executes a transaction, compiling the given source code as an Invoke.
abstract CompletableFuture<Result>	transact(SignedData<ATransaction> signed)	Submits a signed transaction to the Convex network, returning a Future once the transaction has been successfully queued.
final CompletableFuture<Result>	transact(ATransaction transaction)	Submits a transaction to the Convex network, returning a future once the transaction has been successfully queued.
CompletableFuture<Result>	transact(String code)	Executes a transaction, compiling the given source code as an Invoke.
Result	transactSync(SignedData<ATransaction> transaction)	Submits a transaction synchronously to the Convex network, returning a Result
Result	transactSync(SignedData<ATransaction> transaction, long timeout)	Submits a signed transaction synchronously to the Convex network, returning a Result
Result	transactSync(ATransaction transaction)	Submits a transaction synchronously to the Convex network, returning a Result
Result	transactSync(ATransaction transaction, long timeout)	Submits a signed transaction synchronously to the Convex network, returning a Result
Result	transactSync(String code)	Executes a transaction, compiling the given source code as an Invoke.
CompletableFuture<Result>	transfer(Address target, long amount)	Submits a transfer transaction to the Convex network, returning a future once the transaction has been successfully queued.
Result	transferSync(Address target, long amount)	Submits a transfer transaction to the Convex network peer, and waits for confirmation of the result

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

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<Message>> awaiting

Map of results awaiting completion.

messageHandler

protected final Consumer<Message> messageHandler

Result Consumer for messages received back from a client connection

Constructor Details

Convex

protected Convex(Address address,
 AKeyPair keyPair)

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)

Sets a handler for messages that are received but not otherwise processed (transaction/query results will be relayed instead to the appropriate handler )

Parameters:

handler -

getSequence

public long getSequence()
                 throws IOException,
TimeoutException

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)

Throws:

TimeoutException

IOException

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

lookupSequence

public long lookupSequence(Address origin)
                    throws IOException,
TimeoutException

Look up the sequence number for an account

Parameters:

origin -

Returns:

Throws:

TimeoutException

IOException

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 final CompletableFuture<Result> transact(ATransaction transaction)
                                         throws IOException,
TimeoutException

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)

TimeoutException

prepareTransaction

public SignedData<ATransaction> prepareTransaction(ATransaction transaction)
                                            throws TimeoutException,
IOException

Prepares a transaction for network submission - Sets origin account if needed - Sets sequence number (if autosequencing is enabled) - Signs transaction with current key pair

Parameters:

transaction - Transaction to prepare

Returns:

Signed transaction ready to submit

Throws:

IOException - If an IO Exception occurs (most likely the connection is broken)

TimeoutException

transact

public CompletableFuture<Result> transact(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

transact

public CompletableFuture<Result> transact(ACell 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

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,
TimeoutException

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

TimeoutException

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

resolve

public CompletableFuture<ACell> resolve(String cnsName)
                                 throws IOException

Attempts to resolve a CNS name

Parameters:

cnsName - CNS name to resolve

Returns:

A Future for the resolved CNS value

Throws:

IOException - In case of IO failure

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 - In case of IO problem (connection is broken, send buffer 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:

query - Query to execute, as a Form or Op

timeoutMillis - Timeout to wait for query result. Will throw TimeoutException if not received in this time

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:

query - Query to execute, as a Form or Op

address - Address to use for the query

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:

query - Query to execute, as a Form or Op

address - Address to use for the query

timeoutMillis - Timeout to wait for query result. Will throw TimeoutException if not received in this time

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 AccountKey for the client using the API.

Returns:

AcountKey instance, or null if no keypair is set

getAccountKey

public AccountKey getAccountKey(Address a)

Returns the current AccountKey for the specified address. Performs a sync query

Returns:

AcountKey instance, or null if unavailable

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()
                throws IOException

Query the balance for the current account

Returns:

Long balance in Convex coins,

Throws:

IOException - If balance query fails due to IO

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

connect

public static ConvexLocal connect(Server server)

Connect to a local Server, with no address and keypair set

Parameters:

server - Server to connect to

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 default 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()

Get the keypair for this Convex connection.

Returns:

Keypair or null if not set

getLocalServer

public abstract Server getLocalServer()

Gets the local Server instance, or null if 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