In general, CobarClientInternalRouter can accept 4 types of routing rules, but it's usually not necessary for general users to know exactly what these types are. In order to prevent these users from involving too much with the implementation details of CobarClientInternalRouter, we provide a FactoryBean helper to simplify the configuration of CobarClientInternalRouter, this FactoryBean is “com.alibaba.cobar.client.router.config.CobarInteralRouterXmlFactoryBean ” , here is a simple sample on how to use it:

<bean id="internalRouter"
	class="com.alibaba.cobar.client.router.config.CobarInteralRouterXmlFactoryBean">
	<property name="configLocation" value="classpath:META-INF/rules.xml" />
</bean>
						

CobarInteralRouterXmlFactoryBean will read xml-format configuration file and assemble different types of routing rules as per the read content, then inject the assembled routing rules into CobarClientInternalRouter instance. CobarInteralRouterXmlFactoryBean will hide trivial things like read configuration, parse configuration , assemble different types of rule instances,etc. All of these trivial things are transparent to the final users. But, no matter how hard we try to hide these things, the final users still need to provide essential things, for example, the content of the configuration. Only when users provide correctly configured routing rules as per applications' scenarios, CobarClientInternalRouter can work correctly. So in the next section, we will explain more details on how to define routing rules.

A simple sample configuration file for routing rules looks like:

<rules>
  <rule>
    <namespace></namespace> 
    <sqlmap></sqlmap>
    <shardingExpression></shardingExpression>
    <shards></shards>
  </rule>
</rules>
						

<rules> element has more <rule> elements, while <rule> element has 4 more sub-elements:

The definition of rule can be simplified into format of “condition->action” , that's, “(namespace | sqlamp) + shardingExpression -> shards” .

As we see the rule definition is so simple, so it's not mandatory to use DTD or XML schema to validate against the xml configuration files, but if you would like to, the following DTD definition can be used:

<?xml version="1.0"?  encoding="UTF-8"?>

<!ELEMENT rules (rule)+>

<!ELEMENT rule ((namespace|sqlmap),shardingExpression,shards)>

