开发指南

Save this PDF as:
 WORD  PNG  TXT  JPG

Size: px
Start display at page:

Download "开发指南"

Transcription

1 分布式缓存服务 开发指南 发布日期

2 目录 目录 1 简介 DCS IMDG SDK 能做什么 内容导航 相关资源 DCS IMDG 快速入门 开发流程 DCS 服务环境搭建 SDK 开发环境搭建 配置认证参数 编码实现 典型场景开发 对缓存数据进行读写操作 使用 SQL 进行表操作 常见问题 如何开发一个应用 连接超时 A 文档修订记录 ii

3 1 简介 1 简介 1.1 DCS IMDG SDK 能做什么 1.2 内容导航 1.1 DCS IMDG SDK 能做什么 说明 DCS IMDG SDK 介绍 IMDG 仅部分 region 支持, 是否支持 IMDG 请以控制台为准 本文仅适用于支持 IMDG 的 region DCS IMDG SDK 提供基于 GridGain 的接口, 第三方应用程序直接使用 DCS IMDG SDK 即可实现对缓存数据的读 写 删除等操作 具体的接口请参见对应的接口参考文档 关键特性介绍 兼容 ACID: 存储在 IMDG 实例中的数据, 支持 ACID, 可以在整个网络的多台服务器上保持事务 支持完整的 SQL DDL 和 DML: IMDG 支持完整的 SQL DDL 和 DML, 可以单独使用 SQL 而不需要用代码与 IMDG 进行交互, 既只使用 SQL 就可以创建表和索引, 以及插入 更新和查询数据 有这个完整的 SQL 支持,IMDG 就可以作为一种分布式 SQL 数据库 基于 JCache(JSR107) 实现 : IMDG 的 IgniteCache 基于 JCache(JSR107), 提供了 JCache 规范之外的有用的其他功能, 比如数据加载, 查询, 异步模型等

4 1 简介 1.2 内容导航 表 1-1 内容导航 章节简介相关资源快速入门典型场景开发常见问题 内容 简要介绍 DCS IMDG SDK 的概念 介绍使用 DCS IMDG SDK 进行二次开发过程中涉及到的资源信息, 包括 SDK 下载地址 开发工具等 介绍使用 DCS IMDG SDK 进行 demo 开发的全过程 如果您想快速使用 DCS IMDG SDK 进行开发, 可以先阅读这一章节 介绍 DCS 典型功能场景的开发, 包括样例代码 代码说明和注意事项等 解答使用 DCS IMDG SDK 过程中的常见问题

5 2 相关资源 2 相关资源 资源下载 DCS IMDG SDK 下载 DCS IMDG API 下载 DCS IMDG Demo 示例工程下载 DCS IMDG Demo 示例工程基于 DCS IMDG SDK 开发, 包含 DCS IMDG SDK 基本功能的示例代码 后续章节会基于该示例工程介绍使用 DCS IMDG SDK 进行开发的流程, 以及典型场景的开发 开发工具 Eclipse:Eclipse 及以上版本, 可至 Eclipse 官方网站下载 JDK:Java Development Kit 及以上版本, 可至 Oracle 官方下载页面下载 Maven:Apache Maven 及以上版本

6 3 DCS IMDG 快速入门 3 DCS IMDG 快速入门 本章节介绍如何使用 DCS IMDG Demo 的示例快速体验 DCS 的 IMDG API 3.1 开发流程 3.2 DCS 服务环境搭建 3.3 SDK 开发环境搭建 3.4 配置认证参数 3.5 编码实现 3.1 开发流程 本示例以 Java 语言为例进行 DCS IMDG SDK 的二次集成开发 实现流程如下 :

