com.aerospike.client
Class AerospikeClient

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

Direct Known Subclasses:

AsyncClient

public class AerospikeClient
extends Object

Instantiate an AerospikeClient object to access an Aerospike database cluster and perform database operations.

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

Your application uses this class API to perform 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.

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

AerospikeClient(ClientPolicy policy, Host... hosts)
Initialize Aerospike client with suitable hosts to seed the cluster map.

AerospikeClient(ClientPolicy policy, String hostname, int port)
Initialize Aerospike client.

AerospikeClient(String hostname, int port)
Initialize Aerospike client.

Method Summary

void	add(WritePolicy policy, Key key, Bin... bins) Add integer bin values to existing record bin values.
void	append(WritePolicy policy, Key key, Bin... bins) Append bin string values to existing record bin values.
void	close() Close all client connections to database server nodes.
IndexTask	createIndex(Policy policy, String namespace, String setName, String indexName, String binName, IndexType indexType) Create secondary index.
boolean	delete(WritePolicy policy, Key key) Delete record for specified key.
void	dropIndex(Policy policy, String namespace, String setName, String indexName) Delete secondary index.
Object	execute(Policy policy, Key key, String packageName, String functionName, Value... args) Execute user defined function on server and return results.
ExecuteTask	execute(Policy policy, Statement statement, String packageName, String functionName, Value... functionArgs) Apply user defined function on records that match the statement filter.
boolean	exists(Policy policy, Key key) Determine if a record key exists.
boolean[]	exists(Policy policy, Key[] keys) Check if multiple record keys exist in one batch call.
Record	get(Policy policy, Key key) Read entire record for specified key.
Record[]	get(Policy policy, Key[] keys) Read multiple records for specified keys in one batch call.
Record[]	get(Policy policy, Key[] keys, String... binNames) Read multiple record headers and bins for specified keys in one batch call.
Record	get(Policy policy, Key key, String... binNames) Read record header and bins for specified key.
Record	getHeader(Policy policy, Key key) Read record generation and expiration only for specified key.
Record[]	getHeader(Policy policy, Key[] keys) Read multiple record header data for specified keys in one batch call.
LargeList	getLargeList(Policy policy, Key key, String binName, String userModule) Initialize large list operator.
LargeMap	getLargeMap(Policy policy, Key key, String binName, String userModule) Initialize large map operator.
LargeSet	getLargeSet(Policy policy, Key key, String binName, String userModule) Initialize large set operator.
LargeStack	getLargeStack(Policy policy, Key key, String binName, String userModule) Initialize large stack operator.
List<String>	getNodeNames() Return list of active server node names in the cluster.
Node[]	getNodes() Return array of active server nodes in the cluster.
boolean	isConnected() Determine if we are ready to talk to the database server cluster.
Record	operate(WritePolicy policy, Key key, Operation... operations) Perform multiple read/write operations on a single key in one batch call.
void	prepend(WritePolicy policy, Key key, Bin... bins) Prepend bin string values to existing record bin values.
void	put(WritePolicy policy, Key key, Bin... bins) Write record bin(s).
RecordSet	query(QueryPolicy policy, Statement statement) Execute query and return record iterator.
ResultSet	queryAggregate(QueryPolicy policy, Statement statement, String packageName, String functionName, Value... functionArgs) Execute query, apply statement's aggregation function, and return result iterator.
RegisterTask	register(Policy policy, String clientPath, String serverPath, Language language) Register package containing user defined functions with server.
void	scanAll(ScanPolicy policy, String namespace, String setName, ScanCallback callback, String... binNames) Read all records in specified namespace and set.
void	scanNode(ScanPolicy policy, Node node, String namespace, String setName, ScanCallback callback, String... binNames) Read all records in specified namespace and set for one node only.
void	scanNode(ScanPolicy policy, String nodeName, String namespace, String setName, ScanCallback callback, String... binNames) Read all records in specified namespace and set for one node only.
void	touch(WritePolicy policy, Key key) Create record if it does not already exist.

Methods inherited from class java.lang.Object

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

Constructor Detail

AerospikeClient

public AerospikeClient(String hostname,
                       int port)
                throws AerospikeException

Initialize Aerospike 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

AerospikeClient

