com.aerospike.client.async
Class AsyncClient

java.lang.Object
  com.aerospike.client.AerospikeClient
      com.aerospike.client.async.AsyncClient

public class AsyncClient
extends AerospikeClient

Asynchronous Aerospike client.

Your application uses this class to perform asynchronous database operations such as writing and reading records, and selecting sets of records. Write operations include specialized functionality such as append/prepend and arithmetic addition.

This client is thread-safe. One client instance should be used per cluster. Multiple threads should share this cluster instance.

Each record may have multiple bins, unless the Aerospike server nodes are configured as "single-bin". In "multi-bin" mode, partial records may be written or read by specifying the relevant subset of bins.

Constructor Summary

AsyncClient(AsyncClientPolicy policy, Host... hosts)
Initialize asynchronous client with suitable hosts to seed the cluster map.

AsyncClient(AsyncClientPolicy policy, String hostname, int port)
Initialize asynchronous client.

AsyncClient(String hostname, int port)
Initialize asynchronous client.

Method Summary

void	add(WritePolicy policy, WriteListener listener, Key key, Bin... bins) Asynchronously add integer bin values to existing record bin values.
void	append(WritePolicy policy, WriteListener listener, Key key, Bin... bins) Asynchronously append bin string values to existing record bin values.
void	delete(WritePolicy policy, DeleteListener listener, Key key) Asynchronously delete record for specified key.
void	exists(Policy policy, ExistsArrayListener listener, Key[] keys) Asynchronously check if multiple record keys exist in one batch call.
void	exists(Policy policy, ExistsListener listener, Key key) Asynchronously determine if a record key exists.
void	exists(Policy policy, ExistsSequenceListener listener, Key[] keys) Asynchronously check if multiple record keys exist in one batch call.
void	get(Policy policy, RecordArrayListener listener, Key[] keys) Asynchronously read multiple records for specified keys in one batch call.
void	get(Policy policy, RecordArrayListener listener, Key[] keys, String... binNames) Asynchronously read multiple record headers and bins for specified keys in one batch call.
void	get(Policy policy, RecordListener listener, Key key) Asynchronously read entire record for specified key.
void	get(Policy policy, RecordListener listener, Key key, String... binNames) Asynchronously read record header and bins for specified key.
void	get(Policy policy, RecordSequenceListener listener, Key[] keys) Asynchronously read multiple records for specified keys in one batch call.
void	get(Policy policy, RecordSequenceListener listener, Key[] keys, String... binNames) Asynchronously read multiple record headers and bins for specified keys in one batch call.
void	getHeader(Policy policy, RecordArrayListener listener, Key[] keys) Asynchronously read multiple record header data for specified keys in one batch call.
void	getHeader(Policy policy, RecordListener listener, Key key) Asynchronously read record generation and expiration only for specified key.
void	getHeader(Policy policy, RecordSequenceListener listener, Key[] keys) Asynchronously read multiple record header data for specified keys in one batch call.
void	operate(WritePolicy policy, RecordListener listener, Key key, Operation... operations) Asynchronously perform multiple read/write operations on a single key in one batch call.
void	prepend(WritePolicy policy, WriteListener listener, Key key, Bin... bins) Asynchronously prepend bin string values to existing record bin values.
void	put(WritePolicy policy, WriteListener listener, Key key, Bin... bins) Asynchronously write record bin(s).
void	scanAll(ScanPolicy policy, RecordSequenceListener listener, String namespace, String setName, String... binNames) Asynchronously read all records in specified namespace and set.
void	touch(WritePolicy policy, WriteListener listener, Key key) Asynchronously create record if it does not already exist.

Methods inherited from class com.aerospike.client.AerospikeClient

add, append, close, createIndex, delete, dropIndex, execute, execute, exists, exists, get, get, get, get, getHeader, getHeader, getLargeList, getLargeMap, getLargeSet, getLargeStack, getNodeNames, getNodes, isConnected, operate, prepend, put, query, queryAggregate, register, scanAll, scanNode, scanNode, touch

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AsyncClient

public AsyncClient(String hostname,
                   int port)
            throws AerospikeException

Initialize asynchronous client. If the host connection succeeds, the client will:

- Add host to the cluster map
- Request host's list of other nodes in cluster
- Add these nodes to cluster map

