金蝶EAS_V81_WebService开发指南

1、Webservice开发指南版权声明本书著作权属于金蝶软件(中国)有限公司所有，在未经本公司许可的情况下，任何单位或个人不得以任何方式对本书的部分或全部内容擅自进行增删，改编，节录，翻译，翻印，改写。金蝶软件（中国）有限公司2015年8月BOSWebService1.1.BOSWebService原理21.2.发布WebService的约束31.3.BOSWebService发布31.3.1.发布流程31.3.2.发布WebService31.3.3.编辑WebService配置文件41.4.BOSWebService部署51.4.1.建立web工程51.4.2.部署发布文件51.4.3.测试

2、是否正确61.4.4.Web工程目录及文件截图61.5.客户端代码61.5.1.获取wsdl服务描述文件61.5.2.下载工具71.5.3.建立一个新工程71.5.4.使用java客户端111.5.5.importVoucher（凭证引入121.6.BOS webservice 安全性131.6.1.BOS webservice 安全性概述131.6.2.不启用安全性131.6.3.启用安全性131.6.4.如何安全性启用141.7.EASLogin 登陆webservice 说明141.7.1.EASLogin 接口说明141.7.2.EASLogin 异常说明151.7.3.EASLogi

3、n 和前面版本的差别161.8.webservice 异常查看162.WebService 客户端开发指南172.1.前提条件172.2.获取WSDL文件172.3.生成客户端182.3.1.生成Java客户端182.3.2.建立一个新工程182.3.3.将获取到的WSDL文件拷贝到工程的根目录下：192.3.4.生成客户端192.4.使用java客户端232.5.生成C# 客户端232.5.1.使用命令行232.5.2.运行命令生成客户端242.5.3.使用客户端代码253.webservice FAQ273.1.在EAS 上如何发布一个webservice ?273.2.如何调用一个 we

4、bservice？273.3.有哪些工具能够简单的测试 webservice？273.4.EASLogin 服务登陆如何判断失败273.5.调用webservice时报 com.kingdee.bos.IllegalSessionStateException: Please login first 异常？273.6.EAS6.0调用webservice时报没有 WSConfig.getSrvURL() 方法。283.7.调用webservice时报.SocketTimeoutException: Read timed out 异常28BOSWebService1.1. BOSWebServic

5、e原理Webservice 主要由SOAP，WSDL, 以及UDDI 等几块技术组成，以XML格式进行数据的传输。是建立可互操作的分布式应用程序的新平台Webservice的一个最基本的目的就是提供在各个不同平台的不同应用系统的协同工作能力。使各个异构系统之间实现无缝交互。在本质上是要为应用程序之间提供数据通讯的标准，为企业应用之间动态地提供大颗粒度的服务，并不适合于非常精细的基于会话的方法调用以及复杂的事务（transaction）处理之中。1.2. 发布WebService的约束 在BOS Studio中发布webService时，只能发布Entity和Façade两种元数据类型

6、成WebService服务端的代码。 由于Entity或Façade函数参数和返回值可能包含很多复杂的业务类型，在发布时会生成许多辅助类，一些复杂类型在其他异构系统中生成webService客户端时不能很好的支持，因此建议在建立webService功能时，最好使用Façade，并且提供简单类型的输入和返回参数。1.3. BOSWebService发布1.3.1. 发布流程 先建立需要发布的Façade,建立粗粒度的业务方法，业务方法尽可能提供简单数据类型的数据参数和返回参数。1.3.2. 发布WebService 运行BOS Studio，打开“包分类”视图，在其

7、中选中要发布WebService的实体或Façade对象（可同时选中多个），点击鼠标右键，在弹出菜单中选择“发布WebService”,将弹出“发布WebService”向导： 选择实体或Façade对象下要发布的方法，手工输入或者点击“浏览”按钮来指定发布生成代码存放的目录，可以同时勾中“追加到配置文件”。这样BOS Studio将会根据选中的对象和要发布的方法生成WebService代码和wsdl描述1.3.3. 编辑WebService配置文件在“包分类”视图中，选择要编辑其配置文件的解决方案，点击工具栏上的“编辑WebService 配置文件”按钮，将会弹出配置文件

