金蝶EAS-V8.1-WebService开发指南.doc

Webservice开发指南
版权声明
本书著作权属于金蝶软件(中国)有限公司所有，在未经本公司许可的情况下，任何单位或个人不得以任何方式对本书的部分或全部内容擅自进行增删，改编，节录，翻译，翻印，改写。

金蝶软件（中国）有限公司
2015年8月
BOSWebService
1.1. BOSWebService原理 2
1.2. 发布WebService的约束 3
1.3. BOSWebService发布 3
1.3.1. 发布流程 3
1.3.2. 发布WebService 3
1.3.3. 编辑WebService配置文件 4
1.4. BOSWebService部署 5
1.4.1. 建立web工程 5
1.4.2. 部署发布文件 5
1.4.3. 测试是否正确 6
1.4.4. Web工程目录及文件截图 6
1.5. 客户端代码 6
1.5.1. 获取wsdl服务描述文件 6
1.5.2. 下载工具 7
1.5.3. 建立一个新工程 7
1.5.4. 使用java客户端 11
1.5.5. importVoucher（凭证引入 12
1.6. BOS webservice 安全性 13
1.6.1. BOS webservice 安全性概述 13
1.6.2. 不启用安全性 13
1.6.3. 启用安全性 13
1.6.4. 如何安全性启用 14
1.7. EASLogin 登陆webservice 说明 14
1.7.1. EASLogin 接口说明 14
1.7.2. EASLogin 异常说明 15
1.7.3. EASLogin 和前面版本的差别 16
1.8. webservice 异常查看 16
2. WebService 客户端开发指南 17
2.1. 前提条件 17
2.2. 获取WSDL文件 17
2.3. 生成客户端 18
2.3.1. 生成Java客户端 18
2.3.2. 建立一个新工程 18
2.3.3. 将获取到的WSDL文件拷贝到工程的根目录下： 19
2.3.4. 生成客户端 19
2.4. 使用java客户端 23
2.5. 生成C# 客户端 23
2.5.1. 使用命令行 23
2.5.2. 运行命令生成客户端 24
2.5.3. 使用客户端代码 25
3. webservice FAQ 27
3.1. 在EAS 上如何发布一个webservice ? 27
3.2. 如何调用一个 webservice？ 27
3.3. 有哪些工具能够简单的测试 webservice？ 27
3.4. EASLogin 服务登陆如何判断失败 27
3.5. 调用webservice时报 com.kingdee.bos.IllegalSessionStateException: Please login first 异常？ 27
3.6. EAS6.0调用webservice时报没有 WSConfig.getSrvURL() 方法。 28
3.7. 调用webservice时报.SocketTimeoutException: Read timed out 异常 28

BOSWebService
1.1. BOSWebService原理
Webservice 主要由SOAP，WSDL, 以及UDDI 等几块技术组成，以XML格式进行数据的传输。是建立可互操作的分布式应用程序的新平台
Webservice的一个最基本的目的就是提供在各个不同平台的不同应用系统的协同工作能力。使各个异构系统之间实现无缝交互。在本质上是要为应用程序之间提供数据通讯的标准，为企业应用之间动态地提供大颗粒度的服务，并不适合于非常精细的基于会话的方法调
用以及复杂的事务（transaction）处理之中。
1.2. 发布WebService的约束
在BOS Studio中发布webService时，只能发布Entity和Façade两种元数据类型成WebService服务端的代码。
由于Entity或Façade函数参数和返回值可能包含很多复杂的业务类型，在发布时会生成许多辅助类，一些复杂类型在其他异构系统中生成webService客户端时不能很好的
支持，因此建议在建立webService功能时，最好使用Façade，并且提供简单类型的输入和返回参数。

1.3. BOSWebService发布
1.3.1. 发布流程

先建立需要发布的Façade,建立粗粒度的业务方法，业务方法尽可能提供简单数据类型的数据参数和返回参数。

1.3.2. 发布WebService
运行BOS Studio，打开“包分类”视图，在其中选中要发布WebService的实体或Façade对象（可同时选中多个），点击鼠标右键，在弹出菜单中选择“发布WebService”,将弹出“发布WebService”向导：

选择实体或Façade对象下要发布的方法，手工输入或者点击“浏览”按钮来指定发布生成代码存放的目录，可以同时勾中“追加到配置文件”。这样BOS Studio将会根据选中的对象和要发布的方法生成WebService代码和wsdl描述

1.3.3. 编辑WebService配置文件

