com.aerospike.client.policy

Class Policy

java.lang.Object

com.aerospike.client.policy.Policy

Direct Known Subclasses:

BatchPolicy, QueryPolicy, ScanPolicy, WritePolicy

public class Policy
extends Object

Transaction policy attributes used in all database commands.

Field Summary

Fields

Modifier and Type	Field and Description
boolean	compress Use zlib compression on command buffers sent to the server and responses received from the server when the buffer size is greater than 128 bytes.
int	connectTimeout Socket connect timeout in milliseconds.
boolean	failOnFilteredOut Throw exception if filterExp is defined and that filter evaluates to false (transaction ignored).
Expression	filterExp Optional expression filter.
int	maxRetries Maximum number of retries before aborting the current transaction.
ReadModeAP	readModeAP Read policy for AP (availability) namespaces.
ReadModeSC	readModeSC Read policy for SC (strong consistency) namespaces.
int	readTouchTtlPercent Determine how record TTL (time to live) is affected on reads.
Replica	replica Replica algorithm used to determine the target node for a partition derived from a key or requested in a scan/query.
boolean	sendKey Send user defined key in addition to hash digest on both reads and writes.
int	sleepBetweenRetries Milliseconds to sleep between retries.
int	socketTimeout Socket idle timeout in milliseconds when processing a database command.
int	timeoutDelay Delay milliseconds after socket read timeout in an attempt to recover the socket in the background.
int	totalTimeout Total transaction timeout in milliseconds.

Constructor Summary

Constructors

Constructor and Description
Policy() Default constructor.
Policy(Policy other) Copy policy from another policy.

Method Summary

Modifier and Type	Method and Description
boolean	equals(Object o)
int	hashCode()
void	setCompress(boolean compress)
void	setConnectTimeout(int connectTimeout)
void	setFailOnFilteredOut(boolean failOnFilteredOut)
void	setFilterExp(Expression filterExp)
void	setMaxRetries(int maxRetries)
void	setReadModeAP(ReadModeAP readModeAP)
void	setReadModeSC(ReadModeSC readModeSC)
void	setReadTouchTtlPercent(int readTouchTtlPercent)
void	setReplica(Replica replica)
void	setSendKey(boolean sendKey)
void	setSleepBetweenRetries(int sleepBetweenRetries)
void	setSocketTimeout(int socketTimeout)
void	setTimeout(int timeout) Create a single timeout by setting socketTimeout and totalTimeout to the same value.
void	setTimeoutDelay(int timeoutDelay)
void	setTimeouts(int socketTimeout, int totalTimeout) Set socketTimeout and totalTimeout.
void	setTotalTimeout(int totalTimeout)

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

readModeAP

public ReadModeAP readModeAP

Read policy for AP (availability) namespaces.

Default: ReadModeAP.ONE

readModeSC

public ReadModeSC readModeSC

Read policy for SC (strong consistency) namespaces.

Default: ReadModeSC.SESSION

replica

public Replica replica

Replica algorithm used to determine the target node for a partition derived from a key or requested in a scan/query.

Default: Replica.SEQUENCE

filterExp

public Expression filterExp

Optional expression filter. If filterExp exists and evaluates to false, the transaction is ignored.

Default: null

Example:
 Policy p = new Policy();
 p.filterExp = Exp.build(Exp.eq(Exp.intBin("a"), Exp.val(11)));
 

connectTimeout

public int connectTimeout

Socket connect timeout in milliseconds. If connectTimeout greater than zero, it will be applied to creating a connection plus optional user authentication. Otherwise, socketTimeout or totalTimeout will be used depending on their values.

If connect, socket and total timeouts are zero, the actual socket connect timeout is hard-coded to 2000ms.

connectTimeout is useful when new connection creation is expensive (ie TLS connections) and it's acceptable to allow extra time to create a new connection compared to using an existing connection from the pool.

Default: 0

socketTimeout

public int socketTimeout

Socket idle timeout in milliseconds when processing a database command.

If socketTimeout is zero and totalTimeout is non-zero, then socketTimeout will be set to totalTimeout. If both socketTimeout and totalTimeout are non-zero and socketTimeout > totalTimeout, then socketTimeout will be set to totalTimeout. If both socketTimeout and totalTimeout are zero, then there will be no socket idle limit.

If socketTimeout is non-zero and the socket has been idle for at least socketTimeout, both maxRetries and totalTimeout are checked. If maxRetries and totalTimeout are not exceeded, the transaction is retried.

For synchronous methods, socketTimeout is the socket timeout (SO_TIMEOUT). For asynchronous methods, the socketTimeout is implemented using a HashedWheelTimer.

Default: 30000ms

totalTimeout

public int totalTimeout

Total transaction timeout in milliseconds.

The totalTimeout is tracked on the client and sent to the server along with the transaction in the wire protocol. The client will most likely timeout first, but the server also has the capability to timeout the transaction.

If totalTimeout is not zero and totalTimeout is reached before the transaction completes, the transaction will abort with AerospikeException.Timeout.

If totalTimeout is zero, there will be no total time limit.

Default for scan/query: 0

Default for all other commands: 1000ms

timeoutDelay

public int timeoutDelay

Delay milliseconds after socket read timeout in an attempt to recover the socket in the background. Processing continues on the original transaction and the user is still notified at the original transaction timeout.

When a transaction is stopped prematurely, the socket must be drained of all incoming data or closed to prevent unread socket data from corrupting the next transaction that would use that socket.