<!ELEMENT namespace (#PCDATA)>

<!ELEMENT sqlmap (#PCDATA)>

<!ELEMENT shardingExpression (#PCDATA)>

<!ELEMENT shards (#PCDATA)>
						

With above theory of routing rules, in the next section, we will explain how to define routing rules as per the scenarios of the applications.

The routing rules seem simple, but before explaining more details about them, maybe you can figure out how to define them, how to use them, even why they should be defined in this way. So now we will explain the details of routing rules for you.

To do data access with iBatis, we need to define a SqlMap configuration file, like this:

<?xml version="1.0" encoding="GB2312"?>
<!DOCTYPE sqlMap PUBLIC "-//iBATIS.com//DTD SQL Map 2.0//EN" "http://www.ibatis.com/dtd/sql-map-2.dtd">
<sqlMap namespace="com.alibaba.cobar.client.entities.Offer">

	<typeAlias alias="offer" type="com.alibaba.cobar.client.entities.Offer" />

	<resultMap id="offer" class="offer">
		<result property="id"     column="id" />
		<result property="memberId"   column="memberId" />
		<result property="subject"   column="subject" />
		<result property="gmtUpdated"   column="gmtUpdated" />
	</resultMap>

	<insert id="create">
		INSERT INTO offers(memberId, subject, gmtUpdated) VALUES(#memberId#, #subject#, #gmtUpdated#)
		<selectKey keyProperty="id" resultClass="long">
			SELECT LAST_INSERT_ID();
        </selectKey>
	</insert>
	...
</sqlMap>
						

As we see, each SqlMap has a “namespace” , and under each namespace, you can define more sql statements, each sql statement has an “id” as its identity. The “namespace” plus “id” of statement can identify each sql statement in global scope. With this prerequisite, let's see how to define the routing rules as per ibatis SqlMap configuration.

Let's start from special scenarios to general ones.

Take the “create” statement as example, Suppose we have an “offer” table and its data is splitted into 2 databases. The partition strategy is: The records with odd memberId will be stored on partition1, while the records with even memberId will be stored on partition2. To route the data access requests on “offer” table, the simple way is to check which sql statement the data access request uses and whether the memberId of the record is odd or not. So 2 routing rules can be defined as:

<rules>
  <rule>
    <sqlmap>com.alibaba.cobar.client.entities.Offer.create</sqlmap>
    <shardingExpression>memberId % 2 == 1</shardingExpression>
    <shards>partition1</shards>
  </rule>
  <rule>
    <sqlmap>com.alibaba.cobar.client.entities.Offer.create</sqlmap>
    <shardingExpression>memberId % 2 == 0</shardingExpression>
    <shards>partition2</shards>
  </rule>
</rules>
						

<sqlmap> element is equal to the sql statement identity, usually the fully qualified name with both “namespace” and “sql statement id” involved. <shardingExpression> defines the sharding expression as per our original partition strategy. At last, <shards> return the final routing result. Until now, I think you should have basic knowledge on how to define the routing rules in CobarClient.

With above basic knowledge, let's change our scenario. We still perform “create” operation, but this time we use vertial parition strategy instead of horizontal partition strategy. That's, all of the “offer” table records will be stored on a same database, now we change our routing rule definitions as below:

<rules>
  <rule>
    <sqlmap>com.alibaba.cobar.client.entities.Offer.create</sqlmap>
    <shardingExpression>memberId % 2 == 1</shardingExpression>
    <shards>partition1</shards>
  </rule>
  <rule>
    <sqlmap>com.alibaba.cobar.client.entities.Offer.create</sqlmap>
    <shardingExpression>memberId % 2 == 0</shardingExpression>
    <shards>partition1</shards>
  </rule>
</rules>
						

As the rule definitions state, no matter the memberId is odd or even, the records will all be stored on “partition1” . But it's stupid to have duplication things here. We can simplify the routing rule definition as below:

<rules>
  <rule>
    <sqlmap>com.alibaba.cobar.client.entities.Offer.create</sqlmap>
    <shards>partition1</shards>
  </rule>
</rules>
						

That's, only a single <sqlmap> element can do here, no shardingExpression element is needed. The rule reads in this way - “As long as I find the sqlmap value is com.alibaba.cobar.client.entities.Offer.create, I will route data access requests to partition1, no matter the memberId of the record is odd or even.”

We call the first style of routing rule as SqlActionShardingRule , while call the 2nd style of routing rule as SqlAction(Only)Rule , They are routing rules to be used under horizontal partition strategy and vertial partition strategy.

Let's further extend the scenarios, obviously, we need to provde update or delete operations for offer table, besides create opertion. So we add more sql statements into SqlMap configuration file as below:

<?xml version="1.0" encoding="GB2312"?>
<!DOCTYPE sqlMap PUBLIC "-//iBATIS.com//DTD SQL Map 2.0//EN" "http://www.ibatis.com/dtd/sql-map-2.dtd">
<sqlMap namespace="com.alibaba.cobar.client.entities.Offer">

	<typeAlias alias="offer" type="com.alibaba.cobar.client.entities.Offer" />

	<resultMap id="offer" class="offer">
		<result property="id"     column="id" />
		<result property="memberId"   column="memberId" />
		<result property="subject"   column="subject" />
		<result property="gmtUpdated"   column="gmtUpdated" />
	</resultMap>

	<insert id="create">
		INSERT INTO offers(memberId, subject, gmtUpdated) VALUES(#memberId#, #subject#, #gmtUpdated#)
		<selectKey keyProperty="id" resultClass="long">
			SELECT LAST_INSERT_ID();
        </selectKey>
	</insert>
	
	<update id="update">
		UPDATE offers SET subject=#subject#, gmtUpdated=#gmtUpdated# WHERE id=#id#
	</update>
	
	<delete id="delete">
		delete from offers where id=#id#
	</delete>
	...
</sqlMap>
						

With only supports of SqlActionShardingRule and SqlAction(Only)Rule , to make the update and delete operations to be routed to correct target databases, we have to add more and more routing rules in our rule configuration files, the problems with this are:

So to improve or fix these problems mentioned above, we introduce two new routing rule types: “NamespaceShardingRule” and “Namespace(Only)Rule” .

NamespaceShardingRule allows us to define routing rules as per namespace in a SqlMap and horizontal sharding strategy. Still take original partition scenario as an example, that's, records with odd memberId will be stored on partition1, and records with even memberId will be stored on partition2. With NamespaceShardingRule, no matter what kinds of opertations are used(update or create), as long as the sql statements are defined under a same namespace(the namespace is com.alibaba.cobar.client.entities.Offer for our scenario), and the context object conforms to the sharding strategy, we can define one single routing rule of kind of NamespaceShardingRule to route the data access requests corretly, a sample such routing rules definition is listed below:

<rules>
  <rule>
    <namespace>com.alibaba.cobar.client.entities.Offer</namespace>
    <shardingExpression>memberId % 2 == 1</shardingExpression>
    <shards>partition1</shards>
  </rule>
  <rule>
    <namespace>com.alibaba.cobar.client.entities.Offer</namespace>
    <shardingExpression>memberId % 2 == 0</shardingExpression>
    <shards>partition2</shards>
  </rule>
</rules>
						

With NamespaceShardingRule, we don't need to define every routing rules as per each data access sql statements. It helps save lot of repeated works on defining almost same routing rules. Further, if all of the data of a table is stored in a same partition(vertical partition scenarios), then we can use a Namespace(Only)Rule to save more configuraton works, a sample Namespace(Only)Rule defintion is listed below:

<rules>
  <rule>
    <namespace>com.alibaba.cobar.client.entities.Offer</namespace>
    <shards>partition1</shards>
  </rule>
</rules>
						

With only this rule, all of the sql statements under namespace “com.alibaba.cobar.client.entities.Offer” will be routed to partition1. .

In conclusion, from SqlActionShardingRule, SqlAction(Only)Rule to NamespaceShardingRule and Namespace(Only)Rule, the routing rule defintions will cover the routing scope from specific to generic ones. If some sql statement needs a special routing requirement, then we can add a SqlActionShardingRule or SqlAction(Only)Rule to meet the need; while if multiple sql statments have similar or same routing requirements, then we can add some NamespaceShardingRule or Namespace(Only)Rule to complete the requests. Anyway, you can use all of the four routing rule types by composition or using them independently to achieve all of the data access routing requirements with iBatis.

Common horizontal partition strategies/algorithm may be:

There are also other partition strategies, like “predicate-based partition” ,etc. In order to meet the needs of different partition strategies, we CobarClient allows to define custom functions in the “shardingExpression” when defining routing rules.

Here follows a simple sample about how to define custom routing functions in CobarClient.

Suppose we will apply some hashing algorithm on memberId, and route the records as per the hashing result of their memberId. Firstly, we need to define a function class which will return a hashing result as per the memberId argument we pass in, we define the function class as below:

public class Hashing{
	...
	int apply(Long memberId){
		// perform real logic here.
	}
}
						

In order to use this function in “shardingExpression” , we need to register it first. We register custom functions via “functionsMap” property of CobarInteralRouterXmlFactoryBean:

<bean id="internalRouter"
	class="com.alibaba.cobar.client.router.config.CobarInteralRouterXmlFactoryBean">
	<property name="functionsMap">
		<map>
			<entry key="hash">
				<bean class="..Hashing">
				</bean>
			</entry>
		</map>
	</property>
	<property name="configLocations">
		<list>
			<value>classpath:META-INF/routing/offer-sql-action-rules.xml</value>
			<value>classpath:META-INF/routing/offer-sharding-rules-on-namespace.xml</value>
		</list>
	</property>
</bean>
						

Pay attention to the key value of our custom function, here it is “hash” .

With all of the above things done, we now can use our custom function in “shardingExpression” , just as the sample below:

<rules>
  <rule>
    <namespace>com.alibaba.cobar.client.entities.Offer</namespace>
    <shardingExpression>hash.apply(memberId) == someValue</shardingExpression>
    <shards>partition1</shards>
  </rule>
  <rule>
    <namespace>com.alibaba.cobar.client.entities.Offer</namespace>
    <shardingExpression>hash.apply(memberId) == anotherValue</shardingExpression>
    <shards>partition2</shards>
  </rule>
</rules>
						

As we can see, the custom function is invoked by the reference of former registered key value, “hash” , you can apply any function methods to the partition context object as long as you have defined those function methods. Easy to understand, right?

If you execute a query SQL with orderby condition with the queryForList() method of CobarSqlMapClientTemplate, the results returned may be not the one you expect, since the default mergence strategy may not help, the order of query result is not guaranteed. But if we want to reuse these ordered result sets and return a final sorted result object, CobarSqlMapClientTemplate does can help on this scenario. The idea is similar to the merge-sort algorithm, that's, the databases help on the latter sort part, and we CobarClient does the former “merge” part.

To use custom mergence strategies, we have to set a group of the mappings between SqlMapActionId and custom mergence strategy implementation via the “mergers” property of CobarSqlMapClientTemplate, here is an example:

<bean id="sqlMapClientTemplateWithMerger" class="com.alibaba.cobar.client.CobarSqlMapClientTemplate">
	<property name="sqlMapClient" ref="sqlMapClient" />
	<property name="cobarDataSourceService" ref="dataSources" />
	<property name="router" ref="internalRouter" />
	<property name="sqlAuditor">
		<bean class="com.alibaba.cobar.client.audit.SimpleSqlAuditor" />
	</property>
	<property name="profileLongTimeRunningSql" value="true" />
	<property name="longTimeRunningSqlIntervalThreshold" value="3600000" />
	<property name="mergers">
		<map>
			<entry
				key="com.alibaba.cobar.client.entities.Offer.findAllWithOrderByOnSubject"
				value-ref="merger" />
		</map>
	</property>
</bean>

<bean id="merger" class="com.alibaba.cobar.client.merger.ConcurrentSortMerger">
	<property name="comparator" ref="comparator">
	</property>
</bean>

<bean id="comparator" class="com.alibaba.cobar.client.support.OfferComparator">
</bean>
						

As the configuration says, all of the query results returned from the execution of “com.alibaba.cobar.client.entities.Offer.findAllWithOrderByOnSubject ” will be merged by using the “merger” we defined. The “merger” we use is an implementation of interface “IMerger” , that's, com.alibaba.cobar.client.merger.ConcurrentSortMerger. Most of the times, ConcurrentSortMerger can suffice our needs, What we need to do is providing a Comparator for it as per the attributes of query results. But if it can do, we can define our own “IMerger” implementations.