BOS_V63_BOS开发指南_WebService.doc

BOSWebService21.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.测试是否正确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.EASLogin 和前面版本的差别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.如何调用一个 webservice？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. BOSWebService原理Webservice 主要由SOAP，WSDL, 以及UDDI 等几块技术组成，以XML格式进行数据的传输。是建立可互操作的分布式应用程序的新平台Webservice的一个最基本的目的就是提供在各个不同平台的不同应用系统的协同工作能力。使各个异构系统之间实现无缝交互。在本质上是要为应用程序之间提供数据通讯的标准，为企业应用之间动态地提供大颗粒度的服务，并不适合于非常精细的基于会话的方法调用以及复杂的事务（transaction）处理之中。1.2. 发布WebService的约束 在BOS Studio中发布webService时，只能发布Entity和Faade两种元数据类型成WebService服务端的代码。 由于Entity或Faade函数参数和返回值可能包含很多复杂的业务类型，在发布时会生成许多辅助类，一些复杂类型在其他异构系统中生成webService客户端时不能很好的支持，因此建议在建立webService功能时，最好使用Faade，并且提供简单类型的输入和返回参数。1.3. BOSWebService发布1.3.1. 发布流程 先建立需要发布的Faade,建立粗粒度的业务方法，业务方法尽可能提供简单数据类型的数据参数和返回参数。1.3.2. 发布WebService 运行BOS Studio，打开“包分类”视图，在其中选中要发布WebService的实体或Faade对象（可同时选中多个），点击鼠标右键，在弹出菜单中选择“发布WebService”,将弹出“发布WebService”向导： 选择实体或Faade对象下要发布的方法，手工输入或者点击“浏览”按钮来指定发布生成代码存放的目录，可以同时勾中“追加到配置文件”。这样BOS Studio将会根据选中的对象和要发布的方法生成WebService代码和wsdl描述1.3.3. 编辑WebService配置文件在“包分类”视图中，选择要编辑其配置文件的解决方案，点击工具栏上的“编辑WebService 配置文件”按钮，将会弹出配置文件编辑向导在其间，可以增加或删除要发布的对象（方法），选择好要发布的对象（方法）后，点击“完成”按钮，即可完成对配置文件的编辑。配置文件位于解决方案的根目录下。1.4. BOSWebService部署 1.4.1. 建立web工程在apusicdomainsserver1applications下建立一个web工程。（web工程可以从easServerserverdeployeas.earweb.war解压） 然后配置apusicdomainsserver1configserver.xml文件，在下添加 工程 重新启动服务器，访问当前工程是否可用： http:/localhost:6888/web1.4.2. 部署发布文件将生成的Web Serivce 的java代码编译为class或打成jar包，放在web目录下相应的webWEB-INFclasses下或webWEB-INFlib目录中，把发布的wsdd文件中服务部分拷贝到server-config.wsdd中。如EASLogin.wsdd中内容拷贝到server-config.wsdd。1.4.3. 测试是否正确重新启动服务器，通过浏览器输入服务的地址，访问服务是否正确如输入：http:/localhost:6888/web/service?1.4.4. Web工程目录及文件截图1.5. 客户端代码1.5.1. 获取wsdl服务描述文件WebService已经成功部署到应用服务器上（本文以Apusic为例进行说明），客户端可以通过浏览器访问到已部署的WebService。要构建相关的客户端，就要获取已经部署的WebService的相应的WSDL文件，用鼠标右键点击蓝色的部分“(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文件拷贝到工程的根目录下用鼠标右键点击要生成客户端的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); /成功登录后打印sessionIdSystem.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 信息，获取相关的上下文信息。ada894c0-8223-41dc-b816-61eb67dc38bdBF76D8D1id1.6.4. 如何安全性启用一、修改easSpetties文件 isRomoteLocate=falseisRomoteUserCheck=true二、修改easServereasserverdeployeas.ear web.war 压缩文件中 WEB-INF 目录下server-config.wsdd 文件 . . . 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: 数据中心 numberlanguage： L1（英文）、L2(中文简体)、 L3(中文繁体)dbType: 数据中心数据库类型 0(MS SQL Server)、1(DB2 UDB)、2(Oracle)(历史遗留参数)authPattern: EAS 的验证方式, 在方法一种默然为 BaseDB1.7.2. EASLogin 异常说明在 BOS6.2 版本中，EASLogin 登陆出错将会返回 失败返回报文SOAP 协议中 soapenv:Fault 标签的相关说明供识别故障的代码可供人阅读的有关故障的说明有关是谁引发故障的信息存留涉及 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/services2.2. 获取WSDL文件如上图所示，应用服务器已经部署了相关的WebService。要构建相关的客户端，就要获取已经部署的WebService的相应的WSDL文件，用鼠标右键点击蓝色的部分“(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文件拷贝到工程的根目录下：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 FilesMicrosoft 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# 客户端代码：如上图所示，生成了一个文件WSLoginService.cs，这就是我们所需要的客户断代码2.5.3. 使用客户端代码运行Microsoft Visual Studio .NET 2003，建立一个工程，将刚刚生成的WSLoginService.cs文件拷贝到工程的根目录，手工为该代码配置合适的命名空间：这时就可以调用该客户端代码了。例如以下代码：using System;namespace ConsoleApplication1/ / Summary description for Class1./ class Class1/ / The main entry point for the application./ STAThreadstatic 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 FAQ3.1. 在EAS 上如何发布一个webservice ?请看 BOS开发指南_WebService文档3.2. 如何调用一个 webservice？请看 BOS开发指南_WebService客户端开发文档3.3. 有哪些工具能够简单的测试 webservice？可采用xmlspy 软件。在 SOAPCreate new SOAP request选择wsdl 文件，点