在“包分类”视图中，选择要编辑其配置文件的解决方案，点击工具栏上的“编辑WebService 配置文件”按钮，将会弹出配置文件编辑向导

在其间，可以增加或删除要发布的对象（方法），选择好要发布的对象（方法）后，点击“完成”按钮，即可完成对配置文件的编辑。配置文件位于解决方案的根目录下。

1.4. BOSWebService部署

1.4.1. 部署发布文件
发布成功以后，在临时目录里会生成一个wsdd文件和一个目录，例如：
D:\webtest\AcctCussentCheckFacade.wsdd
D:\webtest\com\kingdee\eas\fi\gl\app\webservice\WSAcctCussentCheckFacadeSrvProxy.java

WSAcctCussentCheckFacadeSrvProxy.java文件拷贝到解决方案src目录中，注意包名和路径一致；

AcctCussentCheckFacade.wsdd处理方法如下：
找到解决方案的runtime\server\deploy\eas.ear目录，用解压缩软件打开web.war，进入WEB-INF目录
把AcctCussentCheckFacade.wsdd添加进去；
把AcctCussentCheckFacade.wsdd文件里的service节点内容添加到server-config.wsdd文件。操作方法建议：提取server-config.wsdd文件到临时目录，用编辑工具打开，再打开AcctCussentCheckFacade.wsdd，拷贝service节点内容粘贴到server-config.wsdd文件，注意XML格式一致；保存server-config.wsdd文件并拷回到web.war压缩包里。

1.4.2. 测试是否正确

上面的步骤操作完成后，快测已经可以看到新建的WebService。通过浏览器输入服务的地址，访问服务是否正确
如输入：http://server-ip:port/ormrpc/services
BOS快测启动的默认端口为56898
1.4.3. 部署到正式服务器
1、在BIM中部署代码和元数据；
2、把解决方案下改好的runtime\server\deploy\eas.ear\web.war文件拷贝到EAS服务器的server\deploy\eas.ear目录中，
3.将生成的Web Service的java代码编译为class,放在EAS服务器的eas\server\deploy\eas.ear\web.war\WEB-INF\class下，把发布的wsdd文件中服务部分拷贝到server-config.wsdd中。
4.重启 EAS服务器

1.4.4. Web工程目录及文件截图

1.5. 客户端代码
1.5.1. 获取wsdl服务描述文件
WebService已经成功部署到应用服务器上（本文以Apusic为例进行说明），客户端可以通过浏览器访问到已部署的WebService。

要构建相关的客户端，就要获取已经部署的WebService的相应的WSDL文件，用鼠标右键点击蓝色的部分“(wsdl)”，选取“目标另存为”菜单，这时将出现选择保存文件位置的对话框，在文件名处将文件的后缀名由xml改为wsdl，将wsdl文件保存至本地。

1.5.2. 下载工具
通过www.eclipse.org下载eclipse（下载j2ee版本）或通过命令行来生成
java -Djava.ext.dirs=lib org.apache.axis.wsdl.WSDL2Java
其中lib是axis包目录生成客户端代码。
1.5.3. 建立一个新工程
例如建立一个工程名为GenerateWSClient的Java工程：

将获取到的WSDL文件拷贝到工程的根目录下

用鼠标右键点击要生成客户端的WSDL文件，选取菜单“Web Services”-“Generate Client”

将会弹出生成客户端向导

如图，使用默认值，点击“Next >”，进入下一步：

依然使用默认值，点击“Next >”，进入下一步：

依然使用默认值，点击“Finish”，即可生成相应的客户端工程（是一个Web工程）

1.5.4. 使用java客户端

新生成的工程中有一个JavaSource目录，我们要使用的java代码就位于这个目录，例如上图中的WSLoginProxy.java。以下是一个使用Java客户端的例子：
import java.rmi.RemoteException;
import com.kingdee.WSLoginProxy;//此为发布的代码
import com.client.WSContext;

public class LoginTest {
public static void main(String[] args) {
try {
WSLoginProxy proxy = new WSLoginProxy();
/**
* web service客户端登陆
* userName 用户名
* password 密码
* slnName eas
* dcName 数据中心,对应的是dataCenter中数据中心id
* language 语言 L2简体
* dbType 数据库类型 0:sqlServer 1:db2 2:oracle
* authPattern 验证方式 默认 "BaseDB" ; 其他认证方式KEY可从easAuthPatterns.xml中获取
*/
WSContext ctx = proxy.login("用户", "", "eas", "数据中心id", "L2", 0);
//成功登录后打印sessionId
System.out.println(ctx.getSessionId());
//调用凭证业务webservice方法importVoucher（凭证引入），请看1.55节

}
catch (RemoteException e) {
e.printStackTrace();
}
}
}

