aerospike客户端policy设置官网文档翻译

Policy

Aerospike的读取和写入具有极大的灵活性。通过客户端策略（Policy），可以创建乐观并发（optimistic concurrency 翻译成乐观锁更好理解点）下的读-修改-写模式（原子操作），控制ttl，并仅在以前没有记录存在时才写入记录(或相反)。

这种类型的操作非常快，因为像代（generation）和ttl等信息都存储在主键索引中。检索数据对象不需要额外的工作。

这些策略同时作用于数据库操作和客户端操作。许多策略用于向服务器发送适当的协议命令。其他策略(如maxRetries)影响客户端操作。

每个客户端都存在这些策略，并且api略有不同。

Set Default Client Policies

可以为每个AerospikeClient实例创建默认客户端策略。

// Set client default policies.
ClientPolicy clientPolicy = new ClientPolicy();
clientPolicy.readPolicyDefault.replica = Replica.MASTER_PROLES;
clientPolicy.readPolicyDefault.consistencyLevel = ConsistencyLevel.CONSISTENCY_ALL;
clientPolicy.readPolicyDefault.socketTimeout = 100;
clientPolicy.readPolicyDefault.totalTimeout = 100;
clientPolicy.writePolicyDefault.commitLevel = CommitLevel.COMMIT_ALL;
clientPolicy.writePolicyDefault.socketTimeout = 500;
clientPolicy.writePolicyDefault.totalTimeout = 500;

// Connect to the cluster.
AerospikeClient client = new AerospikeClient(clientPolicy, new Host("seed1", 3000));

Set Per-Transaction Client Policies

要按事务设置策略，请将所需的策略设置传递给各个API调用。例如，以master提交级别执行写操作:

// Make a copy of the client's default write policy.
WritePolicy policy = new WritePolicy(client.writePolicyDefault);

// Change commit level.
policy.commitLevel = ConsistencyLevel.COMMIT_MASTER;

// Write record with modified write policy.
client.put(policy, key, bins);

如果事务调用中指定的策略不是null，那么该策略将覆盖在客户端连接级别上定义的相应策略。如果事务策略为null，则将使用相应的默认客户端策略。

Server Policies

可以在命名空间级别上使用动态可更改的服务器配置参数来覆盖服务器上客户端选择的每事务数据一致性级别。

Policy Definitions

Replica

Replica (Policy.replica)指定在单个记录操作期间客户端将访问哪个副本:

• SEQUENCE (default) — 首先尝试包含键的主分区的节点。如果连接失败，所有命令都会尝试包含复制分区的节点。如果达到socketTimeout，则读操作也会尝试包含复制分区的节点，但写操作仍然在主节点上进行。
• MASTER — 使用包含键的主分区的节点。
• MASTER_PROLES — 以轮询方式在包含key的主分区和复制分区的节点之间分发读取。
• RANDOM — 以轮询方式将读取数据分发到集群中的所有节点。写操作总是使用包含键的主分区的节点。

默认情况下，所有的客户端读操作都会首先被定向到主副本(Replica.SEQUENCE)，然而，用户也可能希望将读操作分散到所有可用的副本上(例如，读取hotkey对性能的影响可以按照复制因子的顺序递减)。设置replica策略为MASTER_PROLES，在master和proles之间分发读取

AP Data Consistency Level

一致性级别(Policy.consistencyLevel)指定服务器内部需要查询多少个副本才能确定最近的记录值，并将其返回给客户端。

consistencyLevel配置不适用于强一致性设置为true的namespace。

• CONSISTENCY_ONE(default) — 在返回之前读取一个副本。
• CONSISTENCY_ALL — 从record父分区唯一版本的所有节点读取数据。

客户端读取记录时的默认(包括读取和操作函数)是只读取一个副本(ConsistencyLevel.CONSISTENCY_ONE)。

在集群重新配置时，读取单个副本可能不会返回最近写入的版本。如果用户希望服务器提供“副本解析”功能，即联系多个副本并找到最新版本，包括更新主副本，可以设置一致性级别策略为ConsistencyLevel.CONSISTENCY_ALL。读取所有副本所带来的潜在性能下降仅在集群重构时才明显。

Linearize Read

如果启用，则线性化读策略(Policy.linearizeRead)强制对支持强一致性模式的服务器namespace的读操作进行线性化。

Send Key

如果启用，send key (Policy.sendKey)在读写时除了发送 hash digest外，还发送用户定义的键。如果键是通过写操作发送的，那么这个键会和记录一起存储在服务器上，并在扫描和查询时返回给客户端。

Socket Timeout

Socket timeout (Policy.socketTimeout)处理数据库命令时的Socket空闲超时时间，单位为毫秒。

如果socketTimeout不为0，并且socket已经空闲至少有socketTimeout时间，则会检查maxRetries和totalTimeout。

如果没有超过maxRetries和totalTimeout，则重试事务。

如果socketTimeout和totalTimeout都是非零的，并且socketTimeout > totalTimeout，那么socketTimeout将设置为totalTimeout。

如果socketTimeout为0，则没有socket空闲限制。

Total Timeout

总超时时间(Policy.totalTimeout)指定事务总超时时间，单位为毫秒。totalTimeout在客户端被跟踪，并通过连接协议与事务一起发送到服务器。totalTimeout在客户端被跟踪，并通过连接协议与事务一起发送到服务器。如果totalTimeout不为零，并且在事务完成之前达到totalTimeout，则事务将因超时异常而中止。

Max Retries

Max retries (Policy.maxRetries)表示终止当前事务之前的最大重试次数。最初的尝试不被视为重试。如果超过maxRetries，则事务将因超时异常而中止。

非幂等的数据库写操作(例如add())不应该重试，因为如果客户端之前的事务尝试超时，写操作可能会执行多次。对于非幂等写，使用不同的写策略很重要，它将maxRetries设置为0。

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