If the connection succeeds, the client is ready to process database requests. If the connection fails, the cluster will remain in a disconnected state until the server is activated.

Parameters:

hostname - host name

port - host port

Throws:

AerospikeException - if host connection fails

AsyncClient

public AsyncClient(AsyncClientPolicy policy,
                   String hostname,
                   int port)
            throws AerospikeException

Initialize asynchronous client. The client policy is used to set defaults and size internal data structures. If the host connection succeeds, the client will:

- Add host to the cluster map
- Request host's list of other nodes in cluster
- Add these nodes to cluster map

If the connection succeeds, the client is ready to process database requests. If the connection fails and the policy's failOnInvalidHosts is true, a connection exception will be thrown. Otherwise, the cluster will remain in a disconnected state until the server is activated.

Parameters:

policy - client configuration parameters, pass in null for defaults

hostname - host name

port - host port

Throws:

AerospikeException - if host connection fails

AsyncClient

public AsyncClient(AsyncClientPolicy policy,
                   Host... hosts)
            throws AerospikeException

Initialize asynchronous client with suitable hosts to seed the cluster map. The client policy is used to set defaults and size internal data structures. For each host connection that succeeds, the client will:

- Add host to the cluster map
- Request host's list of other nodes in cluster
- Add these nodes to cluster map

In most cases, only one host is necessary to seed the cluster. The remaining hosts are added as future seeds in case of a complete network failure.

If one connection succeeds, the client is ready to process database requests. If all connections fail and the policy's failIfNotConnected is true, a connection exception will be thrown. Otherwise, the cluster will remain in a disconnected state until the server is activated.

Parameters:

policy - client configuration parameters, pass in null for defaults

hosts - array of potential hosts to seed the cluster

Throws:

AerospikeException - if all host connections fail

Method Detail

put

public final void put(WritePolicy policy,
                      WriteListener listener,
                      Key key,
                      Bin... bins)
               throws AerospikeException

Asynchronously write record bin(s). This method schedules the put command with a channel selector and returns. Another thread will process the command and send the results to the listener.

The policy specifies the transaction timeout, record expiration and how the transaction is handled when the record already exists.

Parameters:

policy - write configuration parameters, pass in null for defaults

listener - where to send results, pass in null for fire and forget

key - unique record identifier

bins - array of bin name/value pairs

Throws:

AerospikeException - if queue is full

append

public final void append(WritePolicy policy,
                         WriteListener listener,
                         Key key,
                         Bin... bins)
                  throws AerospikeException

Asynchronously append bin string values to existing record bin values. This method schedules the append command with a channel selector and returns. Another thread will process the command and send the results to the listener.

The policy specifies the transaction timeout, record expiration and how the transaction is handled when the record already exists. This call only works for string values.

Parameters:

policy - write configuration parameters, pass in null for defaults

listener - where to send results, pass in null for fire and forget

key - unique record identifier

bins - array of bin name/value pairs

Throws:

AerospikeException - if queue is full

prepend

public final void prepend(WritePolicy policy,
                          WriteListener listener,
                          Key key,
                          Bin... bins)
                   throws AerospikeException

Asynchronously prepend bin string values to existing record bin values. This method schedules the prepend command with a channel selector and returns. Another thread will process the command and send the results to the listener.

The policy specifies the transaction timeout, record expiration and how the transaction is handled when the record already exists. This call works only for string values.

Parameters:

policy - write configuration parameters, pass in null for defaults

listener - where to send results, pass in null for fire and forget

key - unique record identifier

bins - array of bin name/value pairs

Throws:

AerospikeException - if queue is full

add

public final void add(WritePolicy policy,
                      WriteListener listener,
                      Key key,
                      Bin... bins)
               throws AerospikeException

Asynchronously add integer bin values to existing record bin values. This method schedules the add command with a channel selector and returns. Another thread will process the command and send the results to the listener.

The policy specifies the transaction timeout, record expiration and how the transaction is handled when the record already exists. This call only works for integer values.

Parameters:

policy - write configuration parameters, pass in null for defaults

listener - where to send results, pass in null for fire and forget

key - unique record identifier

bins - array of bin name/value pairs

Throws:

AerospikeException - if queue is full

delete