1.5.5. importVoucher（凭证引入
1、 凭证引入接口，两个接口方法都可用，且用法一致

2、 凭证 webService 接口生成客户端，可参考 EASLogin 方法
3、 凭证引入参数：importVoucher(wsvoucher[], int isVerify, int isCashflow)
l 传参数第1个：WSWSVoucher[] 普通对象数组，见构造EAS凭证字段以及含义说明
l 传参数第2个：isverify
0 不核销，暂存
1 核销，暂存
2 不核销，提交
3 核销，提交
l 传参数第3个：isImpCashflow
是否引入现金流量 0 不引入 1 引入
4、 凭证引入代码调用说明

5、 返回值String[][]
是一个长度为凭证数，宽度是5的字符串数据
宽度的定义：外部系统凭证号，凭证字，会计年度，会计期间，处理信息，异常信息，金蝶凭证号

1.6. BOS webservice 安全性
1.6.1. BOS webservice 安全性概述
BOS webservice 安全 有两种模式，启用安全性 和 不启用安全性，默认配置是不启用安全性。
1.6.2. 不启用安全性
在不启用安全性，则访问业务webservice前，先成功调用 EASLogin 登陆的webservice服务，则系统将记住相关登陆信息，下次调用业务方法是，直接从服务器中获取相关登陆信息。
如果多次调用 EASLogin webservice服务，则以最后一次为准。
1.6.3. 启用安全性
在启用安全性后，每次WEBSERVICE 访问，必须带上相关的 SessionID 信息，如下红字部分。系统将根据 SOAP头中的SessionID 信息，获取相关的上下文信息。

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:m0="http://com.kingdee.eas.base.btp.app.BTPManager/isPropOwner/parameter/promote">
<SOAP-ENV:Header>
<ns1:SessionId xmlns:ns1="">ada894c0-8223-41dc-b816-61eb67dc38bd</ns1:SessionId>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<m:isPropOwner xmlns:m="http://com.kingdee.eas.base.btp.app.BTPManager/Service">
<m0:bosTypeString>BF76D8D1</m0:bosTypeString>
<m0:propName>id</m0:propName>
</m:isPropOwner>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

1.6.4. 如何安全性启用
一、修改eas\Server\eas\server\profiles\server1\config\webservice.propetties文件
isRomoteLocate=false
isRomoteUserCheck=true

二、修改eas\Server\eas\server\deploy\eas.ear\ web.war 压缩文件中
WEB-INF 目录下server-config.wsdd 文件
...
<handler name="Authenticate" type=
"java:org.apache.axis.handlers.SimpleAuthenticationHandler"/>
<handler name="LoginHandler" type="java:com.kingdee.bos.webservice.LoginHandler"/>
...
<transport name="http">
<requestFlow>
...
<handler type="LoginHandler"/>
</requestFlow>
</transport>

1.7. EASLogin 登陆webservice 说明
1.7.1. EASLogin 接口说明
EASLogin 中有两个方法
方法一、
public WSContext login(
String userName,
String password,
String slnName,
String dcName,
String language ,
int dbType) throws AxisFault

方法二、public WSContext login(
String userName,
String password,
String slnName,
String dcName,
String language ,
int dbType,
String authPattern) throws AxisFault

参数说明:
userName: 登陆用户名
password: 登陆密码
slnName：解决方案名称（通常为 eas）
dcName: 数据中心 number
language： L1（英文）、L2(中文简体)、 L3(中文繁体)
dbType: 数据中心数据库类型
0(MS SQL Server)、1(DB2 UDB)、2(Oracle)
(历史遗留参数)
authPattern: EAS 的验证方式, 在方法一种默然为 BaseDB

1.7.2. EASLogin 异常说明
在 BOS6.2 版本中，EASLogin 登陆出错将会返回
失败返回报文

SOAP 协议中 soapenv:Fault 标签的相关说明
<faultcode>
供识别故障的代码
<faultstring>
可供人阅读的有关故障的说明
<faultactor>
有关是谁引发故障的信息
<detail>
存留涉及 Body 元素的应用程序专用错误信息

1.7.3. EASLogin 和前面版本的差别
EASLogin 在BOS 6.2 之前，登陆失败后，返回WSContext对象，当 WSContext. sessionId 是为null 或 空 时，表明登陆失败，失败的具体日志信息在 服务器日志中可以查看。

