java typehint_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的具体用法，可以参考功能简介

数据库连接相关hints

timeout

DB操作超时时间，单位秒

DalHints hints = context.getHints().timeout(1);

或者

hints.set(DalHintEnum.timeout, 1000);

masterOnly

指定操作必须使用master数据库。一般来说，CUD操作走master，但R走slave，如果希望R也走matsre，可以使用这个hint

hints.masterOnly()

或者

hints.set(DalHintEnum.masterOnly);

isolationLevel

指定操作的事务隔离级别，取值列表如下：

Connection.TRANSACTION_READ_UNCOMMITTED

Connection.TRANSACTION_READ_COMMITTED

Connection.TRANSACTION_REPEATABLE_READ

Connection.TRANSACTION_SERIALIZABLE

Connection.TRANSACTION_NONE

hints.setIsolationLevel(Connection.TRANSACTION_REPEATABLE_READ);

结果集相关

resultSetType

指明查询结果集的类型。取值为ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_INSENSITIVE, or ResultSet.TYPE_SCROLL_SENSITIVE之一

hints.set(DalHintEnum.resultSetType, ResultSet.TYPE_FORWARD_ONLY);

resultSetConcurrency

指定结果集的并发属性。取值为ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE之一

hints.set(DalHintEnum.resultSetConcurrency, ResultSet.CONCUR_UPDATABLE);

fetchSize

设置resultSet每次向数据库取的行数

hints.set(DalHintEnum.fetchSize, 1000);

skipResultsProcessing

针对调用存储过程的参数设置。如果设置了，则不处理存储过程内部产生的结果集和影响行数。这个参数不影响返回的out参数的获得。

hints.set(DalHintEnum.skipResultsProcessing);

maxRows

设置resultset最多只返回的行数

hints.set(DalHintEnum.maxRows, 3000);

操作相关

continueOnError

当对多个entity进行CUD操作的时候，决定是否在某个更新出错的时候继续对剩下的entity进行操作。但对批处理的无效。

hints.continueOnError()

或

hints = new DalHints(DalHintEnum.continueOnError);

int count = dao.insert(hints, pList);

updateNullField

单表操作时，指定是否把entity里面为null的字段也进行update。如果不设置缺省为忽略，即某个字段如果为null，则不会主动把该字段对应的数据库字段也置为null

hints.set(DalHintEnum.updateNullField);

enableIdentityInsert

缺省的insert会把传入的id去掉，如果该id对应的数据库字段是自增长的主键，使用这个hint允许插入的时候使用传入的id

dao.insert(new DalHints().enableIdentityInsert(), daoPojo);

asyncExecution

在调用任何DAO的API之前设置DalHints为异步执行模式，则执行的结果会放到hints里面，原方法返回null或0。应用在调用结束后取得Future即可。

hints = new DalHints().asyncExecution();

(ClientTestModel)hints.getAsyncResult().get();

sequentialExecution

指定跨shard操作是否顺序执行，缺省情况下，如果操作需要在多个shard上执行，dal会采取并行执行的方式，通过这个hint可以指定为顺序执行。

hints.inAllShards().sequentialExecute().asyncExecution()

resultCallback

在调用任何DAO的API之前设置DalHints为异步回调模式， 传入回调接口，系统会根据执行情况的正常与否，调用不同的API。参数为DalResultCallback。

hints = new DalHints().callbackWith(callback);

DefaultResultCallback是DAL提供的缺省callback实现，可以参考或使用。

异步和跨shard执行可以结合使用，如下

hints.inAllShards().sequentialExecute().asyncExecution(),

sensitive

定义当前执行的SQL是否属于敏感语句。如果设置，在记录log的时候会把SQL替换为一个星号" * " . 如果需要设置参数的敏感性，需要调用StatementParameters.setSensitive()方法族，设置后，参数在log里面也会被替换为一个星号" * " 。注意敏感设置和加密是两个不同的概念，可以即敏感又加密。

hints.set(DalHintEnum.sensitive);

数据库或表的shard相关

shard

通过直接指定shard id的方式决定数据库操作针对哪个shard

model = dao.queryByPk(1, new DalHints().inShard(String.valueOf(i)));

tableShard

通过直接指定table shard id的方式决定数据库操作针对哪个table shard。可以直接调用DalHints().inTableShard(i)

model = dao.queryByPk(pk, new DalHints().inTableShard(i));

shardColValues

用于分库分表判断的 Map。key为column name；value 为具体的值。当Dal.config里面配置的Sharding strategy是ShardColModShardStrategy时起作用。

model = dao.queryByPk(1, new DalHints().setShardColValue("index", i));

shardValue

帮助定位DB shard的值

model = dao.queryByPk(1, new DalHints().setShardValue(String.valueOf(i)));

model = dao.queryByPk(1, new DalHints().setShardValue(i));

tableShardValue

帮助定位table shard的值

model = dao.queryByPk(pk, new DalHints().setTableShardValue(i));

shardBy

指定用于shard判断的参数名称

List 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"));

shards

如果希望操作在给定的shard范围上执行，可以通过Dalhints的如下设置来实现

Set shards = new HashSet<>();

shards.add("0");

shards.add("1");

hints.inShards(shards);

allShards

如果希望操作在所有shard上都执行，可以通过Dalhints的如下设置来实现

hints.inAllShards();

resultMerger

由于查询可以在多个shard上执行，为了保证返回的结果是用户希望的顺序，DAL支持用户自定义的结果合并接口ResultMerger。

List result = queryListInAllShard(hints.mergeBy(new TestResultMerger()));

resultSorter

由于查询可以在多个shard上执行，为了保证返回的结果是用户希望的顺序，可以简单的传入一个Comparator作为排序的sorter。这个sorter会配合缺省的ResultMerger实现。

List result = queryListInAllShard(hints.sortBy(new TestComparator()));

其他

forceAutoCommit

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"