public AerospikeClient(ClientPolicy policy,
                       String hostname,
                       int port)
                throws AerospikeException

Initialize Aerospike 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

AerospikeClient

public AerospikeClient(ClientPolicy policy,
                       Host... hosts)
                throws AerospikeException

Initialize Aerospike 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

close

public final void close()

Close all client connections to database server nodes.

isConnected

public final boolean isConnected()

Determine if we are ready to talk to the database server cluster.

Returns:

true if cluster is ready, false if cluster is not ready

getNodes

public final Node[] getNodes()

Return array of active server nodes in the cluster.

Returns:

array of active nodes

getNodeNames

public final List<String> getNodeNames()

Return list of active server node names in the cluster.

Returns:

list of active node names

put

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

Write record bin(s). 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

key - unique record identifier

bins - array of bin name/value pairs

Throws:

AerospikeException - if write fails

append

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

Append bin string values to existing record bin values. 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

key - unique record identifier

bins - array of bin name/value pairs

Throws:

AerospikeException - if append fails

prepend

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

Prepend bin string values to existing record bin values. 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

key - unique record identifier

bins - array of bin name/value pairs

Throws:

AerospikeException - if prepend fails

add

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

Add integer bin values to existing record bin values. 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

key - unique record identifier

bins - array of bin name/value pairs

Throws:

AerospikeException - if add fails

delete

public final boolean delete(WritePolicy policy,
                            Key key)
                     throws AerospikeException

Delete record for specified key. The policy specifies the transaction timeout.

Parameters:

policy - delete configuration parameters, pass in null for defaults

key - unique record identifier

Returns:

whether record existed on server before deletion

Throws:

AerospikeException - if delete fails

touch

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

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.

Parameters:

policy - write configuration parameters, pass in null for defaults

key - unique record identifier

Throws:

AerospikeException - if touch fails

exists

public final boolean exists(Policy policy,
                            Key key)
                     throws AerospikeException

Determine if a record key exists. The policy can be used to specify timeouts.

Parameters:

policy - generic configuration parameters, pass in null for defaults

key - unique record identifier

Returns:

whether record exists or not

Throws:

AerospikeException - if command fails

exists

public final boolean[] exists(Policy policy,
                              Key[] keys)
                       throws AerospikeException

Check if multiple record keys exist in one batch call. The returned boolean array is in positional order with the original key array order. The policy can be used to specify timeouts.

Parameters:

policy - generic configuration parameters, pass in null for defaults

keys - array of unique record identifiers

Returns:

array key/existence status pairs

Throws:

AerospikeException - if command fails

get

public final Record get(Policy policy,
                        Key key)
                 throws AerospikeException

Read entire record for specified key. The policy can be used to specify timeouts.

Parameters:

policy - generic configuration parameters, pass in null for defaults

key - unique record identifier

Returns:

if found, return record instance. If not found, return null.

Throws:

AerospikeException - if read fails

get

public final Record get(Policy policy,
                        Key key,
                        String... binNames)
                 throws AerospikeException

Read record header and bins for specified key. The policy can be used to specify timeouts.

Parameters:

policy - generic configuration parameters, pass in null for defaults

key - unique record identifier

binNames - bins to retrieve

Returns:

if found, return record instance. If not found, return null.

Throws:

AerospikeException - if read fails

getHeader

public final Record getHeader(Policy policy,
                              Key key)
                       throws AerospikeException

Read record generation and expiration only for specified key. Bins are not read. The policy can be used to specify timeouts.

Parameters:

policy - generic configuration parameters, pass in null for defaults

key - unique record identifier

Returns:

if found, return record instance. If not found, return null.

Throws:

AerospikeException - if read fails

get

public final Record[] get(Policy policy,
                          Key[] keys)
                   throws AerospikeException

Read multiple records for specified keys in one batch call. The returned records are in positional order with the original key array order. If a key is not found, the positional record will be null. The policy can be used to specify timeouts.

Parameters:

policy - generic configuration parameters, pass in null for defaults

keys - array of unique record identifiers

Returns:

array of records

Throws:

AerospikeException - if read fails

get

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

Read multiple record headers and bins for specified keys in one batch call. The returned records are in positional order with the original key array order. If a key is not found, the positional record will be null. The policy can be used to specify timeouts.