8、编辑向导在其间，可以增加或删除要发布的对象（方法），选择好要发布的对象（方法）后，点击“完成”按钮，即可完成对配置文件的编辑。配置文件位于解决方案的根目录下。1.4. BOSWebService部署 1.4.1. 部署发布文件发布成功以后，在临时目录里会生成一个wsdd文件和一个目录，例如：D:webtestAcctCussentCheckFacade.wsddD:webtestcomkingdeeeasfiglappwebserviceWSAcctCussentCheckFacadeSrvProxy.javaWSAcctCussentCheckFacadeSrvProxy.java文件拷贝到

9、解决方案src目录中，注意包名和路径一致；AcctCussentCheckFacade.wsdd处理方法如下：找到解决方案的runtimeserverdeployeas.ear目录，用解压缩软件打开web.war，进入WEB-INF目录把AcctCussentCheckFacade.wsdd添加进去；把AcctCussentCheckFacade.wsdd文件里的service节点内容添加到server-config.wsdd文件。操作方法建议：提取server-config.wsdd文件到临时目录，用编辑工具打开，再打开AcctCussentCheckFacade.wsdd，拷贝servic

10、e节点内容粘贴到server-config.wsdd文件，注意XML格式一致；保存server-config.wsdd文件并拷回到web.war压缩包里。1.4.2. 测试是否正确上面的步骤操作完成后，快测已经可以看到新建的WebService。通过浏览器输入服务的地址，访问服务是否正确如输入：http:/server-ip:port/ormrpc/services BOS快测启动的默认端口为568981.4.3. 部署到正式服务器1、在BIM中部署代码和元数据；2、把解决方案下改好的runtimeserverdeployeas.earweb.war文件拷贝到EAS服务器的serverdepl

11、oyeas.ear目录中，3.将生成的Web Service的java代码编译为class,放在EAS服务器的easserverdeployeas.earweb.warWEB-INFclass下，把发布的wsdd文件中服务部分拷贝到server-config.wsdd中。4.重启EAS服务器1.4.4. Web工程目录及文件截图1.5. 客户端代码1.5.1. 获取wsdl服务描述文件WebService已经成功部署到应用服务器上（本文以Apusic为例进行说明），客户端可以通过浏览器访问到已部署的WebService。要构建相关的客户端，就要获取已经部署的WebService的相应的WSDL

12、文件，用鼠标右键点击蓝色的部分“(wsdl)”，选取“目标另存为”菜单，这时将出现选择保存文件位置的对话框，在文件名处将文件的后缀名由xml改为wsdl，将wsdl文件保存至本地。1.5.2. 下载工具 通过下载eclipse（下载j2ee版本）或通过命令行来生成java -Djava.ext.dirs=lib org.apache.axis.wsdl.WSDL2Java 其中lib是axis包目录生成客户端代码。1.5.3. 建立一个新工程 例如建立一个工程名为GenerateWSClient的Java工程：将获取到的WSDL文件拷贝到工程的根目录下用鼠标右键点

13、击要生成客户端的WSDL文件，选取菜单“Web Services”-“Generate Client”将会弹出生成客户端向导如图，使用默认值，点击“Next >”，进入下一步：依然使用默认值，点击“Next >”，进入下一步：依然使用默认值，点击“Finish”，即可生成相应的客户端工程（是一个Web工程）1.5.4. 使用java客户端新生成的工程中有一个JavaSource目录，我们要使用的java代码就位于这个目录，例如上图中的WSLoginProxy.java。以下是一个使用Java客户端的例子：import java.rmi.RemoteException;import

14、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 数据库类型