BOS 6.2 修改为当登陆失败，将返回 Fault 报文(通常客户端引擎代码会用异常方式表示)， Fault 中将包含具体的错误信息。同时服务器日志中也会打印出错误日志。

1.8. webservice 异常查看
webservice 调用错误，将可以在 EAS 相应的系统日志中查看到相应的信息。如 $EASHOME/ /server/profiles/server1/logs/ apusic.log.0

有的异常信息也会通过 SOAP 返回到客户端。可参考返回SOAP的faultstring元素中的错误详细信息。

2. WebService 客户端开发指南
2.1. 前提条件
WebService已经成功部署到应用服务器上（本文以Apusic为例进行说明），客户端可以通过浏览器访问到已部署的WebService，例如通过以下地址访问到已部署的WebService：http://localhost:6888/easws/services

2.2. 获取WSDL文件
如上图所示，应用服务器已经部署了相关的WebService。要构建相关的客户端，就要获取已经部署的WebService的相应的WSDL文件，用鼠标右键点击蓝色的部分“(wsdl)”，选取“目标另存为”菜单，这时将出现选择保存文件位置的对话框，在文件名处将文件的后缀名由xml改为wsdl，将wsdl文件保存至本地。

2.3. 生成客户端
2.3.1. 生成Java客户端
下面将以使用Eclipse3.1来生成java客户端为例进行说明。Eclipse3.1可以到www.eclipse.org免费下载。运行后，要为Eclipse配置至少一个相应的应用服务器，例如Tomcat5.5。
2.3.2. 建立一个新工程
例如建立一个工程名为GenerateWSClient的Java工程：

2.3.3. 将获取到的WSDL文件拷贝到工程的根目录下：

2.3.4. 生成客户端
用鼠标右键点击要生成客户端的WSDL文件，选取菜单“Web Services”-“Generate Client”

将会弹出生成客户端向导：

如图，使用默认值，点击“Next >”，进入下一步：

依然使用默认值，点击“Next >”，进入下一步：

依然使用默认值，点击“Finish”，即可生成相应的客户端工程（是一个Web工程）。

2.4. 使用java客户端
新生成的工程中有一个JavaSource目录，我们要使用的java代码就位于这个目录，例如上图中的WSLoginProxy.java。以下是一个使用Java客户端的例子：
import java.rmi.RemoteException;
import _111._19._168._192.easwebservice.services.easlogin.WSLoginProxy;
import client.WSContext;

public class LoginTest {
/**
* @param args
*/
public static void main(String[] args) {
try {
WSLoginProxy proxy = new WSLoginProxy();
WSContext ctx = proxy.login("fanfan", "", "eas", "eas50", "l2", 0);
System.out.println(ctx.getSessionId());
}
catch (RemoteException e) {
e.printStackTrace();
}
}
}
所调用的方法中的参数可以从WebService提供者处获得。

2.5. 生成C# 客户端
在此，以Microsoft Visual Studio .Net 2003为例说明如何生成C# 客户端。用户在正确安装完Microsoft Visual Studio .Net 2003后，需要设置一个环境变量Path= C:\Program Files\Microsoft Visual Studio .NET 2003\SDK\v1.1\Bin，其中C:\Program Files\Microsoft Visual Studio .NET 2003是Microsoft Visual Studio .NET 2003的安装路径。

2.5.1. 使用命令行
运行“cmd”，打开命令行窗口，并进入WSDL文件所在目录（在此为C:\wsdl目录）：

2.5.2. 运行命令生成客户端
运行命令wsdl XXX.wsdl（XXX为wsdl文件的文件名），即可生成C# 的WebService客户端代码：

输入途中命令，按回车键，即可自动生成C# 客户端代码：

如上图所示，生成了一个文件WSLoginService.cs，这就是我们所需要的客户断代码
2.5.3. 使用客户端代码
运行Microsoft Visual Studio .NET 2003，建立一个工程，将刚刚生成的WSLoginService.cs文件拷贝到工程的根目录，手工为该代码配置合适的命名空间：

这时就可以调用该客户端代码了。例如以下代码：
using System;

namespace ConsoleApplication1
{
/// <summary>
/// Summary description for Class1.
/// </summary>
class Class1
{
/// <summary>
/// The main entry point for the application.
/// </summary>
[STAThread]
static void Main(string[] args)
{
WSLoginService proxy = new WSLoginService();
WSContext ctx = proxy.login("fanfan", "", "eas", "eas50", "l2", 0);
Console.WriteLine(ctx.sessionId);
Console.ReadLine();
}
}
}
所调用的方法中的参数可以从WebService提供者处获得。