Parameters:

policy - generic configuration parameters, pass in null for defaults

keys - array of unique record identifiers

binNames - array of bins to retrieve

Returns:

array of records

Throws:

AerospikeException - if read fails

getHeader

public final Record[] getHeader(Policy policy,
                                Key[] keys)
                         throws AerospikeException

Read multiple record header data for specified keys in one batch call. The returned records are in positional order with the original key array order. If a key is not found, the positional record will be null. The policy can be used to specify timeouts.

Parameters:

policy - generic configuration parameters, pass in null for defaults

keys - array of unique record identifiers

Returns:

array of records

Throws:

AerospikeException - if read fails

operate

public final Record operate(WritePolicy policy,
                            Key key,
                            Operation... operations)
                     throws AerospikeException

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.

Write operations are always performed first, regardless of operation order relative to read operations.

Parameters:

policy - write configuration parameters, pass in null for defaults

key - unique record identifier

operations - database operations to perform

Returns:

record if there is a read in the operations list

Throws:

AerospikeException - if command fails

scanAll

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

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 call will block until the scan is complete - callbacks are made within the scope of this call.

Parameters:

policy - scan configuration parameters, pass in null for defaults

namespace - namespace - equivalent to database name

setName - optional set name - equivalent to database table

callback - read callback method - called with record data

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

Throws:

AerospikeException - if scan fails

scanNode

public final void scanNode(ScanPolicy policy,
                           String nodeName,
                           String namespace,
                           String setName,
                           ScanCallback callback,
                           String... binNames)
                    throws AerospikeException

Read all records in specified namespace and set for one node only. The node is specified by name.

This call will block until the scan is complete - callbacks are made within the scope of this call.

Parameters:

policy - scan configuration parameters, pass in null for defaults

nodeName - server node name

namespace - namespace - equivalent to database name

setName - optional set name - equivalent to database table

callback - read callback method - called with record data

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

Throws:

AerospikeException - if scan fails

scanNode

public final void scanNode(ScanPolicy policy,
                           Node node,
                           String namespace,
                           String setName,
                           ScanCallback callback,
                           String... binNames)
                    throws AerospikeException

Read all records in specified namespace and set for one node only.

This call will block until the scan is complete - callbacks are made within the scope of this call.

Parameters:

policy - scan configuration parameters, pass in null for defaults

node - server node

namespace - namespace - equivalent to database name

setName - optional set name - equivalent to database table

callback - read callback method - called with record data

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

Throws:

AerospikeException - if transaction fails

getLargeList

public final LargeList getLargeList(Policy policy,
                                    Key key,
                                    String binName,
                                    String userModule)

Initialize large list operator. This operator can be used to create and manage a list within a single bin.

This method is only supported by Aerospike 3 servers.

Parameters:

policy - generic configuration parameters, pass in null for defaults

key - unique record identifier

binName - bin name

userModule - Lua function name that initializes list configuration parameters, pass null for default

getLargeMap

public final LargeMap getLargeMap(Policy policy,
                                  Key key,
                                  String binName,
                                  String userModule)

Initialize large map operator. This operator can be used to create and manage a map within a single bin.

This method is only supported by Aerospike 3 servers.

Parameters:

policy - generic configuration parameters, pass in null for defaults

key - unique record identifier

binName - bin name

userModule - Lua function name that initializes list configuration parameters, pass null for default

getLargeSet

public final LargeSet getLargeSet(Policy policy,
                                  Key key,
                                  String binName,
                                  String userModule)

Initialize large set operator. This operator can be used to create and manage a set within a single bin.

This method is only supported by Aerospike 3 servers.

Parameters:

policy - generic configuration parameters, pass in null for defaults

key - unique record identifier

binName - bin name

userModule - Lua function name that initializes list configuration parameters, pass null for default

getLargeStack

public final LargeStack getLargeStack(Policy policy,
                                      Key key,
                                      String binName,
                                      String userModule)

Initialize large stack operator. This operator can be used to create and manage a stack within a single bin.

This method is only supported by Aerospike 3 servers.

Parameters:

policy - generic configuration parameters, pass in null for defaults

key - unique record identifier

binName - bin name