7 3 DCS IMDG 快速入门 3.2 DCS 服务环境搭建 DCS 服务环境搭建过程中, 需要按照表 3-1 记录 DCS 服务的环境信息, 以备后续使用 表 3-1 环境信息汇总 类型 项目 记录的信息 ( 以下为示例, 请根据实际情况替 换 ) 弹性云服务器 (Window s 系统 ) 弹性 IP - 私有 IP hostname 弹性云服务器的主机名 用户名 密码 administrator password 分布式缓存服务 实例的连接地址单机 : 集群 : , 实例的用户名 实例的密码 username password 注册云服务帐号 如果已申请过华为云服务帐号, 可以跳过此步骤 步骤 1 步骤 2 步骤 3 步骤 4 打开公有云服务网址 单击页面右上方的 注册, 注册新账号 按照页面要求填写用户信息 通过邮件激活账号 使用注册的用户, 登录公有云服务 说明 如果您需要使用付费服务, 请单击首页右上角的用户名, 选择 费用中心, 单击 充值 按钮, 充值成功后, 即可访问付费服务 ---- 结束 申请弹性云服务器 通过浏览器登录华为云, 在弹性云服务器控制台中创建一台 Windows 弹性云服务器, 并绑定弹性 IP 请注意记录弹性 IP 地址 用户名和密码, 后续访问 IMDG 需要使用 如果已申请过华为云弹性云服务器, 可以跳过此步骤

8 3 DCS IMDG 快速入门 说明 创建 IMDG 缓存实例 您创建的弹性云服务器必须与该缓存实例属于同一个 VPC, 并配置相同的安全组, 以确保弹性云服务器与缓存实例的网络是连通的 如果弹性云服务器与缓存实例不在相同 VPC 中, 可以通过建立 VPC 对等连接方式连通网络, 具体请参考缓存实例是否支持跨 VPC 访问? 如果弹性云服务器与缓存实例配置了不同的安全组, 可以通过设置安全组规则连通网络, 具体请参考如何选择和配置安全组? 说明 您创建的 IMDG 缓存实例必须与弹性云服务器属于同一个 VPC 和子网, 以确保弹性云服务器与 IMDG 缓存实例的网络是连通的 通过浏览器登录华为云, 在分布式缓存服务控制台中创建 IMDG 缓存实例 记录创建缓存实例时输入的用户名 密码, 以及实例创建完成后 console 页面显示的连接地址 3.3 SDK 开发环境搭建 本节操作均是在申请弹性云服务器申请的 Windows 弹性云服务器上进行, 以便联调 Java 环境配置 本 SDK 包要求的 JDK 版本为 及以上版本, 以下步骤以 win7 环境配置 JDK8 64 位为例, 若已经下载 JDK 并配置好环境请忽略本章节 步骤 1 步骤 2 步骤 3 步骤 4 下载 JDK 文件 下载地址为 :Oracle 官方下载页面 下载完成后按照提示安装, 位置自选, 比如安装到本地 C:\Program Files\Java \jdk1.8.0_172 配置 Java 环境变量 1. 打开系统 控制面板, 然后选择 系统和安全 > 系统 > 高级系统设置, 打开了 系统属性 窗口 2. 切换到 高级 页签, 单击 环境变量, 打开了 环境变量 窗口 3. 新建系统变量 JAVA_HOME, 变量值为实际 JDK 安装位置 4. 在 path 中添加 %JAVA_HOME%\bin;%JAVA_HOME%\jre\bin( 注意用英文分号分隔 ) 5. 新建系统变量 CLASSPATH, 变量值为 %JAVA_HOME%\lib\dt.jar;%JAVA_HOME% \lib\tools.jar 打开命令行窗口, 输入 java -version, 显示如下图所示表示配置成功 ---- 结束