If a socket read timeout occurs and timeoutDelay is greater than zero, the socket will be drained until all data has been read or timeoutDelay is reached. If all data has been read, the socket will be placed back into the connection pool. If timeoutDelay is reached before the draining is complete, the socket will be closed.

Sync sockets are drained in the cluster tend thread at periodic intervals. Async sockets are drained in the event loop from which the async command executed.

Many cloud providers encounter performance problems when sockets are closed by the client when the server still has data left to write (results in socket RST packet). If the socket is fully drained before closing, the socket RST performance penalty can be avoided on these cloud providers.

The disadvantage of enabling timeoutDelay is that extra memory/processing is required to drain sockets and additional connections may still be needed for transaction retries.

If timeoutDelay were to be enabled, 3000ms would be a reasonable value.

Default: 0 (no delay, connection closed on timeout)

maxRetries

public int maxRetries

Maximum number of retries before aborting the current transaction. The initial attempt is not counted as a retry.

If maxRetries is exceeded, the transaction will abort with AerospikeException.Timeout.

WARNING: Database writes that are not idempotent (such as add()) should not be retried because the write operation may be performed multiple times if the client timed out previous transaction attempts. It's important to use a distinct WritePolicy for non-idempotent writes which sets maxRetries = 0;

Default for write: 0 (no retries)

Default for read: 2 (initial attempt + 2 retries = 3 attempts)

Default for scan/query: 5 (6 attempts. See ScanPolicy.ScanPolicy() comments.)

sleepBetweenRetries

public int sleepBetweenRetries

Milliseconds to sleep between retries. Enter zero to skip sleep. This field is ignored when maxRetries is zero. This field is also ignored in async mode.

The sleep only occurs on connection errors and server timeouts which suggest a node is down and the cluster is reforming. The sleep does not occur when the client's socketTimeout expires.

Reads do not have to sleep when a node goes down because the cluster does not shut out reads during cluster reformation. The default for reads is zero.

The default for writes is also zero because writes are not retried by default. Writes need to wait for the cluster to reform when a node goes down. Immediate write retries on node failure have been shown to consistently result in errors. If maxRetries is greater than zero on a write, then sleepBetweenRetries should be set high enough to allow the cluster to reform (>= 3000ms).

Default: 0 (do not sleep between retries)

readTouchTtlPercent

public int readTouchTtlPercent

Determine how record TTL (time to live) is affected on reads. When enabled, the server can efficiently operate as a read-based LRU cache where the least recently used records are expired. The value is expressed as a percentage of the TTL sent on the most recent write such that a read within this interval of the record’s end of life will generate a touch.

For example, if the most recent write had a TTL of 10 hours and read_touch_ttl_percent is set to 80, the next read within 8 hours of the record's end of life (equivalent to 2 hours after the most recent write) will result in a touch, resetting the TTL to another 10 hours.

Values:

• 0 : Use server config default-read-touch-ttl-pct for the record's namespace/set.
• -1 : Do not reset record TTL on reads.
• 1 - 100 : Reset record TTL on reads when within this percentage of the most recent write TTL.

Default: 0

sendKey

public boolean sendKey

Send user defined key in addition to hash digest on both reads and writes. If the key is sent on a write, the key will be stored with the record on the server.

If the key is sent on a read, the server will generate the hash digest from the key and validate that digest with the digest sent by the client. Unless this is the explicit intent of the developer, avoid sending the key on reads.

Default: false (do not send the user defined key)

compress

public boolean compress

Use zlib compression on command buffers sent to the server and responses received from the server when the buffer size is greater than 128 bytes.

This option will increase cpu and memory usage (for extra compressed buffers),but decrease the size of data sent over the network.

Default: false

failOnFilteredOut

public boolean failOnFilteredOut

Throw exception if filterExp is defined and that filter evaluates to false (transaction ignored). The AerospikeException will contain result code ResultCode.FILTERED_OUT.

This field is not applicable to batch, scan or query commands.

Default: false

Constructor Detail

Policy

public Policy(Policy other)

Copy policy from another policy.

Policy

public Policy()

Default constructor.

Method Detail

setTimeout

public final void setTimeout(int timeout)

Create a single timeout by setting socketTimeout and totalTimeout to the same value.

setTimeouts

public final void setTimeouts(int socketTimeout,
                              int totalTimeout)

Set socketTimeout and totalTimeout. If totalTimeout defined and socketTimeout greater than totalTimeout, set socketTimeout to totalTimeout.

setReadModeAP

public void setReadModeAP(ReadModeAP readModeAP)

setReadModeSC

public void setReadModeSC(ReadModeSC readModeSC)

setReplica

public void setReplica(Replica replica)

setFilterExp

public void setFilterExp(Expression filterExp)

setConnectTimeout

public void setConnectTimeout(int connectTimeout)

setSocketTimeout

public void setSocketTimeout(int socketTimeout)

setTotalTimeout

public void setTotalTimeout(int totalTimeout)

setTimeoutDelay

public void setTimeoutDelay(int timeoutDelay)

setMaxRetries

public void setMaxRetries(int maxRetries)

setSleepBetweenRetries

public void setSleepBetweenRetries(int sleepBetweenRetries)

setReadTouchTtlPercent

public void setReadTouchTtlPercent(int readTouchTtlPercent)

setSendKey

public void setSendKey(boolean sendKey)

setCompress

public void setCompress(boolean compress)

setFailOnFilteredOut

public void setFailOnFilteredOut(boolean failOnFilteredOut)

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object