userModule - Lua function name that initializes list configuration parameters, pass null for default

register

public final RegisterTask register(Policy policy,
                                   String clientPath,
                                   String serverPath,
                                   Language language)
                            throws AerospikeException

Register package containing user defined functions with server. This asynchronous server call will return before command is complete. The user can optionally wait for command completion by using the returned RegisterTask instance.

This method is only supported by Aerospike 3 servers.

Parameters:

policy - generic configuration parameters, pass in null for defaults

clientPath - path of client file containing user defined functions, relative to current directory

serverPath - path to store user defined functions on the server, relative to configured script directory.

language - language of user defined functions

Throws:

AerospikeException - if register fails

execute

public final Object execute(Policy policy,
                            Key key,
                            String packageName,
                            String functionName,
                            Value... args)
                     throws AerospikeException

Execute user defined function on server and return results. The function operates on a single record. The package name is used to locate the udf file location:

udf file = /.lua

This method is only supported by Aerospike 3 servers.

Parameters:

policy - generic configuration parameters, pass in null for defaults

key - unique record identifier

packageName - server package name where user defined function resides

functionName - user defined function

args - arguments passed in to user defined function

Returns:

return value of user defined function

Throws:

AerospikeException - if transaction fails

execute

public final ExecuteTask execute(Policy policy,
                                 Statement statement,
                                 String packageName,
                                 String functionName,
                                 Value... functionArgs)
                          throws AerospikeException

Apply user defined function on records that match the statement filter. Records are not returned to the client. This asynchronous server call will return before command is complete. The user can optionally wait for command completion by using the returned ExecuteTask instance.

This method is only supported by Aerospike 3 servers.

Parameters:

policy - scan configuration parameters, pass in null for defaults

statement - record filter

packageName - server package where user defined function resides

functionName - function name

functionArgs - to pass to function name, if any

Throws:

AerospikeException - if command fails

query

public final RecordSet query(QueryPolicy policy,
                             Statement statement)
                      throws AerospikeException

Execute query and return record iterator. The query executor puts records on a queue in separate threads. The calling thread concurrently pops records off the queue through the record iterator.

This method is only supported by Aerospike 3 servers.

Parameters:

policy - generic configuration parameters, pass in null for defaults

statement - database query command

Returns:

record iterator

Throws:

AerospikeException - if query fails

queryAggregate

public final ResultSet queryAggregate(QueryPolicy policy,
                                      Statement statement,
                                      String packageName,
                                      String functionName,
                                      Value... functionArgs)
                               throws AerospikeException

Execute query, apply statement's aggregation function, and return result iterator. The query executor puts results on a queue in separate threads. The calling thread concurrently pops results off the queue through the result iterator.

The aggregation function is called on both server and client (final reduce). Therefore, the Lua script files must also reside on both server and client. The package name is used to locate the udf file location:

udf file = /.lua

This method is only supported by Aerospike 3 servers.

Parameters:

policy - generic configuration parameters, pass in null for defaults

statement - database query command

packageName - server package where user defined function resides

functionName - aggregation function name

functionArgs - arguments to pass to function name, if any

Returns:

result iterator

Throws:

AerospikeException - if query fails

createIndex

public final IndexTask createIndex(Policy policy,
                                   String namespace,
                                   String setName,
                                   String indexName,
                                   String binName,
                                   IndexType indexType)
                            throws AerospikeException

Create secondary index. This asynchronous server call will return before command is complete. The user can optionally wait for command completion by using the returned IndexTask instance.

This method is only supported by Aerospike 3 servers.

Parameters:

policy - generic configuration parameters, pass in null for defaults

namespace - namespace - equivalent to database name

setName - optional set name - equivalent to database table

indexName - name of secondary index

binName - bin name that data is indexed on

indexType - type of secondary index

Throws:

AerospikeException - if index create fails

dropIndex

public final void dropIndex(Policy policy,
                            String namespace,
                            String setName,
                            String indexName)
                     throws AerospikeException

Delete secondary index. This method is only supported by Aerospike 3 servers.

Parameters:

policy - generic configuration parameters, pass in null for defaults

namespace - namespace - equivalent to database name

setName - optional set name - equivalent to database table

indexName - name of secondary index

Throws:

AerospikeException - if index create fails