-
Notifications
You must be signed in to change notification settings - Fork 0
Java客户端 Hints说明
本页面包含Dal Hints的详细说明和用法。DalHints是在必须的DB操作参数之外额外传递给DAL的参数，用于：
- 提供DAL完成操作的额外指令，以覆盖缺省值或者缺省计算结果
- 传入特殊参数，例如排序器
- 传出特殊返回值，例如自增id
可用的Dal Hint定义在DalHintEnum，一般通过
hints.set(DalHintEnum.timeout, 1000);
的方式设置。但常用的hints一般会有对应的简化方法直接设置，例如
DalHints hints = context.getHints().timeout(1);
hints支持流式计算风格，可以在一行代码里面设置多个hints
hints.inAllShards().sequentialExecute().asyncExecution(),
关于hints的具体用法，可以参考功能简介
DB操作超时时间，单位秒
DalHints hints = context.getHints().timeout(1);
或者
hints.set(DalHintEnum.timeout, 1000);
指定操作必须使用master数据库。一般来说，CUD操作走master，但R走slave，如果希望R也走matsre，可以使用这个hint
hints.masterOnly()
或者
hints.set(DalHintEnum.masterOnly);
指定操作的事务隔离级别，取值列表如下：
Connection.TRANSACTION_READ_UNCOMMITTED
Connection.TRANSACTION_READ_COMMITTED
Connection.TRANSACTION_REPEATABLE_READ
Connection.TRANSACTION_SERIALIZABLE
Connection.TRANSACTION_NONE
hints.setIsolationLevel(Connection.TRANSACTION_REPEATABLE_READ);
指明查询结果集的类型。取值为ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_INSENSITIVE, or ResultSet.TYPE_SCROLL_SENSITIVE之一
hints.set(DalHintEnum.resultSetType, ResultSet.TYPE_FORWARD_ONLY);
指定结果集的并发属性。取值为ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE之一
hints.set(DalHintEnum.resultSetConcurrency, ResultSet.CONCUR_UPDATABLE);
设置resultSet每次向数据库取的行数
hints.set(DalHintEnum.fetchSize, 1000);
针对调用存储过程的参数设置。如果设置了，则不处理存储过程内部产生的结果集和影响行数。这个参数不影响返回的out参数的获得。
hints.set(DalHintEnum.skipResultsProcessing);
设置resultset最多只返回的行数
hints.set(DalHintEnum.maxRows, 3000);
当对多个entity进行CUD操作的时候，决定是否在某个更新出错的时候继续对剩下的entity进行操作。但对批处理的无效。
hints.continueOnError()
或
hints = new DalHints(DalHintEnum.continueOnError);
int count = dao.insert(hints, pList);
单表操作时，指定是否把entity里面为null的字段也进行update。如果不设置缺省为忽略，即某个字段如果为null，则不会主动把该字段对应的数据库字段也置为null
hints.set(DalHintEnum.updateNullField);
缺省的insert会把传入的id去掉，如果该id对应的数据库字段是自增长的主键，使用这个hint允许插入的时候使用传入的id
dao.insert(new DalHints().enableIdentityInsert(), daoPojo);
在调用任何DAO的API之前设置DalHints为异步执行模式，则执行的结果会放到hints里面，原方法返回null或0。应用在调用结束后取得Future即可。
hints = new DalHints().asyncExecution();
(ClientTestModel)hints.getAsyncResult().get();
指定跨shard操作是否顺序执行，缺省情况下，如果操作需要在多个shard上执行，dal会采取并行执行的方式，通过这个hint可以指定为顺序执行。
hints.inAllShards().sequentialExecute().asyncExecution()
在调用任何DAO的API之前设置DalHints为异步回调模式， 传入回调接口，系统会根据执行情况的正常与否，调用不同的API。参数为DalResultCallback。
hints = new DalHints().callbackWith(callback);
DefaultResultCallback是DAL提供的缺省callback实现，可以参考或使用。
异步和跨shard执行可以结合使用，如下
hints.inAllShards().sequentialExecute().asyncExecution(),
定义当前执行的SQL是否属于敏感语句。如果设置，在记录log的时候会把SQL替换为一个星号" * " . 如果需要设置参数的敏感性，需要调用StatementParameters.setSensitive()方法族，设置后，参数在log里面也会被替换为一个星号" * " 。注意敏感设置和加密是两个不同的概念，可以即敏感又加密。
hints.set(DalHintEnum.sensitive);
通过直接指定shard id的方式决定数据库操作针对哪个shard
model = dao.queryByPk(1, new DalHints().inShard(String.valueOf(i)));
通过直接指定table shard id的方式决定数据库操作针对哪个table shard。可以直接调用DalHints().inTableShard(i)
model = dao.queryByPk(pk, new DalHints().inTableShard(i));
用于分库分表判断的 Map<String, Integer>。key为column name；value 为具体的值。当Dal.config里面配置的Sharding strategy是ShardColModShardStrategy时起作用。
model = dao.queryByPk(1, new DalHints().setShardColValue("index", i));
帮助定位DB shard的值
model = dao.queryByPk(1, new DalHints().setShardValue(String.valueOf(i)));
model = dao.queryByPk(1, new DalHints().setShardValue(i));
帮助定位table shard的值
model = dao.queryByPk(pk, new DalHints().setTableShardValue(i));
指定用于shard判断的参数名称
List<Integer> inParam = new ArrayList<>();
inParam.add(0);
inParam.add(1);
parameters.setInParameter(1, "type", Types.INTEGER, inParam);
new DalQueryDao(DATABASE_NAME).query(
builder, parameters,
hints.shardBy("type"));
如果希望操作在给定的shard范围上执行，可以通过Dalhints的如下设置来实现
Set<String> shards = new HashSet<>();
shards.add("0");
shards.add("1");
hints.inShards(shards);
如果希望操作在所有shard上都执行，可以通过Dalhints的如下设置来实现
hints.inAllShards();
由于查询可以在多个shard上执行，为了保证返回的结果是用户希望的顺序，DAL支持用户自定义的结果合并接口ResultMerger。
List<Short> result = queryListInAllShard(hints.mergeBy(new TestResultMerger()));
由于查询可以在多个shard上执行，为了保证返回的结果是用户希望的顺序，可以简单的传入一个Comparator作为排序的sorter。这个sorter会配合缺省的ResultMerger实现。
List<Short> result = queryListInAllShard(hints.sortBy(new TestComparator()));
Note. This hint is actually useless, there is no use case that we need to use it.
used in batch sp batch update, when set, the connection auto commit will be true.
Note that SQL server does not support auto commit for batch update.
My sql support it. But this won't work when mysql has the following settings in datasource.xml: connectionProperties="rewriteBatchedStatements=true;allowMultiQueries=true"