public class AerospikeClient extends Object implements Closeable
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.
Modifier and Type | Field and Description |
---|---|
QueryPolicy |
queryPolicyDefault
Default query policy that is used when query command policy is null.
|
Policy |
readPolicyDefault
Default read policy that is used when read command policy is null.
|
ScanPolicy |
scanPolicyDefault
Default scan policy that is used when scan command policy is null.
|
WritePolicy |
writePolicyDefault
Default write policy that is used when write command policy is null.
|
Constructor and Description |
---|
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.
|
Modifier and Type | Method and Description |
---|---|
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 |
ChangePassword(AdminPolicy policy,
String user,
String password)
Change user's password.
|
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.
|
void |
createUser(AdminPolicy policy,
String user,
String password,
List<String> roles)
Create user with password and roles.
|
boolean |
delete(WritePolicy policy,
Key key)
Delete record for specified key.
|
void |
dropIndex(Policy policy,
String namespace,
String setName,
String indexName)
Delete secondary index.
|
void |
dropUser(AdminPolicy policy,
String user)
Remove user from cluster.
|
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.
|
void |
GrantRoles(AdminPolicy policy,
String user,
List<String> roles)
Add roles to user's list of roles.
|
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.
|
UserRoles |
QueryUser(AdminPolicy policy,
String user)
Retrieve roles for a given user.
|
List<UserRoles> |
QueryUsers(AdminPolicy policy)
Retrieve all users and their roles.
|
RegisterTask |
register(Policy policy,
String clientPath,
String serverPath,
Language language)
Register package containing user defined functions with server.
|
void |
ReplaceRoles(AdminPolicy policy,
String user,
List<String> roles)
Replace user's list of roles.
|
void |
RevokeRoles(AdminPolicy policy,
String user,
List<String> roles)
Remove roles from user's list of roles.
|
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)
Reset record's time to expiration using the policy's expiration.
|
public final Policy readPolicyDefault
public final WritePolicy writePolicyDefault
public final ScanPolicy scanPolicyDefault
public final QueryPolicy queryPolicyDefault
public AerospikeClient(String hostname, int port) throws AerospikeException
- 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.
hostname
- host nameport
- host portAerospikeException
- if host connection failspublic AerospikeClient(ClientPolicy policy, String hostname, int port) throws AerospikeException
- 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.
policy
- client configuration parameters, pass in null for defaultshostname
- host nameport
- host portAerospikeException
- if host connection failspublic AerospikeClient(ClientPolicy policy, Host... hosts) throws AerospikeException
- 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.
policy
- client configuration parameters, pass in null for defaultshosts
- array of potential hosts to seed the clusterAerospikeException
- if all host connections failpublic final void close()
close
in interface Closeable
close
in interface AutoCloseable
public final boolean isConnected()
true
if cluster is ready,
false
if cluster is not readypublic final Node[] getNodes()
public final List<String> getNodeNames()
public final void put(WritePolicy policy, Key key, Bin... bins) throws AerospikeException
policy
- write configuration parameters, pass in null for defaultskey
- unique record identifierbins
- array of bin name/value pairsAerospikeException
- if write failspublic final void append(WritePolicy policy, Key key, Bin... bins) throws AerospikeException
policy
- write configuration parameters, pass in null for defaultskey
- unique record identifierbins
- array of bin name/value pairsAerospikeException
- if append failspublic final void prepend(WritePolicy policy, Key key, Bin... bins) throws AerospikeException
policy
- write configuration parameters, pass in null for defaultskey
- unique record identifierbins
- array of bin name/value pairsAerospikeException
- if prepend failspublic final void add(WritePolicy policy, Key key, Bin... bins) throws AerospikeException
policy
- write configuration parameters, pass in null for defaultskey
- unique record identifierbins
- array of bin name/value pairsAerospikeException
- if add failspublic final boolean delete(WritePolicy policy, Key key) throws AerospikeException
policy
- delete configuration parameters, pass in null for defaultskey
- unique record identifierAerospikeException
- if delete failspublic final void touch(WritePolicy policy, Key key) throws AerospikeException
policy
- write configuration parameters, pass in null for defaultskey
- unique record identifierAerospikeException
- if touch failspublic final boolean exists(Policy policy, Key key) throws AerospikeException
policy
- generic configuration parameters, pass in null for defaultskey
- unique record identifierAerospikeException
- if command failspublic final boolean[] exists(Policy policy, Key[] keys) throws AerospikeException
policy
- generic configuration parameters, pass in null for defaultskeys
- array of unique record identifiersAerospikeException
- if command failspublic final Record get(Policy policy, Key key) throws AerospikeException
policy
- generic configuration parameters, pass in null for defaultskey
- unique record identifierAerospikeException
- if read failspublic final Record get(Policy policy, Key key, String... binNames) throws AerospikeException
policy
- generic configuration parameters, pass in null for defaultskey
- unique record identifierbinNames
- bins to retrieveAerospikeException
- if read failspublic final Record getHeader(Policy policy, Key key) throws AerospikeException
policy
- generic configuration parameters, pass in null for defaultskey
- unique record identifierAerospikeException
- if read failspublic final Record[] get(Policy policy, Key[] keys) throws AerospikeException
policy
- generic configuration parameters, pass in null for defaultskeys
- array of unique record identifiersAerospikeException
- if read failspublic final Record[] get(Policy policy, Key[] keys, String... binNames) throws AerospikeException
policy
- generic configuration parameters, pass in null for defaultskeys
- array of unique record identifiersbinNames
- array of bins to retrieveAerospikeException
- if read failspublic final Record[] getHeader(Policy policy, Key[] keys) throws AerospikeException
policy
- generic configuration parameters, pass in null for defaultskeys
- array of unique record identifiersAerospikeException
- if read failspublic final Record operate(WritePolicy policy, Key key, Operation... operations) throws AerospikeException
Write operations are always performed first, regardless of operation order relative to read operations.
policy
- write configuration parameters, pass in null for defaultskey
- unique record identifieroperations
- database operations to performAerospikeException
- if command failspublic final void scanAll(ScanPolicy policy, String namespace, String setName, ScanCallback callback, String... binNames) throws AerospikeException
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.
policy
- scan configuration parameters, pass in null for defaultsnamespace
- namespace - equivalent to database namesetName
- optional set name - equivalent to database tablecallback
- read callback method - called with record databinNames
- optional bin to retrieve. All bins will be returned if not specified.
Aerospike 2 servers ignore this parameter.AerospikeException
- if scan failspublic final void scanNode(ScanPolicy policy, String nodeName, String namespace, String setName, ScanCallback callback, String... binNames) throws AerospikeException
This call will block until the scan is complete - callbacks are made within the scope of this call.
policy
- scan configuration parameters, pass in null for defaultsnodeName
- server node namenamespace
- namespace - equivalent to database namesetName
- optional set name - equivalent to database tablecallback
- read callback method - called with record databinNames
- optional bin to retrieve. All bins will be returned if not specified.
Aerospike 2 servers ignore this parameter.AerospikeException
- if scan failspublic final void scanNode(ScanPolicy policy, Node node, String namespace, String setName, ScanCallback callback, String... binNames) throws AerospikeException
This call will block until the scan is complete - callbacks are made within the scope of this call.
policy
- scan configuration parameters, pass in null for defaultsnode
- server nodenamespace
- namespace - equivalent to database namesetName
- optional set name - equivalent to database tablecallback
- read callback method - called with record databinNames
- optional bin to retrieve. All bins will be returned if not specified.
Aerospike 2 servers ignore this parameter.AerospikeException
- if transaction failspublic final LargeList getLargeList(Policy policy, Key key, String binName, String userModule)
This method is only supported by Aerospike 3 servers.
policy
- generic configuration parameters, pass in null for defaultskey
- unique record identifierbinName
- bin nameuserModule
- Lua function name that initializes list configuration parameters, pass null for defaultpublic final LargeMap getLargeMap(Policy policy, Key key, String binName, String userModule)
This method is only supported by Aerospike 3 servers.
policy
- generic configuration parameters, pass in null for defaultskey
- unique record identifierbinName
- bin nameuserModule
- Lua function name that initializes list configuration parameters, pass null for defaultpublic final LargeSet getLargeSet(Policy policy, Key key, String binName, String userModule)
This method is only supported by Aerospike 3 servers.
policy
- generic configuration parameters, pass in null for defaultskey
- unique record identifierbinName
- bin nameuserModule
- Lua function name that initializes list configuration parameters, pass null for defaultpublic final LargeStack getLargeStack(Policy policy, Key key, String binName, String userModule)
This method is only supported by Aerospike 3 servers.
policy
- generic configuration parameters, pass in null for defaultskey
- unique record identifierbinName
- bin nameuserModule
- Lua function name that initializes list configuration parameters, pass null for defaultpublic final RegisterTask register(Policy policy, String clientPath, String serverPath, Language language) throws AerospikeException
This method is only supported by Aerospike 3 servers.
policy
- generic configuration parameters, pass in null for defaultsclientPath
- path of client file containing user defined functions, relative to current directoryserverPath
- path to store user defined functions on the server, relative to configured script directory.language
- language of user defined functionsAerospikeException
- if register failspublic final Object execute(Policy policy, Key key, String packageName, String functionName, Value... args) throws AerospikeException
udf file =
This method is only supported by Aerospike 3 servers.
policy
- generic configuration parameters, pass in null for defaultskey
- unique record identifierpackageName
- server package name where user defined function residesfunctionName
- user defined functionargs
- arguments passed in to user defined functionAerospikeException
- if transaction failspublic final ExecuteTask execute(Policy policy, Statement statement, String packageName, String functionName, Value... functionArgs) throws AerospikeException
This method is only supported by Aerospike 3 servers.
policy
- scan configuration parameters, pass in null for defaultsstatement
- record filterpackageName
- server package where user defined function residesfunctionName
- function namefunctionArgs
- to pass to function name, if anyAerospikeException
- if command failspublic final RecordSet query(QueryPolicy policy, Statement statement) throws AerospikeException
This method is only supported by Aerospike 3 servers.
policy
- generic configuration parameters, pass in null for defaultsstatement
- database query commandAerospikeException
- if query failspublic final ResultSet queryAggregate(QueryPolicy policy, Statement statement, String packageName, String functionName, Value... functionArgs) throws AerospikeException
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 =
This method is only supported by Aerospike 3 servers.
policy
- generic configuration parameters, pass in null for defaultsstatement
- database query commandpackageName
- server package where user defined function residesfunctionName
- aggregation function namefunctionArgs
- arguments to pass to function name, if anyAerospikeException
- if query failspublic final IndexTask createIndex(Policy policy, String namespace, String setName, String indexName, String binName, IndexType indexType) throws AerospikeException
This method is only supported by Aerospike 3 servers.
policy
- generic configuration parameters, pass in null for defaultsnamespace
- namespace - equivalent to database namesetName
- optional set name - equivalent to database tableindexName
- name of secondary indexbinName
- bin name that data is indexed onindexType
- type of secondary indexAerospikeException
- if index create failspublic final void dropIndex(Policy policy, String namespace, String setName, String indexName) throws AerospikeException
policy
- generic configuration parameters, pass in null for defaultsnamespace
- namespace - equivalent to database namesetName
- optional set name - equivalent to database tableindexName
- name of secondary indexAerospikeException
- if index create failspublic void createUser(AdminPolicy policy, String user, String password, List<String> roles) throws AerospikeException
policy
- admin configuration parameters, pass in null for defaultsuser
- user namepassword
- user password in clear-text formatroles
- variable arguments array of role names. Valid roles are listed in Role.csAerospikeException
- if command failspublic void dropUser(AdminPolicy policy, String user) throws AerospikeException
policy
- admin configuration parameters, pass in null for defaultsuser
- user nameAerospikeException
- if command failspublic void ChangePassword(AdminPolicy policy, String user, String password) throws AerospikeException
policy
- admin configuration parameters, pass in null for defaultsuser
- user namepassword
- user password in clear-text formatAerospikeException
- if command failspublic void GrantRoles(AdminPolicy policy, String user, List<String> roles) throws AerospikeException
policy
- admin configuration parameters, pass in null for defaultsuser
- user nameroles
- role names. Valid roles are listed in Role.csAerospikeException
- if command failspublic void RevokeRoles(AdminPolicy policy, String user, List<String> roles) throws AerospikeException
policy
- admin configuration parameters, pass in null for defaultsuser
- user nameroles
- role names. Valid roles are listed in Role.csAerospikeException
- if command failspublic void ReplaceRoles(AdminPolicy policy, String user, List<String> roles) throws AerospikeException
policy
- admin configuration parameters, pass in null for defaultsuser
- user nameroles
- role names. Valid roles are listed in Role.csAerospikeException
- if command failspublic UserRoles QueryUser(AdminPolicy policy, String user) throws AerospikeException
policy
- admin configuration parameters, pass in null for defaultsuser
- user name filterAerospikeException
- if command failspublic List<UserRoles> QueryUsers(AdminPolicy policy) throws AerospikeException
policy
- admin configuration parameters, pass in null for defaultsAerospikeException
- if command failsCopyright © 2012–2014 Aerospike, Inc. All rights reserved.