云平台编程与开发（二）：X5Cloud云平台SDK包概述

API的概括
  X5.database
2.1.1 X5.database.X5Persist类的描述    X5db为数据库支持，提供创建数据库、创建表、创建视图、创建存储过程等一些DDL的操作，以及对数据库表的增删查改操作。 X5.database包下，有X5Persist 、 X5dbprocSupport 、 X5DBResult 三个类。 2.1.1.1 X5.database.X5Persist类

该类用来做数据库的所有操作，X5提供两种方式(下面有具体说明)来得到该类的实例对象。X5Persist的方法介绍: 2.1.1.2 X5.database.X5DBResult类

该类为查询数据库得到的结果集,X5DBResult的方法介绍：

2.1.1.3 X5.database.X5dbprocSupport类

该类X5DB为支持存储过程的一个辅助类，执行前用于封装存储过程的参数定义，执行后用于封装存储过程的返回结果。 X5dbprocSupport的方法介绍：
  X5.file

2.2.1 X5.file类的描述    X5file为文件系统支持，提供文件夹和文件的创建、重命名、删除、读取和写入操作、X5.file包下，有X5File 、X5FileResult 两个类。 2.2.1.1 X5.file.X5File类

该类用来对文件的所有操作，X5提供两种方式(下面有具体说明)来得到该类的实例对象。X5File的方法介绍：

2.2.1.1X5.file.X5FileResult类

该类用来封装查看文件夹下的文件信息X5FileResult的方法介绍：

  X5.Exception

2.3.1 X5.Exception类的描述    X5EXception为公共的异常类，做本APIs中可能抛出的异常都可以通过该异常类处理。X5.exception包下，有X5EXception 一个类。 2.3.1.1 X5.exception.X5Exception类

该类为异常类，抛出该异常后通过异常码和异常信息以及异常的堆栈信息可以帮助我们更快的找出程序错误。

异常码说明：

400 用户账号异常，账号或者密码错误，或被禁用

500 socket通信错误，接收响应数据失败

501 socket通信错误，发送请求数据失败

502 socket通信错误，发送请求数据失败

503 socket通信错误，发送请求数据失败

600 socket通信错误，接收请求数据失败

601 socket通信错误，接收请求数据失败

602 socket通信错误，接收请求数据失败

700 无法连接数据库，可能数据库名错误或数据库类型指定错误

701 数据库重名了

702 工作单元批处理错误

703 工作单元事务回滚错误

704 查询数据库表错误

705 数据库的增删改错误或者DDL操作失败

706 创建数据库失败

707 执行存储过程失败

800 用户文件系统根路径无效

801 创建文件夹失败，可能该文件夹已经存在

802 新建文件失败，可能该文件已经存在

803 重命名文件失败，可能文件不存在，或者已经存在要重命名的文件

804 删除文件失败，可能文件不存在，或者文件夹不为空

805 查看文件失败，可能文件不存在，或者无法查看此文件

806 查看文件长度失败，可能文件不存在

807 读取文件失败，可能文件不存在或者指定了文件夹

808 写入文件失败，可能无法创建此文件

以上错误码说明仅供参考，详细信息可调用getMessage()方法查看。
X5_SDK用法举例
  X5DB对数据库的操作