public final void delete(WritePolicy policy,
                         DeleteListener listener,
                         Key key)
                  throws AerospikeException

Asynchronously delete record for specified key. This method schedules the delete command with a channel selector and returns. Another thread will process the command and send the results to the listener.

The policy specifies the transaction timeout.

Parameters:

policy - delete configuration parameters, pass in null for defaults

listener - where to send results, pass in null for fire and forget

key - unique record identifier

Throws:

AerospikeException - if queue is full

touch

public final void touch(WritePolicy policy,
                        WriteListener listener,
                        Key key)
                 throws AerospikeException

Asynchronously create record if it does not already exist. If the record exists, the record's time to expiration will be reset to the policy's expiration.

This method schedules the touch command with a channel selector and returns. Another thread will process the command and send the results to the listener.

Parameters:

policy - write configuration parameters, pass in null for defaults

listener - where to send results, pass in null for fire and forget

key - unique record identifier

Throws:

AerospikeException - if queue is full

exists

public final void exists(Policy policy,
                         ExistsListener listener,
                         Key key)
                  throws AerospikeException

Asynchronously determine if a record key exists. This method schedules the exists command with a channel selector and returns. Another thread will process the command and send the results to the listener.

The policy can be used to specify timeouts.

Parameters:

policy - generic configuration parameters, pass in null for defaults

listener - where to send results

key - unique record identifier

Throws:

AerospikeException - if queue is full

exists

public final void exists(Policy policy,
                         ExistsArrayListener listener,
                         Key[] keys)
                  throws AerospikeException

Asynchronously check if multiple record keys exist in one batch call. This method schedules the exists command with a channel selector and returns. Another thread will process the command and send the results to the listener in a single call.

The policy can be used to specify timeouts.

Parameters:

policy - generic configuration parameters, pass in null for defaults

listener - where to send results

keys - array of unique record identifiers

Throws:

AerospikeException - if queue is full

exists

public final void exists(Policy policy,
                         ExistsSequenceListener listener,
                         Key[] keys)
                  throws AerospikeException

Asynchronously check if multiple record keys exist in one batch call. This method schedules the exists command with a channel selector and returns. Another thread will process the command and send the results to the listener in multiple unordered calls.

The policy can be used to specify timeouts.

Parameters:

policy - generic configuration parameters, pass in null for defaults

listener - where to send results

keys - array of unique record identifiers

Throws:

AerospikeException - if queue is full

get

public final void get(Policy policy,
                      RecordListener listener,
                      Key key)
               throws AerospikeException

Asynchronously read entire record for specified key. This method schedules the get command with a channel selector and returns. Another thread will process the command and send the results to the listener.

The policy can be used to specify timeouts.

Parameters:

policy - generic configuration parameters, pass in null for defaults

listener - where to send results

key - unique record identifier

Throws:

AerospikeException - if queue is full

get

public final void get(Policy policy,
                      RecordListener listener,
                      Key key,
                      String... binNames)
               throws AerospikeException

Asynchronously read record header and bins for specified key. This method schedules the get command with a channel selector and returns. Another thread will process the command and send the results to the listener.

The policy can be used to specify timeouts.

Parameters:

policy - generic configuration parameters, pass in null for defaults

listener - where to send results

key - unique record identifier

binNames - bins to retrieve

Throws:

AerospikeException - if queue is full

getHeader

public final void getHeader(Policy policy,
                            RecordListener listener,
                            Key key)
                     throws AerospikeException

Asynchronously read record generation and expiration only for specified key. Bins are not read. This method schedules the get command with a channel selector and returns. Another thread will process the command and send the results to the listener.

The policy can be used to specify timeouts.

Parameters:

policy - generic configuration parameters, pass in null for defaults

listener - where to send results

key - unique record identifier

Throws:

AerospikeException - if queue is full

get

public final void get(Policy policy,
                      RecordArrayListener listener,
                      Key[] keys)
               throws AerospikeException

Asynchronously read multiple records for specified keys in one batch call. This method schedules the get command with a channel selector and returns. Another thread will process the command and send the results to the listener in a single call.

If a key is not found, the record will be null. The policy can be used to specify timeouts.

Parameters:

policy - generic configuration parameters, pass in null for defaults

listener - where to send results

