开发准备

本章先介绍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

注意事项:

  1. 所有依赖的第三方jar包,均放在lib文件夹下。其中包括AbleCloud的服务框架ablecloud-framework-1.5.6.jarac-java-api-1.6.3.jar。根据SDK的发行状态,各jar包的版本号可能不同。

  2. 开发者开发的UDS服务需要编译成jar包,并置于lib文件夹下。另外,开发者自己所引用的第三方jar包,也需要一并置于lib文件夹下。

  3. 按上述目录结构将所有文件压缩、打包成一个ZIP文件(文件名可自取)。要求ZIP文件解压缩后能直接得到上述目录或文件,不能存在其它中间层次的目录。

  4. 在开发者管理控制台中提交压缩后的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选择正确的版本。

new project

选择maven工程。

info

注意JDK版本选择安装的1.7。点击next即可。

next

进入下一个页面,根据情况填写groupid/artifactid/version等信息。

info

填好后点击next,进入下一步,填写工程名以及存放路径。

name

然后点击finish完成新建工程向导。

finish

至此,新建工程完成。

2、 部署AbleCloud框架便于本机测试以及提交版本

新建package目录,将ablecloud-framework-1.4.0.zip解压到package目录下。

package子目录的结构为config/、lib/、start.sh文件等

3、 设置工程

设置编码方式,建议将字符编码设置为UTF-8或GBK

setting

fileencoding

按照步骤1完成了工程的新建,还需对工程属性进行一些设置以方便后续的编译、单测。 点击File -> Project Structure...

setting

首先设置工程所使用的JDK版本1.7和语言级别7.0。

lib

设置开发服务所要依赖的AbleCloud框架包:同上,打开Project Structure...,然后选择Libraries,点击右边的+号,选择Java,如下图所示。

lib

在弹出的对话框中选择下载并解压后的AbleCloud中的lib目录,并点击OK

lib

回到上一个窗口后再次点击OK确认。

lib

这个过程中,我们可以对添加的lib库重命名(可选),例如这里重命名为ablecloud-libs。点击OK完成添加。

lib

至此,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.shstart.cmd,即可在您的开发机上启动您编写好的服务程序。

注:服务启动所需的参数,如域名、版本、端口等信息均在xml的配置文件中设置。

9、 提交到平台

将AbleCloud的config目录、lib目录(含编译好的UDS服务jar包),以及start.sh文件等压缩、打包为一个zip文件,通过AbleCloud的Web管理控制台提交。

Eclipse

  1. 新建工程

    选择File-->New-->Project...

    new project

    选择maven工程。

    new project

    点击Next进入下一步。

    next

    填写groupId,artifactId,version等信息,并点击Finish完成新建工程。

    info

  2. 设置工程

    设置编码方式,建议将字符编码设置为UTF-8或GBK

    setting

    fileencoding

    在工程视窗右键点击步骤1中新建的工程进行工程设置。或者点击菜单栏Project-->Properties进行设置。

    setting

    首先设置工程对AbleCloud发行库的依赖。如图选择Java Build PathLibaries标签页,点击Add Library...

    setting

    Add Library页选择User Library

    setting

    继续点击User Libraries...按钮。

    setting

    然后点击New...新建一个用户library文件夹。

    setting

    这里可以给该用户lib重命名,如图中命名为ablecloud-libs,点击OK完成。

    setting

    回到User Libraries页面,点击右方的Add External JARs...按钮,选择下载并解压的AbleCloud发行库中的lib目录,将该目录中所有的jar文件添加到新建的user library中。

    setting

    勾选上新建的user library,并点击Finish将AbleCloud的jar文件添加到新建的工程中。

    setting

    下面进行java语言的设置,类似上面的设置,先进入Properties窗口,选择Java Compiler去掉默认的Use compliance from execution environment...,并且选择Compiler compliance level1.7

    setting

  3. 修改pom.xml文件

    intellij章节。

  4. 修改配置文件

    intellij章节。

  5. 编译单测

    TBD

  6. 本地运行

    intellij章节。

  7. 提交到平台

    intellij章节。