15、0:sqlServer 1:db2 2:oracle * authPattern 验证方式 默认 "BaseDB" ; 其他认证方式KEY可从easAuthPatterns.xml中获取 */WSContext ctx = proxy.login("用户", "", "eas", "数据中心id", "L2", 0); /成功登录后打印sessionIdSystem.out.println(ctx.getSessionId(); /调用凭证业务webservice方法impo

16、rtVoucher（凭证引入），请看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 核销，

17、暂存 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前，先成功调用 EASLogi

18、n 登陆的webservice服务，则系统将记住相关登陆信息，下次调用业务方法是，直接从服务器中获取相关登陆信息。如果多次调用 EASLogin webservice服务，则以最后一次为准。1.6.3. 启用安全性在启用安全性后，每次WEBSERVICE 访问，必须带上相关的 SessionID 信息，如下红字部分。系统将根据 SOAP头中的SessionID 信息，获取相关的上下文信息。<SOAP-ENV:Envelope xmlns:SOAP-ENV="/soap/envelope/" xmlns:SOAP-ENC

19、="/soap/encoding/" xmlns:xsi="/2001/XMLSchema-instance" xmlns:xsd="/2001/XMLSchema" xmlns:m0="http:/com.kingdee.eas.base.btp.app.BTPManager/isPropOwner/parameter/promote"><SOAP-ENV:Header><ns

20、1: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:

21、propName>id</m0:propName></m:isPropOwner></SOAP-ENV:Body></SOAP-ENV:Envelope>1.6.4. 如何安全性启用一、修改easSpetties文件 isRomoteLocate=falseisRomoteUserCheck=true二、修改easServereasserverdeployeas.ear web.war 压缩文件中 WEB-INF 目录下server-confi

22、g.wsdd 文件 . <handler name="Authenticate" type= "java:org.apache.axis.handlers.SimpleAuthenticationHandler"/> <handler name="LoginHandler" type="java:com.kingdee.bos.webservice.LoginHandler"/> . <transport name="http"> <requestFlo

23、w> . <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方法二、publ

24、ic WSContext login( String userName, String password, String slnName, String dcName, String language , int dbType, String authPattern) throws AxisFault参数说明:userName: 登陆用户名password: 登陆密码slnName：解决方案名称（通常为 eas）dcName: 数据中心 numberlanguage： L1（英文）、L2(中文简体)、 L3(中文繁体)dbType: 数据中心数据库类型 0(MS SQL Server)、1(D

25、B2 UDB)、2(Oracle)(历史遗留参数)authPattern: EAS 的验证方式, 在方法一种默然为 BaseDB1.7.2. EASLogin 异常说明在 BOS6.2 版本中，EASLogin 登陆出错将会返回 失败返回报文SOAP 协议中 soapenv:Fault 标签的相关说明<faultcode>供识别故障的代码<faultstring>可供人阅读的有关故障的说明<faultactor>有关是谁引发故障的信息<detail>存留涉及 Body 元素的应用程序专用错误信息1.7.3. EASLogin 和前面版本的差别EA

26、SLogin 在BOS 6.2 之前，登陆失败后，返回WSContext对象，当 WSContext. sessionId 是为null 或 空 时，表明登陆失败，失败的具体日志信息在 服务器日志中可以查看。BOS 6.2 修改为当登陆失败，将返回 Fault 报文(通常客户端引擎代码会用异常方式表示)， Fault 中将包含具体的错误信息。同时服务器日志中也会打印出错误日志。1.8. webservice 异常查看webservice 调用错误，将可以在 EAS 相应的系统日志中查看到相应的信息。如 $EASHOME/ /server/profiles/server1/logs/ apusi

27、c.log.0有的异常信息也会通过 SOAP 返回到客户端。可参考返回SOAP的faultstring元素中的错误详细信息。2. WebService 客户端开发指南2.1. 前提条件WebService已经成功部署到应用服务器上（本文以Apusic为例进行说明），客户端可以通过浏览器访问到已部署的WebService，例如通过以下地址访问到已部署的WebService：http:/localhost:6888/easws/services2.2. 获取WSDL文件如上图所示，应用服务器已经部署了相关的WebService。要构建相关的客户端，就要获取已经部署的WebService的相应的WS

28、DL文件，用鼠标右键点击蓝色的部分“(wsdl)”，选取“目标另存为”菜单，这时将出现选择保存文件位置的对话框，在文件名处将文件的后缀名由xml改为wsdl，将wsdl文件保存至本地。2.3. 生成客户端2.3.1. 生成Java客户端下面将以使用Eclipse3.1来生成java客户端为例进行说明。Eclipse3.1可以到免费下载。运行后，要为Eclipse配置至少一个相应的应用服务器，例如Tomcat5.5。2.3.2. 建立一个新工程例如建立一个工程名为GenerateWSClient的Java工程：2.3.3. 将获取到的WSDL文件拷贝到工程的根目录下

29、：2.3.4. 生成客户端用鼠标右键点击要生成客户端的WSDL文件，选取菜单“Web Services”-“Generate Client”将会弹出生成客户端向导：如图，使用默认值，点击“Next >”，进入下一步：依然使用默认值，点击“Next >”，进入下一步：依然使用默认值，点击“Finish”，即可生成相应的客户端工程（是一个Web工程）。2.4. 使用java客户端新生成的工程中有一个JavaSource目录，我们要使用的java代码就位于这个目录，例如上图中的WSLoginProxy.java。以下是一个使用Java客户端的例子：import java.rmi.Remo

30、teException;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

31、", "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

32、Microsoft Visual Studio .NET 2003SDKv1.1Bin，其中C:Program FilesMicrosoft 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# 客户端代码：如上图所示，生成了一

33、个文件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

34、>/ The main entry point for the application./ </summary>STAThreadstatic void Main(string args)WSLoginService proxy = new WSLoginService();WSContext ctx = proxy.login("fanfan", "", "eas", "eas50", "l2", 0);Console.WriteLine(ctx.sessionId);Con

35、sole.ReadLine();所调用的方法中的参数可以从WebService提供者处获得。3. webservice FAQ3.1. 在EAS 上如何发布一个webservice ?请看 BOS开发指南_WebService文档3.2. 如何调用一个 webservice？请看 BOS开发指南_WebService客户端开发文档3.3. 有哪些工具能够简单的测试 webservice？可采用xmlspy 软件。在 SOAPàCreate new SOAP requestà选择wsdl 文件，点击OK à 选择测试的方法à 在返回的SOAP报文中，输入相

36、应的参数信息在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.IllegalSess

37、ionStateException: Please login first 异常？1、在调用 业务的webservice前，需要先调用 EASLogin webservice 登陆。2、判断调用 EASLogin webservice 是否成功。3.6. EAS6.0调用webservice时报没有 WSConfig.getSrvURL() 方法。打补丁 PT0247173.7. 调用webservice时报.SocketTimeoutException: Read timed out 异常在使用webservice客户端调用 webservice时，客户端默认会设置一个超时时间，当调用超过该

38、时间后，客户端将会报 .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. Webservic

39、e返回复杂对象 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

40、long serialVersionUID = -8798284029723517521L;/书本名称private String name;/书本价格private Double price;/一本书有多个作者进行编写 最好只能用数组方式，请勿用其他方式private BookAuthor bookAuthor;public String getName() return name;public void setName(String name) = name;public Double getPrice() return price;public void setPri

41、ce(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

42、= -6434694774033892935L;/作者名称private String name;/作者简述private String desc;public String getName() return name;public void setName(String name) = name;public String getDesc() return desc;public void setDesc(String desc) this.desc = desc;package com.kingdee.service;import java.util.ArrayList

43、;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 BookAuthor1;BookAuthor author=new BookAuthor();author.s

44、etName("bookAuthor");author.setDesc("authorDesc");authorList0=author;book.setBookAuthor(authorList);return "success"/根据名称返回书本，一个书本有多个作者public Book getBookByName(String name)if(name!=null&&!"".equalsIgnoreCase(name)&&name.equalsIgnoreCase(book.g

45、etName()return book;elsereturn null;/返回所有（多个）书本public List getAllBooks()List bookList=new ArrayList();bookList.add(book);return bookList;4.2. 关键配置<！-定义的webservice名称 -> <service name="BookService" provider="java:RPC"> <parameter name="className" value="com.kingdee.service.BookOrder" /> <parameter name="allowedMethods" value="*" /> <!- 这里定义了方法的参数以及返回值 可以不写 ->