update doc and add example of hint sharding value

hanahmily · hanahmily · commit 010c917ae617 · 2016-03-04T13:05:20.000+08:00
diff --git a/sharding-jdbc-core/src/main/java/com/dangdang/ddframe/rdb/sharding/api/HintShardingValueManager.java b/sharding-jdbc-core/src/main/java/com/dangdang/ddframe/rdb/sharding/api/HintShardingValueManager.java
@@ -47,7 +47,7 @@ public final class HintShardingValueManager {
      */
     public static void init() {
         if (null != SHARING_VALUE_CONTAINER.get()) {
-            throw new ShardingJdbcException("CAN NOT register sharding value repeatedly");
+            throw new ShardingJdbcException("CAN NOT init repeatedly");
         }
         SHARING_VALUE_CONTAINER.set(new ShardingValueContainer());
     }
diff --git a/sharding-jdbc-core/src/main/java/com/dangdang/ddframe/rdb/sharding/router/single/SingleTableRouter.java b/sharding-jdbc-core/src/main/java/com/dangdang/ddframe/rdb/sharding/router/single/SingleTableRouter.java
@@ -82,7 +82,7 @@ private Collection<String> routeDataSources() {
         Optional<List<ShardingValue<?>>> hintDatabaseShardingValues = HintShardingValueManager.getShardingValueOfDatabase(logicTable);
         List<ShardingValue<?>> databaseShardingValues;
         if (hintDatabaseShardingValues.isPresent()) {
-            databaseShardingValues = hintDatabaseShardingValues.get();
+            databaseShardingValues = filterShardingValue(strategy.getShardingColumns(), hintDatabaseShardingValues.get());
         } else {
             databaseShardingValues = getShardingValues(strategy.getShardingColumns());
         }
@@ -98,7 +98,7 @@ private Collection<String> routeTables(final Collection<String> routedDataSource
         Optional<List<ShardingValue<?>>> hintTableShardingValues = HintShardingValueManager.getShardingValueOfTable(logicTable);
         List<ShardingValue<?>> tableShardingValues;
         if (hintTableShardingValues.isPresent()) {
-            tableShardingValues = hintTableShardingValues.get();
+            tableShardingValues = filterShardingValue(strategy.getShardingColumns(), hintTableShardingValues.get());
         } else {
             tableShardingValues = getShardingValues(strategy.getShardingColumns());
         }
@@ -120,6 +120,16 @@ private List<ShardingValue<?>> getShardingValues(final Collection<String> shardi
         return result;
     }
     
+    private List<ShardingValue<?>> filterShardingValue(final Collection<String> shardingColumns, final List<ShardingValue<?>> shardingValues) {
+        List<ShardingValue<?>> result = new ArrayList<>(shardingColumns.size());
+        for (ShardingValue<?> each : shardingValues) {
+            if (shardingColumns.contains(each.getColumnName())) {
+                result.add(each);
+            }
+        }
+        return result;
+    }
+    
     private void logBeforeRoute(final String type, final String logicTable, final Collection<?> targets, final Collection<String> shardingColumns, final List<ShardingValue<?>> shardingValues) {
         log.trace("Before {} sharding {} routes db names: {} sharding columns: {} sharding values: {}", type, logicTable, targets, shardingColumns, shardingValues);
     }
diff --git a/sharding-jdbc-core/src/test/java/com/dangdang/ddframe/rdb/integrate/AbstractDBUnitTest.java b/sharding-jdbc-core/src/test/java/com/dangdang/ddframe/rdb/integrate/AbstractDBUnitTest.java
@@ -17,8 +17,6 @@
 
 package com.dangdang.ddframe.rdb.integrate;
 
-import static org.dbunit.Assertion.assertEquals;
-
 import java.io.File;
 import java.io.InputStream;
 import java.io.InputStreamReader;
@@ -28,9 +26,9 @@
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
-
 import javax.sql.DataSource;
 
+import com.dangdang.ddframe.rdb.sharding.api.DatabaseType;
 import org.apache.commons.dbcp.BasicDataSource;
 import org.dbunit.DatabaseUnitException;
 import org.dbunit.IDatabaseTester;
@@ -44,11 +42,11 @@
 import org.h2.tools.RunScript;
 import org.junit.Before;
 
-import com.dangdang.ddframe.rdb.sharding.api.DatabaseType;
+import static org.dbunit.Assertion.assertEquals;
 
 public abstract class AbstractDBUnitTest {
     
-    public static final DatabaseType CURRENT_DB_TYPE = DatabaseType.H2;
+    public static final DatabaseType CURRENT_DB_TYPE = DatabaseType.MySQL;
     
     private static final Map<String, DataSource> DATA_SOURCES = new HashMap<>();
     
diff --git a/sharding-jdbc-core/src/test/java/com/dangdang/ddframe/rdb/sharding/router/AbstractDynamicRouteSqlTest.java b/sharding-jdbc-core/src/test/java/com/dangdang/ddframe/rdb/sharding/router/AbstractDynamicRouteSqlTest.java
@@ -45,8 +45,8 @@ protected void assertMultipleTargets(final List<ShardingValuePair> shardingValue
                                          final Collection<String> targetDataSources, final Collection<String> targetSQLs) throws SQLParserException {
         HintShardingValueManager.init();
         for (ShardingValuePair each : shardingValuePairs) {
-            HintShardingValueManager.registerShardingValueOfDatabase(each.logicTable, "dynamic_virtual_order_id", each.binaryOperator, each.shardingValue);
-            HintShardingValueManager.registerShardingValueOfTable(each.logicTable, "dynamic_virtual_order_id", each.binaryOperator, each.shardingValue);
+            HintShardingValueManager.registerShardingValueOfDatabase(each.logicTable, "order_id", each.binaryOperator, each.shardingValue);
+            HintShardingValueManager.registerShardingValueOfTable(each.logicTable, "order_id", each.binaryOperator, each.shardingValue);
         }
         
         assertMultipleTargets(originSql, parameters, expectedSize, targetDataSources, targetSQLs);
diff --git a/sharding-jdbc-doc/content/post/hint_shardingvalue.md b/sharding-jdbc-doc/content/post/hint_shardingvalue.md
@@ -0,0 +1,72 @@
++++
+date = "2016-02-05T17:03:18+08:00"
+title = "基于暗示的分片键值注册方法"
+weight = 12
++++
+
+# 基于暗示的分片键值注册方法
+
+> 提示:阅读本文前请详细预读 [使用指南](../user_guide)
+
+## 背景
+对`Shanrding-JDBC`有初步了解的朋友已经发现了：在编写分片算法的时候，传入的分片键值是来自`SQL`语句中`WHERE`条件的。
+例如逻辑表`t_order`如果其数据源分片键为`user_id`，
+分片算法是奇数值路由到`db1`偶数值路由到`db2`；表分片键为`order_id`，
+分片算法是奇数值路由到`t_order_1`偶数值路由到`t_order_2`，如果执行如下sql语句：
+```sql
+select * from t_order where user_id = 1 and order_id = 2
+```
+那么在数据源分片算法的`shardingValue`参数将会传入`1`用于分片计算，结果为路由到`db1`;
+表分片算法的`shardingValue`参数将会传入`2`用于分片计算，结果为路由到`t_order_2`。最终SQL为：
+```sql
+select * from db1.t_order_2 where user_id = 1 and order_id = 2
+```
+
+__现有一个假设，如果`WHERE`中没有`user_id`和`order_id`的条件，那么是否可以进行分片计算呢？__
+
+答案是肯定的。下面就介绍一下`Sharding-JDBC`对这个问题的解决方法。
+
+## 基于暗示的分片键值管理器
+要解决上面的问题，我们使用`com.dangdang.ddframe.rdb.sharding.api.HintShardingValueManager`。
+该管理器是使用`ThreadLocal`技术管理分片键值的。
+使用例子：
+```java
+String sql = "SELECT * FROM t_order";
+        
+try (
+        Connection conn = dataSource.getConnection();
+        PreparedStatement pstmt = conn.prepareStatement(sql)) {
+    HintShardingValueManager.init();
+    HintShardingValueManager.registerShardingValueOfDatabase("t_order", "user_id", 1);
+    HintShardingValueManager.registerShardingValueOfTable("t_order", "order_id", 2);
+    try (ResultSet rs = pstmt.executeQuery()) {
+        while (rs.next()) {
+            ...
+        }
+    }
+} finally {
+    HintShardingValueManager.clear();
+}
+```
+
+### 初始化方法
+使用`HintShardingValueManager.init()`表示开始执行操作，此时会初始化`ThreadLocal`中的数据。
+
+注意：__在一个线程中只能初始化一次__。否则会抛出`CAN NOT init repeatedly`的异常。
+
+### 注册分片键值
+- 使用`HintShardingValueManager.registerShardingValueOfDatabase`来注册数据源分片键值
+- 使用`HintShardingValueManager.registerShardingValueOfTable`来注册表分片键值
+
+每种分片键值注册方法中有两个重载方法，参数较短的方法可以简化相等条件的分片值注入。
+
+### 清除注册的分片键值
+由于分片键值保存在`ThreadLocal`中，所以需要在操作结束的使用调用`HintShardingValueManager.clear()`来清除`ThreadLocal`中的内容。
+如果你没有调用该方法，那么在该线程被复用时（线程池场景），`HintShardingValueManager.init()`被调用将抛出`CAN NOT init repeatedly`异常。
+
+__建议使用`try-finally`或者`AOP`编程的方式来调用清除方法__
+
+
+
+
+
diff --git a/sharding-jdbc-doc/content/post/release_notes.md b/sharding-jdbc-doc/content/post/release_notes.md
@@ -7,7 +7,11 @@ weight = 1
 # Release Notes
 
 ## 1.0.1-snapshot
-1.增加使用ThreadLocal方式动态生成分区键值的方式进行SQL路由的功能
+功能提升:
+
+1. 增加使用暗示(Hint)方式注册分片键值的方式进行SQL路由的功能
+
+bug修改:
 
 1. 修正JPA与Sharding-JDBC的兼容问题。JPA会自动增加SELECT的列别名，导致ORDER BY只能通过别名，而非列名称获取ResultSet的数据。
 1. 修正[issue #11](https://github.com/dangdangdotcom/sharding-jdbc/issues/11) count函数在某些情况下返回不正确
diff --git a/sharding-jdbc-doc/content/post/user_guide.md b/sharding-jdbc-doc/content/post/user_guide.md
@@ -385,3 +385,5 @@ String sql = "SELECT i.* FROM t_order o JOIN t_order_item i ON o.order_id=i.orde
         }
 ```
 该数据源与普通数据源完全相同，你可以通过上例的API形式来使用，也可以将其配置在Spring，Hibernate等框架中使用。
+
+> 如果希望不依赖于表中的列传入分片键值，参考：[基于暗示的分片键值注册方法](../hint_shardingvalue)
diff --git a/sharding-jdbc-example/sharding-jdbc-example-jdbc/src/main/java/com/dangdang/ddframe/rdb/sharding/example/jdbc/Main.java b/sharding-jdbc-example/sharding-jdbc-example-jdbc/src/main/java/com/dangdang/ddframe/rdb/sharding/example/jdbc/Main.java
@@ -24,11 +24,9 @@
 import java.util.Arrays;
 import java.util.HashMap;
 import java.util.Map;
-
 import javax.sql.DataSource;
 
-import org.apache.commons.dbcp.BasicDataSource;
-
+import com.dangdang.ddframe.rdb.sharding.api.HintShardingValueManager;
 import com.dangdang.ddframe.rdb.sharding.api.ShardingDataSource;
 import com.dangdang.ddframe.rdb.sharding.api.rule.BindingTableRule;
 import com.dangdang.ddframe.rdb.sharding.api.rule.DataSourceRule;
@@ -38,6 +36,7 @@
 import com.dangdang.ddframe.rdb.sharding.api.strategy.table.TableShardingStrategy;
 import com.dangdang.ddframe.rdb.sharding.example.jdbc.algorithm.ModuloDatabaseShardingAlgorithm;
 import com.dangdang.ddframe.rdb.sharding.example.jdbc.algorithm.ModuloTableShardingAlgorithm;
+import org.apache.commons.dbcp.BasicDataSource;
 // CHECKSTYLE:OFF
 public final class Main {
     
@@ -47,6 +46,8 @@ public static void main(final String[] args) throws SQLException {
         printSimpleSelect(dataSource);
         System.out.println("--------------");
         printGroupBy(dataSource);
+        System.out.println("--------------");
+        printHintSimpleSelect(dataSource);
     }
     
     private static void printSimpleSelect(final DataSource dataSource) throws SQLException {
@@ -79,6 +80,27 @@ private static void printGroupBy(final DataSource dataSource) throws SQLExceptio
         }
     }
     
+    private static void printHintSimpleSelect(final DataSource dataSource) throws SQLException {
+        String sql = "SELECT i.* FROM t_order o JOIN t_order_item i ON o.order_id=i.order_id";
+        
+        try (
+                Connection conn = dataSource.getConnection();
+                PreparedStatement pstmt = conn.prepareStatement(sql)) {
+            HintShardingValueManager.init();
+            HintShardingValueManager.registerShardingValueOfDatabase("t_order", "user_id", 10);
+            HintShardingValueManager.registerShardingValueOfTable("t_order", "order_id", 1001);
+            try (ResultSet rs = pstmt.executeQuery()) {
+                while (rs.next()) {
+                    System.out.println(rs.getInt(1));
+                    System.out.println(rs.getInt(2));
+                    System.out.println(rs.getInt(3));
+                }
+            }
+        } finally {
+            HintShardingValueManager.clear();
+        }
+    }
+    
     private static ShardingDataSource getShardingDataSource() throws SQLException {
         DataSourceRule dataSourceRule = new DataSourceRule(createDataSourceMap());
         TableRule orderTableRule = new TableRule("t_order", Arrays.asList("t_order_0", "t_order_1"), dataSourceRule);

Original file line number	Diff line number	Diff line change
`@@ -47,7 +47,7 @@ public final class HintShardingValueManager {`
`47`	`47`	`*/`
`48`	`48`	`public static void init() {`
`49`	`49`	`if (null != SHARING_VALUE_CONTAINER.get()) {`
`50`		`- throw new ShardingJdbcException("CAN NOT register sharding value repeatedly");`
	`50`	`+ throw new ShardingJdbcException("CAN NOT init repeatedly");`
`51`	`51`	`}`
`52`	`52`	`SHARING_VALUE_CONTAINER.set(new ShardingValueContainer());`
`53`	`53`	`}`
Original file line number	Diff line number	Diff line change
`@@ -385,3 +385,5 @@ String sql = "SELECT i.* FROM t_order o JOIN t_order_item i ON o.order_id=i.orde`
`385`	`385`	`}`
`386`	`386`	```
`387`	`387`	`该数据源与普通数据源完全相同，你可以通过上例的API形式来使用，也可以将其配置在Spring，Hibernate等框架中使用。`
	`388`	`+`
	`389`	`+> 如果希望不依赖于表中的列传入分片键值，参考：[基于暗示的分片键值注册方法](../hint_shardingvalue)`