Default for write/query/scan: 0 (no retries)

Sleep Between Retries

Policy.sleepBetweenRetrie表示两次重试之间休眠的毫秒数。0表示跳过sleep。当maxRetries为0或异步模式时，此字段将被忽略。

sleep只发生在连接错误和服务器超时时，这表明一个节点停机了，集群正在重组。当客户端的socketTimeout超时时，不会发生sleep。当节点停机时，读操作不必sleep，因为集群不会在集群重组期间关闭读操作。读取的默认值是0。

写入操作的默认值也是0，因为默认情况下不会重试写入操作。当一个节点宕机时，写操作可以等待集群重组。节点失败时的立即写重试会始终导致错误。如果maxRetries在一次写操作时大于0，则应该将sleepBetweenRetries设置为足够高的值以允许集群进行调整(>= 500ms)。

Write Mode

写入模式(WritePolicy.recordExistsAction)指定如何处理记录已经存在的写入。

• UPDATE (default) — 创建或更新record。合并写命令bins和现有分区（Merge write command bins with existing bins）
• UPDATE_ONLY — 只更新记录。如果记录不存在则失败。合并写命令bins和现有分区。
• REPLACE — 创建或替换记录。删除未被写入命令bin引用的现有bin。
• REPLACE_ONLY — 只替换记录。如果记录不存在则失败。删除未被写入命令bin引用的现有bin。
• CREATE_ONLY — 创建。如果记录存在则失败。

AP Write Commit Level

提交级别策略(WritePolicy.commitLevel)指定了服务器在成功返回客户端之前必须成功写入的副本数:

commitLevel配置不适用于强一致性设置为true的namespace。

• COMMIT_ALL (default) — 返回前提交所有副本。强一致性模式所需。
• COMMIT_MASTER——仅提交主副本后返回，并异步复制prole副本。在强一致性模式下，COMMIT_MASTER会导致错误。

客户端在修改记录(包括写、删除、操作和UDF函数)时的默认行为是，在从写相关的API返回成功之前，确认所有的副本都成功写入。这个默认策略(CommitLevel.COMMIT_ALL)提供了最高级别的写一致性。

如果想要更低的写延迟，并且应用可以容忍更低的写一致性级别(可能出现“脏读”，即在提交副本之前，如果从非主副本读取了相同的记录，则返回旧的值)，则将提交级别策略设置为CommitLevel.COMMIT_MASTER。从Aerospike 5.7开始，如果客户端推送的COMMIT_MASTER事务速率超过了服务器的复制系统所能处理的速率，那么服务器会将这些事务转换为COMMIT_ALL来回推。

Write Generation Policy

generationPolicy(WritePolicy.generationPolicy)指定如何基于记录的generation来处理record的写。

Record generation是一个内部计数器，它使用整数值，每次更新record时都会递增。(这里的“Generation”不是指“Generation的行为”，而是指“版本”。)当插入一条记录时，计数器从1开始计数。因此，当前计数器为5的记录已经更新了4次。客户端应用程序不能直接改变计数器的值。读取记录不会导致Aerospike增加计数器。
当Aerospike处于可用和分区容忍(AP)模式时，在记录更新64K次后，Aerospike将记录计数器重置为1。

当Aerospike处于强一致性模式时，它会在记录更新1K次后将记录计数器重置为1。

客户端应用程序可以使用此计数器与其他客户端应用程序协调read-modify-write操作序列。

例如，假设客户端应用程序需要从记录中读取数据，修改数据，然后将修改后的数据写回记录。读取记录需要加锁，写入记录也是如此。然而，在客户端应用程序修改数据时，它对记录没有锁。另一个客户端应用程序可以在第一个客户端应用程序能够获得写锁并写入修改后的数据之前更新相同的记录。

如果generation策略设置为GEN_EQUAL或GEN_GT:

1. 在读取操作期间，客户端应用程序还会读取记录的生成计数器的值。
2. 在客户端应用程序修改数据并获得记录上的写锁后，它会读取计数器的当前值。
3. 出现下列情况之一:

(1) 如果generation成策略设置为GEN_EQUAL:

a. 如果客户端发送的generation等于服务器上的generation，则客户端应用程序将修改后的数据写入记 录。

b. 如果客户端发送的generation值与服务器端发送的generation值不相等，客户端应用不会执行写操 作。客户端应用程序可以重试read-modify-write操作序列。

(2) 如果generation成策略设置为GEN_GT:

a. 如果客户端发送的generation严格大于服务器上的generation值，则客户端应用程序将修改后的数据写入 记录。

b. 如果客户端发送的generation值不大于服务器端的generation值，则客户端应用程序不执行写操 作。客户端应用程序可以重试read-modify-write操作序列。

(3) 如果generation成策略设置为NONE:

a. 客户端应用程序从记录中读取数据时不会读取计数器的值。

b. 在修改它读取的数据之后，它将修改后的数据写入记录。

如果将生成策略设置为GEN_EQUAL或GEN_GT，写失败的操作错误码为3，即_err_generation。在这种情况下，fail_generation和通用的client_write_error统计信息将在服务器上标记。

Expiration (Time To Live)

记录过期时间(WritePolicy.expiration)或生存时间(time to live, ttl)是指记录在被服务器删除之前存在的秒数。到期值:

• -2 — 当记录被更新时，不要改变ttl。
• -1 — Never expire.
• 0 — 默认为服务器上的namespace的配置变量“Default -ttl”。
• > 0 — 实际ttl，以秒为单位。

Durable Delete

如果启用，持久删除(WritePolicy.durableDelete)会在记录被删除时留下一个墓碑。这可以防止删除的记录在节点故障后重新出现。