开发准备
本章先介绍UDS(User Defined Service)在AbleCloud平台上的发布要求,然后以官网上发布的DemoService为基础,介绍如何在本地运行UDS服务,以及如何开发自己的UDS服务。
UDS发布说明
在AbleCloud管理控制台中,设备通过长连接上报数据可以由对应产品指定转发的UDS来处理。 其它业务请求(包括设备或其它客户端发起的)也可以由请求发起方选择由指定UDS来处理。
开发者可通过AbleCloud开发者管理控制台提交、运行UDS。提交和运行UDS时,要求压缩包其目录结构与AbleCloud发布的Java版本服务开发框架一致,如下所示。
/config
/cloudservice-conf.xml
/lib
/ablecloud-framework-1.5.6.jar
/ac-java-api-1.6.3.jar
/commons-collections-3.2.1.jar
/commons-configuration-1.10.jar
/commons-lang-2.6.jar
/slf4j-api-1.7.7.jar
/...
start.sh
start.cmd
注意事项:
所有依赖的第三方jar包,均放在lib文件夹下。其中包括AbleCloud的服务框架
ablecloud-framework-1.5.6.jar
和ac-java-api-1.6.3.jar
。根据SDK的发行状态,各jar包的版本号可能不同。开发者开发的UDS服务需要编译成jar包,并置于lib文件夹下。另外,开发者自己所引用的第三方jar包,也需要一并置于lib文件夹下。
按上述目录结构将所有文件压缩、打包成一个ZIP文件(文件名可自取)。要求ZIP文件解压缩后能直接得到上述目录或文件,不能存在其它中间层次的目录。
在开发者管理控制台中提交压缩后的ZIP文件,之后即可通过“上线”/“下线”功能管理UDS的运行状态。
本机运行UDS
本机运行UDS要求已安装Java的运行时环境JRE(推荐1.7或更新版本)。
1、首先,从AbleCloud官网下载栏目下载DemoService.zip,解压后进入package目录,修改config文件夹下的cloudservice-conf.xml文件。
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<developer>
<!-- 对应“管理控制台->开发者ID” -->
<id>4</id>
</developer>
<authentication>
<!-- 对应“服务管理->开发密钥”,选择已启用的任意一对。 -->
<access-key>33df24a54054067e80af49d939b429c2</access-key>
<secret-key>5e2fec3440e23c5e807910b13b672015</secret-key>
</authentication>
<service>
<!-- 对应“产品管理->产品列表->主域名” -->
<major-domain>ablecloud</major-domain>
<!-- 对应“产品管理->产品列表->子域” -->
<sub-domain>demo</sub-domain>
</service>
</configuration>
注:开发者ID,access-key,secret-key等信息,均能登录AbleCloud网站(开发者管理控制台)获取。其它项不需要修改。
2、启动终端,进入package目录下,接下来就可以在本地启动服务并进行测试。
linux下在终端运行如下命令启动服务:
sh start.sh
windows下在cmd中运行如下命令启动服务:
start.cmd
本地启动成功后,可使用curl命令进行开灯测试。
linux下使用curl命令:
curl -v -X POST -H "Content-Type:application/x-zc-object" -H "X-Zc-Major-Domain:ablecloud" -H "X-Zc-Sub-Domain:test" -H "X-Zc-User-Id:1" -d "{\"action\":\"I'm test\"}" 'http://localHost:8080/test'
windows下使用curl命令请求:
curl -v -X POST -H "Content-Type:application/x-zc-object" -H "X-Zc-Major-Domain:ablecloud" -H "X-Zc-Sub-Domain:test" -H "X-Zc-User-Id:1" --data-ascii "{\"action\":\"I'm test\"}" "http://localHost:8080/test"
注:
X-Zc-Major-Domain
是开发者帐号的主域的名字;X-Zc-Sub-Domain
是要访问的服务所关联的子域的名字;X-Zc-User-Id
是用户的ID。
开始自己的UDS程序
系统准备
在进行开发前,需要对系统以及环境进行设置。目前框架只支持java语言,因此系统准备基本都是和java相关,如JDK、maven等。
-
JDK
安装JDK,建议采用1.7版本JDK。
-
maven
安装maven,建议采用3.2以上版本。
-
AbleCloud SDK
点此进入下载页 获取AbleCloud云端服务SDK
新建maven工程
熟悉上述流程之后,可以开始开发自己的UDS程序。以下从开始逐步介绍开发步骤。
Intellij
1、 新建工程
选择新建maven工程,JDK选择正确的版本。
选择maven工程。
注意JDK版本选择安装的1.7。点击next即可。
进入下一个页面,根据情况填写groupid/artifactid/version等信息。
填好后点击next,进入下一步,填写工程名以及存放路径。
然后点击finish完成新建工程向导。
至此,新建工程完成。
2、 部署AbleCloud框架便于本机测试以及提交版本
新建package目录,将ablecloud-framework-1.4.0.zip解压到package目录下。
package子目录的结构为config/、lib/、start.sh文件等
3、 设置工程
设置编码方式,建议将字符编码设置为UTF-8或GBK
按照步骤1完成了工程的新建,还需对工程属性进行一些设置以方便后续的编译、单测。 点击File -> Project Structure...
首先设置工程所使用的JDK版本1.7和语言级别7.0。
设置开发服务所要依赖的AbleCloud框架包:同上,打开Project Structure...,然后选择Libraries,点击右边的+号,选择Java,如下图所示。
在弹出的对话框中选择下载并解压后的AbleCloud中的lib目录,并点击OK。
回到上一个窗口后再次点击OK确认。
这个过程中,我们可以对添加的lib库重命名(可选),例如这里重命名为ablecloud-libs。点击OK完成添加。
至此,UDS开发所依赖的AbleCloud开发框架库添加成功。
4、 修改pom.xml文件
下面是一个示例服务的完整pom.xml文件:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.ablecloud.demo</groupId>
<artifactId>DemoService</artifactId>
<version>1.2.0</version>
<properties>
<ablecloud.lib.dir>./package/lib</ablecloud.lib.dir>
</properties>
<build>
<plugins>
<plugin>
<!--this plugin and dependency jars are used for testing-->
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.18.1</version>
<dependencies>
<dependency>
<groupId>org.apache.maven.surefire</groupId>
<artifactId>surefire-junit47</artifactId>
<version>2.18.1</version>
</dependency>
</dependencies>
<configuration>
<additionalClasspathElements>
<additionalClasspathElement>${ablecloud.lib.dir}/ablecloud-framework-1.5.6.jar</additionalClasspathElement>
<additionalClasspathElement>${ablecloud.lib.dir}/ac-java-api-1.6.3.jar</additionalClasspathElement>
<additionalClasspathElement>${ablecloud.lib.dir}/slf4j-log4j12-1.7.7.jar</additionalClasspathElement>
<additionalClasspathElement>${ablecloud.lib.dir}/slf4j-api-1.7.7.jar</additionalClasspathElement>
<additionalClasspathElement>${ablecloud.lib.dir}/log4j-1.2.17.jar</additionalClasspathElement>
<additionalClasspathElement>${ablecloud.lib.dir}/junit-4.11.jar</additionalClasspathElement>
<additionalClasspathElement>${ablecloud.lib.dir}/hamcrest-core-1.3.jar</additionalClasspathElement>
<additionalClasspathElement>${ablecloud.lib.dir}/commons-configuration-1.10.jar</additionalClasspathElement>
<additionalClasspathElement>${ablecloud.lib.dir}/commons-collections-3.2.1.jar</additionalClasspathElement>
<additionalClasspathElement>${ablecloud.lib.dir}/commons-lang-2.6.jar</additionalClasspathElement>
<additionalClasspathElement>${ablecloud.lib.dir}/commons-logging-1.1.1.jar</additionalClasspathElement>
<additionalClasspathElement>${ablecloud.lib.dir}/jetty-all-9.1.5.v20140505.jar</additionalClasspathElement>
<additionalClasspathElement>${ablecloud.lib.dir}/jackson-core-2.3.2.jar</additionalClasspathElement>
<additionalClasspathElement>${ablecloud.lib.dir}/jackson-annotations-2.3.2.jar</additionalClasspathElement>
<additionalClasspathElement>${ablecloud.lib.dir}/jackson-databind-2.3.2.jar</additionalClasspathElement>
<additionalClasspathElement>${ablecloud.lib.dir}/javax.servlet-api-3.1.0.jar</additionalClasspathElement>
<additionalClasspathElement>${ablecloud.lib.dir}/javax.websocket-api-1.0.jar</additionalClasspathElement>
<additionalClasspathElement>${ablecloud.lib.dir}/gson-2.3.1.jar</additionalClasspathElement>
<additionalClasspathElement>${ablecloud.lib.dir}/okhttp-2.7.1.jar</additionalClasspathElement>
<additionalClasspathElement>${ablecloud.lib.dir}/okio-1.6.0.jar</additionalClasspathElement>
<additionalClasspathElement>${ablecloud.lib.dir}/qiniu-java-sdk-7.0.10.jar</additionalClasspathElement>
</additionalClasspathElements>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>1.7</source>
<target>1.7</target>
<encoding>UTF-8</encoding>
<compilerArguments>
<extdirs>${ablecloud.lib.dir}</extdirs>
</compilerArguments>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
<configuration>
<outputDirectory>${ablecloud.lib.dir}</outputDirectory>
</configuration>
</plugin>
</plugins>
</build>
</project>
完整拷贝该示例pom.xml文件内容,其中绝大部分内容都无须修改,开发者仅需修改如下几个配置项即可:
<project>
<groupId>your service group id</groupId>
<artifactId>your service artifact id</artifactId>
<version>your service version</version>
</project>
5、 修改配置文件
配置文件位于AbleCloud发行库的config文件夹下,名字为cloudservice-conf.xml
。
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<developer>
<!-- 对应“个人信息->个人信息->开发者ID” -->
<id>4</id>
</developer>
<authentication>
<!-- 对应“密钥对管理->全部密钥对”,选择已启用的任意一对即可。 -->
<access-key>33df24a54054067e80af49d939b429c2</access-key>
<secret-key>5e2fec3440e23c5e807910b13b672015</secret-key>
<timeout>5000</timeout>
</authentication>
<framework>
<!-- 此处为开发环境配置,默认为测试环境,仅本地测试时生效-->
<router>test.ablecloud.cn:5000</router>
</framework>
<service>
<!-- 此处为继承ACService的类的相对路径,即UDS的唯一入口 -->
<class>com.ablecloud.demo.DemoService</class>
<!-- 此处为本机启动的端口号 -->
<port>1234</port>
<!-- 对应“产品管理->产品列表->主域名” -->
<major-domain>ac</major-domain>
<!-- 对应“产品管理->产品列表->子域” -->
<sub-domain>test</sub-domain>
</service>
<!-- Options-->
<client>
<!-- UDS所有访问云端接口的超时时间 -->
<timeout>5000</timeout>
<!-- UDS所有访问云端接口的重试次数 -->
<retry-count>1</retry-count>
</client>
</configuration>
注:开发者ID,access-key,secret-key等信息,均能登录AbleCloud网站(开发者管理控制台)获取。
至此,即完成了新建一个工程所需的所有准备工作以及环境配置,接下来可以开始UDS的业务逻辑开发。
6、 新建Class并继承ACService
参照DemoService或者API文档里关于ACSevice的介绍。
7、 编译单测
在IDE的终端(terminal)或系统终端中运行命令mvn package
即可完整的执行编译、单元测试(如果写了单测代码的话),这种方式要求已安装maven环境并配置系统环境变量。另外也可以通过安装MAVEN HELPER
的Intellij插件进行编译。
8、 本地运行
如果编译、单测都没有问题,则将编译出来的服务jar包(在服务工程主目录下的target/lib目录下)拷贝到AbleCloud框架的lib目录下。之后,在AbleCloud的框架主目录执行AbleCloud提供的脚本sh start.sh
或start.cmd
,即可在您的开发机上启动您编写好的服务程序。
注:服务启动所需的参数,如域名、版本、端口等信息均在xml的配置文件中设置。
9、 提交到平台
将AbleCloud的config目录、lib目录(含编译好的UDS服务jar包),以及start.sh文件等压缩、打包为一个zip文件,通过AbleCloud的Web管理控制台提交。
Eclipse
-
新建工程
选择File-->New-->Project...。
选择maven工程。
点击Next进入下一步。
填写groupId,artifactId,version等信息,并点击Finish完成新建工程。
-
设置工程
设置编码方式,建议将字符编码设置为UTF-8或GBK
在工程视窗右键点击步骤1中新建的工程进行工程设置。或者点击菜单栏Project-->Properties进行设置。
首先设置工程对AbleCloud发行库的依赖。如图选择Java Build Path的Libaries标签页,点击Add Library...。
在Add Library页选择User Library。
继续点击User Libraries...按钮。
然后点击New...新建一个用户library文件夹。
这里可以给该用户lib重命名,如图中命名为ablecloud-libs,点击OK完成。
回到User Libraries页面,点击右方的Add External JARs...按钮,选择下载并解压的AbleCloud发行库中的lib目录,将该目录中所有的jar文件添加到新建的user library中。
勾选上新建的user library,并点击Finish将AbleCloud的jar文件添加到新建的工程中。
下面进行java语言的设置,类似上面的设置,先进入Properties窗口,选择Java Compiler,去掉默认的Use compliance from execution environment...,并且选择Compiler compliance level为1.7。
-
修改pom.xml文件
同intellij章节。
-
修改配置文件
同intellij章节。
-
编译单测
TBD
-
本地运行
同intellij章节。
-
提交到平台
同intellij章节。