keys - array of unique record identifiers

Throws:

AerospikeException - if queue is full

get

public final void get(Policy policy,
                      RecordSequenceListener listener,
                      Key[] keys)
               throws AerospikeException

Asynchronously read multiple records for specified keys in one batch call. This method schedules the get command with a channel selector and returns. Another thread will process the command and send the results to the listener in multiple unordered calls.

If a key is not found, the record will be null. The policy can be used to specify timeouts.

Parameters:

policy - generic configuration parameters, pass in null for defaults

listener - where to send results

keys - array of unique record identifiers

Throws:

AerospikeException - if queue is full

get

public final void get(Policy policy,
                      RecordArrayListener listener,
                      Key[] keys,
                      String... binNames)
               throws AerospikeException

Asynchronously read multiple record headers and bins for specified keys in one batch call. This method schedules the get command with a channel selector and returns. Another thread will process the command and send the results to the listener in a single call.

If a key is not found, the record will be null. The policy can be used to specify timeouts.

Parameters:

policy - generic configuration parameters, pass in null for defaults

listener - where to send results

keys - array of unique record identifiers

binNames - array of bins to retrieve

Throws:

AerospikeException - if queue is full

get

public final void get(Policy policy,
                      RecordSequenceListener listener,
                      Key[] keys,
                      String... binNames)
               throws AerospikeException

Asynchronously read multiple record headers and bins for specified keys in one batch call. This method schedules the get command with a channel selector and returns. Another thread will process the command and send the results to the listener in multiple unordered calls.

If a key is not found, the record will be null. The policy can be used to specify timeouts.

Parameters:

policy - generic configuration parameters, pass in null for defaults

listener - where to send results

keys - array of unique record identifiers

binNames - array of bins to retrieve

Throws:

AerospikeException - if queue is full

getHeader

public final void getHeader(Policy policy,
                            RecordArrayListener listener,
                            Key[] keys)
                     throws AerospikeException

Asynchronously read multiple record header data for specified keys in one batch call. This method schedules the get command with a channel selector and returns. Another thread will process the command and send the results to the listener in a single call.

If a key is not found, the record will be null. The policy can be used to specify timeouts.

Parameters:

policy - generic configuration parameters, pass in null for defaults

listener - where to send results

keys - array of unique record identifiers

Throws:

AerospikeException - if queue is full

getHeader

public final void getHeader(Policy policy,
                            RecordSequenceListener listener,
                            Key[] keys)
                     throws AerospikeException

Asynchronously read multiple record header data for specified keys in one batch call. This method schedules the get command with a channel selector and returns. Another thread will process the command and send the results to the listener in multiple unordered calls.

If a key is not found, the record will be null. The policy can be used to specify timeouts.

Parameters:

policy - generic configuration parameters, pass in null for defaults

listener - where to send results

keys - array of unique record identifiers

Throws:

AerospikeException - if queue is full

operate

public final void operate(WritePolicy policy,
                          RecordListener listener,
                          Key key,
                          Operation... operations)
                   throws AerospikeException

Asynchronously perform multiple read/write operations on a single key in one batch call. An example would be to add an integer value to an existing record and then read the result, all in one database call.

This method schedules the operate command with a channel selector and returns. Another thread will process the command and send the results to the listener.

Parameters:

policy - write configuration parameters, pass in null for defaults

listener - where to send results, pass in null for fire and forget

key - unique record identifier

operations - database operations to perform

Throws:

AerospikeException - if queue is full

scanAll

public final void scanAll(ScanPolicy policy,
                          RecordSequenceListener listener,
                          String namespace,
                          String setName,
                          String... binNames)
                   throws AerospikeException

Asynchronously read all records in specified namespace and set. If the policy's concurrentNodes is specified, each server node will be read in parallel. Otherwise, server nodes are read in series.

This method schedules the scan command with a channel selector and returns. Another thread will process the command and send the results to the listener.

Parameters:

policy - scan configuration parameters, pass in null for defaults

listener - where to send results, pass in null for fire and forget

namespace - namespace - equivalent to database name

setName - optional set name - equivalent to database table

binNames - optional bin to retrieve. All bins will be returned if not specified. Aerospike 2 servers ignore this parameter.

Throws:

AerospikeException - if queue is full