3. webservice FAQ
3.1. 在EAS 上如何发布一个webservice ?
请看 《BOS开发指南_WebService》文档
3.2. 如何调用一个 webservice？
请看 《BOS开发指南_WebService客户端开发》文档

3.3. 有哪些工具能够简单的测试 webservice？
可采用xmlspy 软件。
在 SOAPàCreate new SOAP requestà选择wsdl 文件，点击OK à 选择测试的方法à 在返回的SOAP报文中，输入相应的参数信息
在SOAP àSend request to server
xmlspy 将访问服务，并列出返回的 SOAP 报文。

3.4. EASLogin 服务登陆如何判断失败
在 BOS6.2 之前，EASLogin 服务返回 WSContext, 当 WSContext. sessionId 是为null 或 空 时，表明登陆失败，失败的具体日志信息在 服务器日志中可以查看。
在 BOS6.2 登陆失败，返回SOAP报文则BODY为FAULT标签（即客户端webservice引擎将抛出异常）

3.5. 调用webservice时报 com.kingdee.bos.IllegalSessionStateException: Please login first 异常？
1、在调用 业务的webservice前，需要先调用 EASLogin webservice 登陆。
2、判断调用 EASLogin webservice 是否成功。

3.6. EAS6.0调用webservice时报没有 WSConfig.getSrvURL() 方法。
打补丁 PT024717

3.7. 调用webservice时报.SocketTimeoutException: Read timed out 异常
在使用webservice客户端调用 webservice时，客户端默认会设置一个超时时间，当调用超过该时间后，客户端将会报 .SocketTimeoutException: Read timed out 异常。
可以通过客户端参数设置改变超时时间
如果采用axis1客户端：
call = (Call) service.createCall();
call.setTimeout(TIMEOUT);

如果采用axis2客户端：
ServiceClient call = new ServiceClient();
call.setOptions(options);
call.getOptions().setTimeOutInMilliSeconds(Constants.WSTIMEOUT);

4. Webservice返回复杂对象 List 或者JAVABEAN中包含List
axis返回对象的基本要求，Axis开发的Webservice中不能直接返回List对象，只能通过数组的方式返回，当然在直接返回List的例子中，服务端代码是返回List，但通过传输后客户端必须以数组的方式进行解读，因此建议直接返回数组方式。

4.1. 以下为例子源码
服务端代码：
package com.kingdee.model;

import java.util.List;
//书本
public class Book implements java.io.Serializable{
/**
*
*/
private static final long serialVersionUID = -8798284029723517521L;
//书本名称
private String name;
//书本价格
private Double price;

//一本书有多个作者进行编写 最好只能用数组方式，请勿用其他方式
private BookAuthor[] bookAuthor;

public String getName() {
return name;
}

public void setName(String name) {
this.name = name;
}

public Double getPrice() {
return price;
}

public void setPrice(Double price) {
this.price = price;
}
public BookAuthor[] getBookAuthor() {
return bookAuthor;
}
public void setBookAuthor(BookAuthor[] bookAuthor) {
this.bookAuthor = bookAuthor;
}
}

Package com.kingdee.model;
//作者
public class BookAuthor implements java.io.Serializable{

/**
*
*/
private static final long serialVersionUID = -6434694774033892935L;
//作者名称
private String name;
//作者简述
private String desc;

public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getDesc() {
return desc;
}
public void setDesc(String desc) {
this.desc = desc;
}

}

package com.kingdee.service;

import java.util.ArrayList;
import java.util.List;

import com.kingdee.model.Book;
import com.kingdee.model.BookAuthor;
//书本订购
public class BookOrder {

public static Book book=new Book();
//设置要订购的书名称
public String setBookName(String name)
{
book.setName(name);
BookAuthor[] authorList=new BookAuthor[1];
BookAuthor author=new BookAuthor();
author.setName("bookAuthor");
author.setDesc("authorDesc");
authorList[0]=author;
book.setBookAuthor(authorList);
return "success";
}
//根据名称返回书本，一个书本有多个作者
public Book getBookByName(String name)
{

if(name!=null&&!"".equalsIgnoreCase(name)&&name.equalsIgnoreCase(book.getName()))
return book;
else
return null;
}
//返回所有（多个）书本
public List getAllBooks()
{
List bookList=new ArrayList();

bookList.add(book);

return bookList;
}
}

4.2. 关键配置

<！--定义的webservice名称 -->
<service name="BookService" provider="java