9 3 DCS IMDG 快速入门 下载示例工程 下载 DCS IMDG Demo 示例工程代码并解压到本地 下载地址 : 更多示例代码可参考 java/org/apache/ignite/examples 下载 Eclipse 安装与 Demo 示例工程导入 SDK 开发环境需要使用 Eclipse 及以上版本 下面以 eclipse 工具为例给出 Demo 示例工程导入步骤, 如果使用其他 IDE 工具, 请参照处理 : 步骤 1 在 Eclipse 官方网站下载对应平台的 eclipse 版本, 比如 :eclipse-jee-mars-r-win32- x86_64.zip 步骤 2 解压后直接打开 eclipse 步骤 3 步骤 4 确保 Windows>Preferences>Java>Installed JREs 配置正确的 JRE 路径 在左侧工程上单击右键, 选择 Build path->configure Build Path..., 在弹出框中左边选择 Java Build Path, 在右边选择 Libraries 页签, 然后点击右边的 Add External JARs..., 选择 DCS IMDG Demo 示例工程所在的本地位置 说明 如果需要导入 DCS IMDG SDK 包, 则应先新建一个工程, 然后按照此步骤引入对应 DCS IMDG SDK 包 步骤 5 单击 OK, 导入 Demo 示例工程, 导入后打开工程 ---- 结束

10 3 DCS IMDG 快速入门 3.4 配置认证参数 本节描述如何在 Demo 工程中配置连接缓存实例的用户名 密码 实例连接地址等信息 上述信息已在创建 IMDG 缓存实例时记录 步骤 1 在 IDE 修改 src/main/resources 目录下的 example-cache.xml 文件, 设置 username password 和 multicastgroup 其中标红内容需要替换为实际值 : username_for_replace 替换为实例的用户名 password_for_replace 替换为实例的密码 和 替换为实例的连接地址 若有多个 IP, 则需添加多行 <value>xxx</value>, 其中 XXX 为实例的连接地址 <bean id="allowall.cred" class="org.apache.ignite.plugin.security.securitycredentials"> <constructor-arg value="username_for_replace"/> <constructor-arg value="password_for_replace"/> </bean>.. <property name="discoveryspi"> <bean class="org.apache.ignite.spi.discovery.tcp.tcpdiscoveryspi"> <property name="ipfinder"> <bean class="org.apache.ignite.spi.discovery.tcp.ipfinder.vm.tcpdiscoveryvmipfinder"> <property name="addresses"> <list> <value> </value> <value> </value> </list> </property> </bean> </property> </bean> </property> ---- 结束 3.5 编码实现 典型场景的编码实现请参考典型场景开发

11 4 典型场景开发 4 典型场景开发 4.1 对缓存数据进行读写操作 4.2 使用 SQL 进行表操作 4.1 对缓存数据进行读写操作 向 DCS IMDG 实例写入, 读取和删除数据 代码示例 import org.apache.ignite.ignite; import org.apache.ignite.ignitecache; import org.apache.ignite.igniteexception; import org.apache.ignite.ignition; import org.apache.ignite.configuration.cacheconfiguration; import java.util.hashmap; import java.util.map; import java.util.uuid; /** * This example demonstrates very basic operations on cache, such as 'put' and 'get'. * <p> * Remote nodes should always be started */ public class CachePutGetExample /** Cache name. */ private static final String CACHE_NAME = "CachePutGetExample"; /** * Executes example. * args Command line arguments, none required. IgniteException If example execution failed. */ public static void main(string[] args) throws IgniteException try (Ignite ignite = Ignition.start("config/example-cache.xml")) CacheConfiguration<Integer, String> cachecfg = new CacheConfiguration<>(CACHE_NAME); //if you want see the cache metric in ces, set the statisticsenabled as true cachecfg.setstatisticsenabled(true); //if your imdg instance is cluster and want to backup your cache, you can set the

12 4 典型场景开发 backups param. default is 0 cachecfg.setbackups(0); try (IgniteCache<Integer, String> cache = ignite.getorcreatecache(cachecfg)) // Individual puts and gets. putget(cache); // Bulk puts and gets. putallgetall(cache); finally //ignite.destroycache(cache_name); /** * Execute individual puts and gets. * IgniteException If failed. */ private static void putget(ignitecache<integer, String> cache) throws IgniteException System.out.println(">>> Cache put-get example started."); final int keycnt = 5; // Store keys in cache. for (int i = 0; i < keycnt; i++) cache.put(i, UUID.randomUUID().toString()); System.out.println(">>> Stored values in cache. key size is " + keycnt); for (int i = 0; i < keycnt; i++) cache.get(i); cache.remove(i); System.out.println(">>> get and remove value in cache. key is " + i); /** * Execute putall(...) getall(...) operations. * IgniteException If failed. */ private static void putallgetall(ignitecache<integer, String> cache) throws IgniteException System.out.println(">>> Starting putall-getall example."); final int keycnt = 5; // Create batch. Map<Integer, String> batch = new HashMap<>(); for (int i = 0; i < keycnt; i++) batch.put(i, "bulk-" + Integer.toString(i)); // Bulk-store entries in cache. cache.putall(batch); System.out.println(">>> Bulk-stored values in cache.");

