diff --git a/ClientAPI.md b/ClientAPI.md new file mode 100644 index 0000000..78cad03 --- /dev/null +++ b/ClientAPI.md @@ -0,0 +1,140 @@ +
+
+ 返回全部博客列表 +
+
+ +

+ 本文为草稿，可在草稿箱中找到！ +

+

预览文章: Canal Client API 编辑 + + 删除 +

+
2013-10-29
+ +
 
+
+ +
+
+

+

快速体验

+

1. 首先需要先启动canal server，可参见：Canal Server的QuickStart

+

2. 运行canal client，可参见：canal client的ClientExample

+

+

如何下载

+

1. 如果是maven用户，可配置mvn dependency

+
<dependency>
+    <groupId>com.alibaba.otter</groupId>
+    <artifactId>canal.client</artifactId>
+    <version>x.y.z</version>
+</dependency>
+

对应的version版本，可见https://github.com/alibaba/canal/releases

+

+

2. 其他用户，可通过mvn仓库直接下载jar包

+

mvn仓库下载url : http://central.maven.org/maven2/com/alibaba/otter/canal.client/

+

选择对应的version，下载jar/source/javadoc文件即可.

+

+

类设计

+

在了解具体API之前，需要提前了解下canal client的类设计，这样才可以正确的使用好canal.

+


+

大致分为几部分：

+
    +
  • ClientIdentity
    canal client和server交互之间的身份标识，目前clientId写死为1001. (目前canal server上的一个instance只能有一个client消费，clientId的设计是为1个instance多client消费模式而预留的，暂时不需要理会)
    • +
  • CanalConnector
    SimpleCanalConnector/ClusterCanalConnector : 两种connector的实现，simple针对的是简单的ip直连模式，cluster针对多ip的模式，可依赖CanalNodeAccessStrategy进行failover控制
    • +
  • CanalNodeAccessStrategy
    SimpleNodeAccessStrategy/ClusterNodeAccessStrategy：两种failover的实现，simple针对给定的初始ip列表进行failover选择，cluster基于zookeeper上的cluster节点动态选择正在运行的canal server.
    • +
  • ClientRunningMonitor/ClientRunningListener/ClientRunningData
    client running相关控制，主要为解决client自身的failover机制。canal client允许同时启动多个canal client，通过running机制，可保证只有一个client在工作，其他client做为冷备. 当运行中的client挂了，running会控制让冷备中的client转为工作模式，这样就可以确保canal client也不会是单点. 保证整个系统的高可用性.
    • +
+

javadoc查看：

+ +

server/client交互协议

+
+


+
具体的协议格式，可参见：CanalProtocol.proto +
+

get/ack/rollback协议介绍：

+ +

canal的get/ack/rollback协议和常规的jms协议有所不同，允许get/ack异步处理，比如可以连续调用get多次，后续异步按顺序提交ack/rollback，项目中称之为流式api.

+

流式api设计的好处：

+ +

流式api设计：

+

+ +

流式api带来的异步响应模型：

+

数据对象格式简单介绍：EntryProtocol.proto +

+
Entry  
+    Header  
+        logfileName [binlog文件名]  
+        logfileOffset [binlog position]  
+        executeTime [binlog里记录变更发生的时间戳,精确到秒]  
+        schemaName   
+        tableName  
+        eventType [insert/update/delete类型]  
+    entryType   [事务头BEGIN/事务尾END/数据ROWDATA]  
+    storeValue  [byte数据,可展开，对应的类型为RowChange]  
+      
+RowChange  
+    isDdl       [是否是ddl变更操作，比如create table/drop table]  
+    sql         [具体的ddl sql]  
+    rowDatas    [具体insert/update/delete的变更数据，可为多条，1个binlog event事件可对应多条变更，比如批处理]  
+        beforeColumns [Column类型的数组，变更前的数据字段]  
+        afterColumns [Column类型的数组，变更后的数据字段]  
+          
+Column   
+    index         
+    sqlType     [jdbc type]  
+    name        [column name]  
+    isKey       [是否为主键]  
+    updated     [是否发生过变更]  
+    isNull      [值是否为null]  
+    value       [具体的内容，注意为string文本]
+

说明：

+ +

Client使用例子

+

+
+

1. 创建Connector

+

1. 创建SimpleCanalConnector (直连ip，不支持server/client的failover机制)

+
CanalConnector connector = CanalConnectors.newSingleConnector(new InetSocketAddress(AddressUtils.getHostIp(),11111), destination, "", "");
+
+
2. 创建ClusterCanalConnector (基于zookeeper获取canal server ip，支持server/client的failover机制) +
CanalConnector connector = CanalConnectors.newClusterConnector("10.20.144.51:2181", destination, "", "");
+3. 创建ClusterCanalConnector (基于固定canal server的地址，支持固定的server ip的failover机制，不支持client的failover机制
+
+
CanalConnector connector = CanalConnectors.newClusterConnector(Arrays.asList(new InetSocketAddress(AddressUtils.getHostIp(),11111)), destination,"", "");
+

+

2. get/ack/rollback使用

+

+
+

+

3. RowData数据处理

+


+

如果需要更详细的exmpale例子，请下载canal当前最新源码包，里面有个example工程，谢谢.

+ \ No newline at end of file