KV存储-Aerospike之客户端策略(Policy)

Aerospike(以下简称Spike）
通常情况下Spike对数据的一次操作（写入、读取）都有三大核心组件（Policy、Key、Bin）参与。要想在业务中对数据进行合理的操作必须提前系统的掌握各组件。
如下是个人对Policy组件的一些梳理总结。

1、客户端策略ClientPolicy

/**
 * Container object for client policy Command.
客户端策略命令的容器对象。
 */
public class ClientPolicy {
    /**用于异步命令的可选事件循环。*/
    public EventLoops eventLoops;
    /**群集的用户身份验证。对于在没有限制访问的情况下运行的群集，保留空值。*/
    public String user;
    /**群集的密码验证。密码将由客户端存储并以哈希格式发送到服务器。对于在没有限制访问的情况下运行的群集，保留空值。*/
    public String password;
    /**需要群集名称。如果不为空，则服务器节点必须返回此群集名称，以便加入客户端的群集视图。只应在连接到支持“cluster name”info命令的服务器时设置。*/
    public String clusterName;
    /**定义用户/密码时使用的身份验证模式。默认：INTERNAL*/
    public AuthMode authMode = AuthMode.INTERNAL;
    /**初始主机连接超时（毫秒）。首次打开与服务器主机的连接时的超时。 默认: 1000ms*/
    public int timeout = 1000;
    /**登录超时（毫秒）。当启用用户身份验证并执行节点登录时，将使用超时。 Default: 5000ms*/
    public int loginTimeout = 5000;
    /** 每个服务器节点允许的最大连接数。事务将通过重试逻辑，如果超过最大连接数，则可能会以“resultcode.no more_connections”失败。每个节点使用的连接数取决于正在进行的并发命令以及用于并行多节点命令（batch批处理、scan扫描和query查询）的子命令。每个命令将使用一个连接。Default: 300*/
    public int maxConnsPerNode = 300;
    /**每个节点使用的同步连接池数。具有8个或更少CPU核心的计算机通常每个节点只需要一个连接池。具有大量CPU核心的计算机可能会由于对池连接的争用而限制其同步性能。通过创建多个小型连接池，可以减少池连接的争用 Default: 1*/
    public int connPoolsPerNode = 1;
    /**最大套接字空闲时间（秒）。套接字连接池将丢弃空闲时间超过最大值的套接字。该值限制为24小时（86400）
     1、将该值设置为比服务器的 proto-fd-idle-ms（默认为60000毫秒或1分钟）少几秒钟是很重要的，这样客户端就不会尝试使用服务器已经获取的套接字。
     2、连接池现在由后进先出栈实现[LIFO]。堆栈尾部的连接总是使用最少的。这些连接每30次趋向迭代（通常为30秒）检查一次MaxSocketIdle。 Default: 55 seconds*/
    public int maxSocketIdle = 55;
    /**维护线程倾向于集群之间的间隔（以毫秒为单位）。默认值：1秒*/
    public int tendInterval = 1000;
    /**如果所有种子连接在群集实例化时失败，则引发异常。默认值：真*/
    public boolean failIfNotConnected = true;
    /**读取命令策略为空时使用的默认读取策略。*/
    public Policy readPolicyDefault = new Policy();
    /**写入命令策略为空时使用的默认写入策略。*/
    public WritePolicy writePolicyDefault = new WritePolicy();
    /**扫描命令策略为空时使用的默认扫描策略。*/
    public ScanPolicy scanPolicyDefault = new ScanPolicy();
    /**当查询命令的策略为空时使用的默认查询策略。*/
    public QueryPolicy queryPolicyDefault = new QueryPolicy();
    /**批处理命令策略为空时使用的默认批处理策略。*/
    public BatchPolicy batchPolicyDefault = new BatchPolicy();
    /**当info命令的策略为空时使用的默认信息策略。*/
    public InfoPolicy infoPolicyDefault = new InfoPolicy();
    /**启用了TLS的服务器的TLS安全连接策略。只有AerospikeClient同步命令才支持TLS连接。默认值：空（使用普通套接字）*/
    public TlsPolicy tlsPolicy;
    /**IP转换表用于不同客户端使用不同服务器IP地址的情况。在使用局域网内外的客户端时，这可能是必需的。Default is no translation. 
     密钥是从朋友信息请求返回到其他服务器的IP地址。该值是用于连接到服务器的实际IP地址。*/
    public Map<String,String> ipMap;
    /** 同步批处理、扫描和查询命令中使用的基础线程池。这些命令通常以并行线程的形式发送到多个服务器节点。线程池提高了性能，因为不必为每个命令创建/销毁线程。默认值为空，表示将使用以下守护进程线程池：
     * <pre>
     * threadPool = Executors.newCachedThreadPool(new ThreadFactory() {
     *     public final Thread newThread(Runnable runnable) {
     *       Thread thread = new Thread(runnable);
     *       thread.setDaemon(true);
     *       return thread;
     *    }
     * });
     * </pre>
     * 当程序终止时，守护进程线程自动终止。
     */
    public ExecutorService threadPool;
    /**线程池是否在其他客户端实例或类之间共享。
     如果未共享threadpool（默认），则当客户端实例关闭时，threadpool将关闭。
     如果threadpool是共享的，则在关闭客户端实例时不会关闭threadpool。此共享线程池应在程序终止前手动关闭。建议关闭，但如果threadpool为 构造为使用守护进程线程。*/
    public boolean sharedThreadPool;
    /**在集群操作期间，应该在信息请求中使用"services-alternate"代替"services"。"services-alternate"返回客户端用于与节点对话的服务器配置的外部IP地址。"services-alternate"可以用来代替提供客户机"ipMap"。默认值：false（使用原始"services"信息请求）。
     "services-alternate" 可用于Aerospike服务器版本 >= 3.7.1.*/
    public boolean useServicesAlternate;
    /**仅用于测试目的。不要修改。如果AerospikeClient实例只与第一个种子节点通信，而不使用数据分区映射来确定要发送数据库命令的节点。 Default: false*/
    public boolean forceSingleNode;
    /** 跟踪服务器机架数据。当将读取命令定向到包含密钥且与客户机位于同一机架上的服务器节点时，此字段非常有用。当节点分布在不同的机架/数据中心时，这有助于降低云提供商的成本。
     {@link ClientPolicy#rackId}, {@link Replica#PREFER_RACK} 还必须设置服务器机架配置以启用此功能。Default: false*/
    public boolean rackAware;
    /**此客户机实例所在的机架。
     {@link ClientPolicy#rackAware}, {@link Replica#PREFER_RACK} 还必须设置服务器机架配置以启用此功能。Default: 0*/
    public int rackId;

1.1、策略基类Policy【供写入，读取，批量用】

/**所有数据库命令中使用的事务策略属性。*/
public class Policy {
   /**请求相对于其他事务的优先级。目前，仅用于扫描。*/
   public Priority priority = Priority.DEFAULT;
   /**读取AP（可用性）命名空间的策略。
    * Default: {@link ReadModeAP#ONE}*/
   public ReadModeAP readModeAP = ReadModeAP.ONE;
   /**读取SC（强一致性）命名空间的策略。
    * Default: {@link ReadModeSC#SESSION}*/
   public ReadModeSC readModeSC = ReadModeSC.SESSION;

   /**用于确定单个记录命令的目标节点的副本算法。扫描和查询不受复制算法的影响。
    * Default: {@link Replica#SEQUENCE}*/
   public Replica replica = Replica.SEQUENCE;

   /**处理数据库命令时套接字空闲超时（毫秒）。
    * Default: 30000ms*/
   public int socketTimeout = 30000;
   /**总事务超时（毫秒）。
    * 在客户机上跟踪totalTimeout，并将其与有线协议中的事务一起发送到服务器。客户机很可能会先超时，但服务器也有能力使事务超时。
    * 如果totalTimeout不是零，并且在事务完成之前已达到totalTimeout，则事务将中止    * {@link com.aerospike.client.AerospikeException.Timeout}.
    * 如果totalTimeout为零，则不存在总时间限制。
    * Default: 0 (no time limit)*/
   public int totalTimeout;

   /**尝试在后台恢复socket时，socket读取超时后的延迟毫秒数。处理在原始事务上继续，并且在原始事务超时时仍会通知用户。*/
   public int timeoutDelay;

   /**中止当前事务之前的最大重试次数。初始尝试不算重试。*/
   public int maxRetries = 2;

   /**在两次重试之间休眠的毫秒数。输入零以跳过睡眠。当maxretries为零时忽略此字段。在异步模式下，此字段也被忽略。*/
   public int sleepBetweenRetries;

   /**除了对读和写进行哈希摘要之外，还发送用户定义的密钥。如果在写入时发送密钥，则该密钥将与服务器上的记录一起存储。
    * <p>
    * Default: false (do not send the user defined key)*/
   public boolean sendKey;

1.2、写入策略WritePolicy

/**
 * Container object for policy attributes used in write operations.
 * This object is passed into methods where database writes can occur.
 */
public final class WritePolicy extends Policy {
   /**限定如何处理记录已存在的写入。/
   public RecordExistsAction recordExistsAction = RecordExistsAction.UPDATE;
   /**根据记录生成限定如何处理记录写入。默认值（无）表示生成不用于限制写入。*/
   public GenerationPolicy generationPolicy = GenerationPolicy.NONE;
   /**在服务器上提交事务时需要一致性保证。默认值（commit_all）表示服务器应等待master和所有副本提交成功，然后再将成功返回到客户机。/
   public CommitLevel commitLevel = CommitLevel.COMMIT_ALL;
   /**预期Generation。Generation是在服务器上修改（包括创建）记录的次数。如果写入操作正在创建记录，则预期生成将为<code>0。*/
   public int generation;
   /**记录过期。也称为TTL（生存时间）。秒记录将在被服务器删除之前生存。 
    -2: 更新记录时不要更改TTL。Aerospike服务器版本支持>=3.10.1.
-1：永不过期。Aerospike服务器版本支持>=3.1.4.
0:  服务器上的命名空间配置变量“default ttl”的默认值。0：实际生存时间（以秒计）*/
   public int expiration;
   /**对于client operate（），返回每个操作的结果。默认情况下，某些操作不会返回结果（例如ListOperation.clear() ）这会使在返回的Bin结果列表中确定所需的结果偏移量变得困难。
将respondAllOps设置为true可以更容易地识别所需的结果偏移量（结果偏移量等于bin的操作序列）。如果operate()中有映射操作，那么对于该operate()调用，respondAllOps将强制为true。
Default: false*/
   public boolean respondAllOps;
   /**如果事务导致删除记录，请为该记录保留一个墓碑(tombstone)。这可以防止删除的记录在节点失败后重新出现。仅对Aerospike Server Enterprise Edition 3.10+有效。*/
   public boolean durableDelete;

1.2.1、生成策略GenerationPolicy【乐观锁】

/**如何基于记录生成处理记录写入*/
public enum GenerationPolicy {
   /**不要使用记录生成来限制写入*/
   NONE,
   /**如果预期生成等于服务器生成，则更新/删除记录。否则，失败。*/
   EXPECT_GEN_EQUAL,
   /**如果预期生成大于服务器生成，则更新/删除记录。否则，失败。这对于备份后的恢复很有用。*/
   EXPECT_GEN_GT
}

1.2.2、记录存在的处理RecordExistsAction

/**当记录已经存在时如何处理写入。/
public enum RecordExistsAction {
   /**创建或更新记录。将写入命令bins与现有bins合并*/
   UPDATE,
   /**仅更新记录。如果记录不存在，则失败。将写入命令bins与现有bins合并[Merge ]。*/
   UPDATE_ONLY,
   /**创建或替换记录。删除库中存在，但当前bins中未被写入的bins。Aerospike服务器版本支持>=3.1.6。*/
   REPLACE,
   /**仅替换记录。如果记录不存在，则失败。删除库中存在，但当前bins中未被写入的bins。Aerospike服务器版本支持>=3.1.6。*/
   REPLACE_ONLY,
   /**仅创建。如果记录存在，则失败。*/
   CREATE_ONLY
}

1.2.3、提交级别CommitLevel

package com.aerospike.client.policy;
/**在服务器上提交事务时需要一致性保证。 */
public enum CommitLevel {
   /**服务器应等待，直到成功提交主副本和所有副本。*/
   COMMIT_ALL,
   /**服务器应仅等待成功提交主服务器。*/
   COMMIT_MASTER
}

1.3、读取策略QueryPolicy/ScanPolicy

1.3.1、用户查询策略QueryPolicy

/**
 * Container object for policy attributes used in query operations.
 */
public class QueryPolicy extends Policy {
   /**在任何时间点对服务器节点的最大并发请求数。如果集群中有16个节点，maxConcurrentNodes为8，那么扫描请求将并行发送到8个节点。扫描完成后，将发出新的扫描请求，直到扫描完所有16个节点。只有当ConcurrentNodes为true时，此字段才相关。默认值（0）是并行向所有服务器节点发出请求。*/
   public int maxConcurrentNodes;
   /**阻塞前要放入队列中的记录数。从多个服务器节点接收的记录将放在一个队列中。单独的线程并行消费这些记录。如果队列已满，则生产者线程将阻塞，直到记录被占用*/
   public int recordQueueSize = 5000;
   /**指示是否检索bin数据。如果为false，则只检索记录摘要（如果存储在服务器上，则检索用户keys）。*/
   public boolean includeBinData = true;
   /**如果集群处于迁移状态，则终止查询。*/
   public boolean failOnClusterChange;

1.3.2、用户扫描策略ScanPolicy

/**Container object for optional parameters used in scan operations.
扫描操作中使用的可选参数的容器对象。 */
public final class ScanPolicy extends Policy {
   /**要扫描的数据百分比。有效的整数范围是1到100。默认值为100*/
   public int scanPercent = 100;
   /**在任何时间点对服务器节点的最大并发请求数。如果集群中有16个节点，maxConcurrentNodes为8，那么扫描请求将并行发送到8个节点。扫描完成后，将发出新的扫描请求，直到扫描完所有16个节点。只有当ConcurrentNodes为true时，此字段才相关。默认值（0）是并行向所有服务器节点发出请求。*/
   public int maxConcurrentNodes;
   /**并行或串行地发出扫描请求。*/
   public boolean concurrentNodes = true;
   /**指示是否检索bin数据。如果为false，则只检索记录摘要（如果存储在服务器上，则检索用户keys）*/
   public boolean includeBinData = true;
   /**如果群集处于迁移状态，则终止扫描*/
   public boolean failOnClusterChange;

1.3.3、命名空间的SC（强一致性）读取策略

/**读取SC（强一致性）命名空间的策略。确定SC读取一致性选项。*/
public enum ReadModeSC {
   /**确保此客户端只能看到记录版本的增加序列。服务器只从主服务器读取。这是默认设置。*/
   SESSION,
   /**确保所有客户机只能看到记录版本的增加序列。服务器只从主服务器读取。*/
   LINEARIZE,
   /**服务器可以从主副本或任何完整（非迁移）副本读取。不能保证记录版本的增加顺序。*/
   ALLOW_REPLICA,
   /**服务器可以从主服务器或任何完整（非迁移）副本或不可用的分区读取。不能保证记录版本的增加顺序。*/
   ALLOW_UNAVAILABLE
}

1.3.4、命名空间的AP（可用性）读取策略

package com.aerospike.client.policy;
/**
 * Read policy for AP (availability) namespaces.
 * <p>
 * How duplicates should be consulted in a read operation.
 * Only makes a difference during migrations and only applicable in AP mode.
命名空间的读取AP（可用性）策略。
读取操作中应如何查询重复项。只会在迁移期间产生差异，并且只适用于AP模式。 
 */
public enum ReadModeAP {
   /**在读取操作中涉及单个节点。*/
   ONE,
   /**在读取操作中涉及所有重复项。*/
   ALL
}

1.4、批量策略BatchPolicy

/**
 * Configuration variables for multi-record get and exist requests.
多记录获取和存在请求的配置变量
 */
public final class BatchPolicy extends Policy {
/**任何时间点到服务器节点的并发同步批处理请求线程的最大数目。如果请求了16个节点/名称空间组合，而maxConcurrentThreads为8，那么将对并行线程中的8个节点/名称空间组合发出批处理请求。当一个请求完成时，将发出一个新的请求，直到所有16个请求都完成。
值：1：按顺序发出批量请求。此模式对于中小型批处理大小具有性能优势，因为可以在主事务线程中发出请求。这是默认设置。
0: 在并行线程中发出所有批处理请求。对于非常大的批处理大小，此模式具有性能优势，因为每个节点都可以立即处理请求。缺点是需要创建额外的线程（或从线程池中获取线程）。
   >0: 在并行线程中最多发出MaxConcurrentthreads批处理请求。当一个请求完成时，将发出一个新的请求，直到所有请求完成。此模式可防止为大型群集实现创建过多的并行线程。缺点是仍需要创建（或从线程池中获取）额外的线程。
注：异步批处理请求忽略此字段，并始终并行发出所有节点请求。*/
public int maxConcurrentThreads = 1;
/**当服务器认为批处理合适时，允许在服务器的接收线程中立即处理批处理。如果为false，则批处理将始终在单独的事务线程中进行。此字段仅与新的批索引协议相关。
对于存在批处理或批量读取较小的记录（每条记录小于等于1K），在“内存中”名称空间上内联处理将显著加快。无论此策略字段如何，服务器都禁用基于磁盘的命名空间的内联处理。
内联处理可能引入不公平的可能性，因为服务器可以在进入下一个命令之前处理整个批处理。默认值：true*/
public boolean allowInline = true;
/**对于批处理索引协议，将批处理中的每个键的“设置名称”字段发送到服务器。只有在启用身份验证并按集合定义安全角色时才需要这样做。默认值：false*/
public boolean sendSetName;

1.5、安全连接策略TlsPolicy

/**TLS连接策略,只有AerospikeClient同步命令才支持安全的TLS连接.*/
public final class TlsPolicy {
......

1.6、副本Replica

public enum Replica {
   /**使用包含键的主分区的节点。*/
   MASTER,
   /**跨包含键的主分区和复制分区的节点分发读取，以循环方式。写入总是使用包含键的主分区的节点。*/
   MASTER_PROLES,
   /**首先尝试包含主分区的节点。如果连接失败，所有命令都尝试包含复制分区的节点。
如果达到socketTimeout，reads也会尝试包含复制分区的节点，但写操作仍保留在主节点上。*/
   SEQUENCE,
   /**首先在客户机所在的机架上尝试节点。如果没有节点在同样的机架上，使用SEQUENCE代替。
    * {@link ClientPolicy#rackAware}, {@link ClientPolicy#rackId}, and server rack configuration must also be set to enable this functionality.*/
   PREFER_RACK,
   /**以循环方式将读取分布到集群中的所有节点。写入总是使用包含键的主分区的节点。 
当复制因子等于集群中的节点数并且不需要请求proles的开销时，此选项非常有用。*/
   RANDOM;
}

1.7、优先级Priority

/**数据库服务器上操作的优先级。*/
public enum Priority {
   /**服务器定义优先级*/
   DEFAULT,
   /**在后台线程中运行数据库操作。*/
   LOW,
   /**以中等优先级运行数据库操作。*/
   MEDIUM,
   /**以最高优先级运行数据库操作。*/
   HIGH
}