13 4 典型场景开发 // Bulk-get values from cache. Map<Integer, String> vals = cache.getall(batch.keyset()); for (Map.Entry<Integer, String> e : vals.entryset()) System.out.println("Got entry [key=" + e.getkey() + ", val=" + e.getvalue() + ']'); 代码说明 从 example-cache.xml 配置文件中读取连接 IMDG 实例的配置信息, 连接到 IMDG 实例 创建名字为 CachePutGetExample 的缓存, 备份个数 backup 设置为 0 往缓存中写入 key 为 0-4,value 为随机数的 5 个值, 从缓存中把值读取之后, 删除 往缓存中批量写入, 读取数值 4.2 使用 SQL 进行表操作 本节示例介绍如何使用 SQL 语言创建 删除表结构, 以及对创建的表进行写入 查询操作 代码示例 import org.apache.ignite.ignite; import org.apache.ignite.ignitecache; import org.apache.ignite.ignition; import org.apache.ignite.cache.query.sqlfieldsquery; import org.apache.ignite.configuration.cacheconfiguration; import java.util.list; /** * Example to showcase DDL capabilities of Ignite's SQL engine. * <p> * Remote nodes could be started * <p> */ public class CacheQueryDdlExample /** Dummy cache name. */ private static final String DUMMY_CACHE_NAME = "CacheQueryDdlExample"; /** * Executes example. * args Command line arguments, none required. Exception If example execution failed. "ThrowFromFinallyBlock") public static void main(string[] args) throws Exception try (Ignite ignite = Ignition.start("config/example-cache.xml")) print("cache query DDL example started."); // Create dummy cache to act as an entry point for SQL queries (new SQL API which do not require this // will appear in future versions, JDBC and ODBC drivers do not require it already). CacheConfiguration<?,?> cachecfg = new CacheConfiguration<>(DUMMY_CACHE_NAME).setSqlSchema("PUBLIC"); try (IgniteCache<?,?> cache = ignite.getorcreatecache(cachecfg))

14 4 典型场景开发 // Create reference City table based on REPLICATED template. cache.query(new SqlFieldsQuery( "CREATE TABLE city (id LONG PRIMARY KEY, name VARCHAR) WITH \"template=replicated\"")).getall(); // Create table based on PARTITIONED template with one backup. cache.query(new SqlFieldsQuery( "CREATE TABLE person (id LONG, name VARCHAR, city_id LONG, PRIMARY KEY (id, city_id)) " + "WITH \"backups=1, affinitykey=city_id\"")).getall(); // Create an index. cache.query(new SqlFieldsQuery("CREATE INDEX on Person (city_id)")).getall(); print("created database objects."); (?,?)"); SqlFieldsQuery qry = new SqlFieldsQuery("INSERT INTO city (id, name) VALUES cache.query(qry.setargs(1l, "Forest Hill")).getAll(); cache.query(qry.setargs(2l, "Denver")).getAll(); cache.query(qry.setargs(3l, "St. Petersburg")).getAll(); (?,?,?)"); qry = new SqlFieldsQuery("INSERT INTO person (id, name, city_id) values cache.query(qry.setargs(1l, "John Doe", 3L)).getAll(); cache.query(qry.setargs(2l, "Jane Roe", 2L)).getAll(); cache.query(qry.setargs(3l, "Mary Major", 1L)).getAll(); cache.query(qry.setargs(4l, "Richard Miles", 2L)).getAll(); print("populated data."); List<List<?>> res = cache.query(new SqlFieldsQuery( "SELECT p.name, c.name FROM Person p INNER JOIN City c on c.id = p.city_id")).getall(); print("query results:"); for (Object next : res) System.out.println(">>> " + next); cache.query(new SqlFieldsQuery("drop table Person")).getAll(); cache.query(new SqlFieldsQuery("drop table City")).getAll(); print("dropped database objects."); finally // Distributed cache can be removed from cluster only by #destroycache() call. ignite.destroycache(dummy_cache_name); print("cache query DDL example finished."); /** * Prints message. * msg Message to print before all objects are printed. */ private static void print(string msg) System.out.println(); System.out.println(">>> " + msg);