首先实例化一个X5persist对象:
X5Persist X5 = new X5Persist();
(String userid,int dbtype,int dbname,String serverip);
参数：Userid由运营商提供
Dbtype为数据库类型，见相关约定
Dbtype为数据库名字，用户自取
Serverip由运营商提供
我们只需提供上述四个参数，构造一个X5Persist的实例，就可以做所有对数据库的操作了。实例中提供的方法，下面以例子的形式逐一介绍其用法。方法的具体定义，参考相应的JAVADOC即有详细说明。
第一步，我们来创建一个数据库1. public static void main(String[] args) {
2. String userid="1241234544445412"; //userid
3. int dbtype=2; //dbtype
4. String dbname="qishima"; //dbname
5. String serverip="service.x5cloud.com"; //serverip
6. //实例化，把标志身份的userid传过去
7. X5Persist x5=new X5Persist(userid,dbtype,dbname,serverip);
10. int count=-1;
11. try {
12. //调用方法，返回int值大于或等于零为创库成功
13. count=x5.createDB();
14. } catch (X5Exception e) {
15. e.printStackTrace();
16. System.out.println(e.getMessage());
17. }
18. if(count>=0){
19. System.out.println("创建数据库成功");
20. }
代码13行调用了x5persist.createDB()方法创建数据库。
第二步，我们在数据库中创建一张表1. public static void main(String[] args) {
2. //创建sqlserver表的sql语句
3. String sql="create table UserInfo123" +
4. "(user_id int not null," +
5. "user_name varchar(20) not null," +
6. "user_sex char(2) default('男')," +
7. "user_age int default(18)" +
8. ")";
9. String userid="1241234544445412"; //userid
10. int dbtype=2; //dbtype
11. String dbname="qishima"; //dbname
12. String serverip="service.x5cloud.com"; //serverip
13. //实例化，把标志身份的userid传过去
14. X5Persist x5=new X5Persist(userid,dbtype,dbname,serverip);
15. int count=-1;
16. try {
17. //调用方法，返回int值大于或等于零为创建表成功
18. count = x5.persist(sql);
19. } catch (X5Exception e) {
20. System.out.println(e.getMessage());
21. e.printStackTrace();
22. }
23. if(count>=0){
24. System.out.println("成功！受影响行数为："+count);
25. }
26. }
代码18行调用了x5persist的persist(String sql)方法，该方法可以做几乎除创库和查询外的所有数据库操作，该方法也有一个重载的方法persist(String sql,Object[] objs)，重载的方法支持了sql语句的参数列表。
第三步，我们在新建的数据库表中做增删改操作，这里我们通过一个工作单元来完成这三类动作。实际上我们也可以通过单独调用X5.persist (String sql) 方法，来分步做增删改。这里X5.X5job()方法为一个job单元，我们可以通过设置istransaction的值（0为false，1为true）来做事务支持。1. public static void main(String[] args) {
2. String str1="insert into UserInfo123 values('张三',default,default)";
3. String str2="insert into UserInfo123 values('李四','女',20)";
4. String str3="update UserInfo123 set user_name='王五',user_age=30 where user_name='张三'";
5. String str4="delete from UserInfo123 where user_name='李四'";
6. List<String> sql=new ArrayList<String>();
7. sql.add(str1);
8. sql.add(str2);
9. sql.add(str3);
10. sql.add(str4);
11. int istransaction=1;
12. String userid="1241234544445412"; //userid
13. int dbtype=2; //dbtype
14. String dbname="qishima"; //dbname
15. String serverip="service.x5cloud.com"; //serverip
16. //实例化，把标志身份的userid传过去 17. X5Persist x5=new X5Persist(userid,dbtype,dbname,serverip);
18. boolean flag=false;
19. try {
20. //调用方法，返回boolean值标识是否执行成功
21. flag = x5.x5job(sql,istransaction);
22. } catch (X5Exception e) {
23. System.out.println(e.getMessage());
24. e.printStackTrace();
25. }
26. if(flag){
27. System.out.println("成功!");
28. }
29. }
代码2至10行，把要执行的增删改sql语句放入一个list集合中，代码21行调用方法x5job(List<String> sql)，第二个参数可以标识是否为这个job工程添加事务支持，可以缺省，缺省时为不添加事务。
第四步，我们来个简单查询表，数据调用select()方法后，返回的是一个X5DBResult对象，从该对象中取数据同JDBC中的ResultSet，略有不同，详见对X5DBResult类的介绍。1. public static void main(String[] args) {
2. String sql="select * from UserInfo where user_id<?";
3. Object []objs=new Object[]{1000};
4. String userid="1241234544445412"; //userid
5. int dbtype=2; //dbtype
6. String dbname="qishima"; //dbname
7. String serverip="service.x5cloud.com"; //serverip
8. //实例化，把标志身份的userid传过去
9. X5Persist x5=new X5Persist(userid,dbtype,dbname,serverip);
10. try {
11. X5DBResult set=x5.select(sql,objs);
12. List<Object> columns=set.getColumns();
13. for(Object obj:columns){
14. System.out.print(obj.toString()+" ");
15. }
16. System.out.println("");
17. while(set.hasNext()){
18. System.out.println(set.getObject("user_id")+""+set.getObject("user_name")+""+set.getObject(3)+""+set.getObject(4));
19. }
20. } catch (X5Exception e) {
21. e.printStackTrace();
22. }
23. }
本例子是做一个简单的条件查询，见代码2至3行。代码11行调用了select(String sql,Object[] objs)方法，返回一个X5DBResult的实例对象，该实例对象封装着查询结果，代码12至19是访问的查询结果。
代码12行调用getColmns()方法，得到结果集的表头信息，13至15采用for循环遍历打印表头的列名。
代码17至19为取数据，先是hasNext()判断结果集中是否有下一行数据。
代码18行中，通过getObject(String columnName)或者getObject(int columnsIndex)来取出当前指针指向的一行记录中的值。注意columnName必须和数据库字段名一致，需要严格注意大小写。
这样我们就从查询返回的结果集中取出了我们想要的数据，是不是跟JDBC中的ResultSet极为相似呢？还有一些getSize()获得结果集大小等方法，可以参见javadoc
第五步，我们来尝试执行一个存储过程。为了说明问题，我们选择执行一个带IN参，OUT参和查询结果集的存储过程，这一步我们需要借助一个辅助类X5dbprocSupport，用法同JDBC的CallableStatement，略有不同，详见X5dbprocSupport类的介绍1. public static void main(String[] args) {
2. String userid="1241234544445412"; //userid
3. int dbtype=2; //dbtype
4. String dbname="qishima"; //dbname
5. String serverip="service.x5cloud.com"; //serverip
6. //实例化，把标志身份的userid传过去
7. X5Persist x5=new X5Persist(userid,dbtype,dbname,serverip);
8. //实例化一个执行存储过程的辅助类对象
9. String sql="{call testa(?,?,?,?)}";
10. X5dbprocSupport x5dbproc=new X5dbprocSupport(sql);
11. //IN参数和OUT参数
12. x5dbproc.setString(2, "女");
13. x5dbproc.registerOutParameter(4, Types.VARCHAR);
14. x5dbproc.setInt(3, 100);
15. x5dbproc.setString(1, "测试测试测试");
16. //调用方法，返回一个辅助类对象，用于访问结果
17. try {
18. X5dbprocSupport x5dbprocresult=x5.callProc(x5dbproc);
19. //调用getMoreUpdateCount()方法，判断是否还有更新计数
20. if(x5dbprocresult.getMoreUpdateCount()){
21. System.out.println(x5dbprocresult.getUpdateCount());
22. }
23. //调用getX5DBResult()方法，获得一个结果集
24. x5.database.X5DBResult x5result=x5dbprocresult.getX5DBResult();
25. //遍历取值
26. while(x5result!=null&&x5result.hasNext()){
27. System.out.println(x5result.getObject("user_name")+" "+x5result.getObject(1));
28. }
29. //调用get方法，获得OUT参数的值
30. System.out.println(x5dbprocresult.getString(4));
31. //调用getX5DBResult()方法，获得下一个结果集
32. x5.database.X5DBResult x5result2=x5dbprocresult.getX5DBResult();
33. //遍历取值
34. while(x5result2!=null&&x5result2.hasNext()){
35. System.out.println(x5result2.getObject("user_name")+" "+x5result2.getObject(1)+" "+x5result2.getObject(4));
36. }
37. } catch (X5Exception e) {
38. e.printStackTrace();
39. }
40. }
代码8至15行实例化了一个辅助类对象x5dbprocSupport，其中11至15行为设置参数，setObject(int index,Object obj)为输入参数赋值，代码13行registerOutParameter(4, Types.VARCHAR)为输出参数指定类型，这里的Types.VARCHAR与JDBC中一致，如果是oracle的结果集可以用OracleTypes.CURSOR或者直接用-10。代码18行调用callProc(X5dbprocSupport x5dbproc)方法执行存储过程，并返回了一个辅助类对象，这里我们不用关心该返回的辅助类和执行前的辅助类对象是否为同一个，值得注意的是我们怎样从返回的辅助类对象中取出我们想要的结果。在这个返回的辅助类实例对象中，保存着执行存储过程的所有结果，包括更新计数信息，结果集，输出参数。下面我们看怎样来取出我们想要的数据：代码18至22行，调用getMoreUpdateCount()方法返回boolean值判断是否有更新计数，调用getUpdateCount()方法取出更新计数，注意每取一次，标识更新计数的指针会向下移动一次，故每个更新计数只能取一次。要重复取值可以通过setCountIndex()来设置指针的位置。代码23至28行，31至36行，调用getX5DBResult()方法取出当前指针标志的结果集对象，我们也可以先调用getMoreX5DBResult()方法来判断是否有结果集。注意每取一次，指针也会向下移动一次，故每个结果集只能取一次。要重复取值可以通过setSetIndex()来设置指针的位置，标识结果集的指针和标识更新计数的指针是没有关系的，彼此没有影响。代码29，30行是取出输出参数的值，getString(int paramIndex)方法的参数为存储过程的参数列表序号。事实上我们可以通过getObject(int paramIndex)，getInt(int paramIndex)，getLong(int paramIndex)等等方法取出我们需要的类型的输出参数，但是参数不能给错，否则会返回每个指定类型的缺省值，如getString()会放回null。例子中将取得各种结果数据的顺序打乱，是为了说明存储过程执行后返回的结果已经完全保存在辅助类对象中，可以根据编程需求随意取值，值得注意的是这一点与JDBC中是不同的。
  X5File 对文件系统的操作
首先实例化一个X5File对象：X5Persist X5 = new X5Persist() X5.setServer
("service.x5cloud.com "); X5.setUserid ("1241234544445412");
或者是X5File X5 = new X5File (String userid, String serverip);
参数：Userid由运营商提供 Serverip由运营商提供
我们只需提供上述两个参数，构造一个X5File的实例，就可以做所有对文件
系统的操作了。实例中提供的方法，下面以例子的形式逐一介绍其用法。方法的具体定义，参考相应的JAVADOC即有详细说明。
第一步，我们创建文件夹，创建文件，重命名文件，删除文件String filepath，这就是我们要操作的文件路径，注意以“/”开头。各种操作的方法调用同JAVA中的File类，略有不同，可见X5File类的说明。首先我们得到一个X5File类的实例对象
1. 实例化，把标志身份的userid传过去
2. X5File x5 = new X5File();
3. x5.setServer("service.x5cloud.com");
4. x5.setUserid("1241234544445412");
5. //创建文件夹
6. public static boolean mkdirs(X5File x5) {
7. String filepath = "/测试/demo/demo1/demo2/demo3";
8. try {
9. return x5.mkdirs(filepath);
10. } catch (X5Exception e) {
11. e.printStackTrace();
12. }
13. return false;
14. }15. //创建文件
16. public static boolean createNewFile(X5File x5) {
17. String filepath = "/测试/demo/demo1/demo2/demo3/demo4/demo.txt";
18. try {
19. return x5.createNewFile(filepath);
20. } catch (X5Exception e) {
21. e.printStackTrace();
22. }
23. return false;
24. }
25. //重命名
26. public static boolean rename(X5File x5) {
27. String filepath = "/测试/demo/demo1/demo2/demo3/demo4/demo.txt";
28. String tofilepath = "/测试/demo/demo1/demo2/demo3/demo4/demo1234.doc";
29. try {
30. return x5.rename(filepath, tofilepath);
31. } catch (X5Exception e) {
32. e.printStackTrace();
33. }
34. return false;
35. }36. //删除 37. public static boolean delete(X5File x5) {
38. String filepath = "/测试/demo/demo1/demo2/demo3/demo4/demo1234.doc";
39. try {
40. return x5.delete(filepath);
41. } catch (X5Exception e) {
42. e.printStackTrace();
43. }
44. return false;
45. }注意不能创建重名的文件夹或者文件，不能删除包含子文件的父文件夹。
第二步，我们做文件的读写X5File对文件的读写都是基于byte数组的，因此关于编码的问题，在调用该方法前后可自行设置。1. //读取文件
2. public static byte[] read(X5File x5) {
3. String filepath = "/测试/demo/demo1/demo2/demo3/demo1234.doc";
4. try {
5. return x5.read(filepath);
6. } catch (X5Exception e) {
7. e.printStackTrace();
8. return null;
9. }
10. }
指定文件路径，调用read(String filePath)方法可以将文件数据读取出来保存在一个byte[]中。事实上read(String filePath)方法还有两个重载的方法，用来支持按指定的偏移量读取文件和设置读取的长度，缺省为头读起且读取全部，详见javadoc说明。
//写入文件
1. public static boolean write(X5File x5) {
2. String str = "D:/我的文档/学习文档/QQ_api.doc";//本地文件
3. String filepath = "/测试/demo/demo1/demo2/demo3/demo1234.doc";//要写入的远端文件
4. //读取本地文件，得到byte[]
5. File file = new File(str);
6. try {
7. FileInputStream fis = new FileInputStream(file);
8. byte[] b = new byte[(int) file.length()];
9. fis.read(b);
10. fis.close();
11. //调用写入的方法
12. return x5.write(filepath, b);
13. } catch (FileNotFoundException e) {
14. e.printStackTrace();
15. return false;
16. } catch (IOException e) {
17. e.printStackTrace();
18. return false;
19. } catch (X5Exception e) {
20. e.printStackTrace();
21. return false;
22. }
23. }
代码2行是一个本地文件的路径，代码4至10行从本地文件中读取数据到一个byte[]中。
代码3行是要写入的文件路径，代码12行调用write(String filePath,byte[] b)方法将本地文件数据写入到指定的文件。返回一个boolean判断是否成功写入。
事实上该方法还有一个write(String filePath,long off,byte[] b)的重载方法，支持从指定的位置开始写入，缺省为追加到最后，详见javadoc。
第三步，我们做文件夹的目录化查看X5File对文件夹的目录化查看包含两种，一种是查看指定文件夹下面的文件，文件夹的名字，另一种是查看指定文件夹下面的文件，文件夹的所有信息，包括文件名，文件类型，文件大小，文件最后修改时间。如果指定的路径为一个文件，即为查看文件的文件名或者文件的所有信息。1. public static void doDirFiles(X5File x5){
2. String filepath = "/demo000/测试0/测试1/测试2/测试3/测试4";
3. System.out.println("文件目录：");
4. try {
5. X5FileResult rs=x5.dirFiles(filepath);
6. while(rs.hasNext()){
7. System.out.println(rs.getName()+" "+rs.getFileType()+" "+rs.getLength()+" "+new SimpleDateFormat("yyyy-MM-dd hh:mm:ss").format(new Date(rs.getLastModify())) );
8. }
9. } catch (X5Exception e) {
10. e.printStackTrace();
11. }
12. }
代码2行指定要查看的文件夹路径
代码5行调用dirFiles(String filePath)方法，返回一个X5FileResult类的实例对象。
代码6至8行循环遍历查询的结果集，这个类似于数据库查询的结果集。
关键代码为7行，我们可以调用getName(),getFileType(),getLength(),getLastModify()方法来分别获得当前结果行的文件名，文件类型，文件大小以及文件的最后修改时间。