15 4 典型场景开发 代码说明 从 example-cache.xml 配置文件中读取连接 IMDG 实例的配置信息, 连接到 IMDG 实例 使用 sql 语句创建 city person 两张表 往 city 表中插入 3 条数据,person 表中插入 4 条数据 联合 city 和 person 表进行查询 删除 city 和 person 表

16 5 常见问题 5 常见问题 5.1 如何开发一个应用 5.2 连接超时 5.1 如何开发一个应用 操作步骤 本节介绍使用 DCS IMDG Demo 包开发一个应用的完整过程, 包括下载实例代码, 修改典型场景代码, 配置认证参数, 运行示例工程以及编译示例工程 步骤 1 下载并解压 DCS IMDG Demo 示例工程代码到本地 PC 步骤 2 步骤 3 步骤 4 打开 Eclipse, 通过 File -> Import 菜单导入已存在的 Maven 工程, 选择解压后的 example 目录, 导入示例工程代码 参考典型场景开发, 将典型场景的示例代码写入 src/main/java/com/imdg/examples/ datagrid/myfirstexample 中 参考配置认证参数, 配置连接缓存实例的用户名 密码 实例连接地址等信息 步骤 5 鼠标右键单击 dcs.imdg.example 项目, 在弹出的上下文菜单中选择 Run As -> Maven build, 执行目标输入 clean package, 执行编译构建 说明 Maven 工程中使用到了 GridGain Enterprises 库, 实例代码库中添加了 GridGain 的 External Repository 到 Maven 配置文件, 编译前请确保网络是连通的 如果网络不通, 请先获取到 IMDG SDK 包, 将 IMDG SDK 包解压到本地 maven 仓库 例如本地 Maven 仓库地址为 D:\Repositories\Maven\repo, 则将解压后的 IMDG SDK 包中的 IMDG SDK 目录下的文件夹拷贝到 D:\Repositories\Maven\repo 中 步骤 6 将 dcs.imdg.example-1.0-snapshot.zip 拷贝到 Linux 弹性云服务器的任意目录下 说明 该 Linux 弹性云服务器必须与缓存实例属于同一个 VPC, 并配置相同的安全组, 以确保弹性云服务器与缓存实例的网络是连通的 步骤 7 将 dcs.imdg.example-1.0-snapshot.zip 压缩包解压到 demo 目录 unzip dcs.imdg.example-1.0-snapshot.zip -d demo

17 5 常见问题 步骤 8 运行示例脚本 cd demo bash bin/start_my_first_example.sh ---- 结束 5.2 连接超时 出现此类异常原因一般如下 : 实例连接地址错误 此时请检查实例连接地址是否正确 网络不通 此时请检查网络状况 弹性云服务器与缓存实例不在相同 VPC 内 此时可以通过建立 VPC 对等连接方式连通网络, 具体请参考缓存实例是否支持跨 VPC 访问? 弹性云服务器与缓存实例配置了不同的安全组 此时可以通过设置安全组规则连通网络, 具体请参考如何选择和配置安全组?

18 A 文档修订记录 A 文档修订记录 表 A-1 文档修订记录 发布日期 修订记录 第二次正式发布 第一次正式发布 调整文档的目录, 并对内容进行优化