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

WebserviceWebservice 开发指南开发指南 版权声明版权声明 本书著作权属于金蝶软件 中国 有限公司所有 在未经本公司许可的情况下 任何单 位或个人不得以任何方式对本书的部分或全部内容擅自进行增删 改编 节录 翻译 翻 印 改写 金蝶软件 中国 有限公司 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 BOSWebServiceBOSWebService 1 1 BOSWebService 原理原理 Webservice 主要由 SOAP WSDL 以及 UDDI 等几块技术组成 以 XML 格式进行数据的 传输 是建立可互操作的分布式应用程序的新平台 Webservice 的一个最基本的目的就是提供在各个不同平台的不同应用系统的协同工作 能力 使各个异构系统之间实现无缝交互 在本质上是要为应用程序之间提供数据通讯的 标准 为企业应用之间动态地提供大颗粒度的服务 并不适合于非常精细的基于会话的方 法调 用以及复杂的事务 transaction 处理之中 1 2 发布发布 WebService 的约束的约束 在在 BOSBOS StudioStudio 中发布中发布 webServicewebService 时 只能发布时 只能发布 EntityEntity 和和 Fa adeFa ade 两种元数据类两种元数据类 型成型成 WebServiceWebService 服务端的代码 服务端的代码 由于 Entity 或 Fa ade 函数参数和返回值可能包含很多复杂的业务类型 在发布时 会生成许多辅助类 一些复杂类型在其他异构系统中生成 webService 客户端时不能很好的 支持 因此建议在建立因此建议在建立 webServicewebService 功能时 最好使用功能时 最好使用 Fa adeFa ade 并且提供简单类型的输入 并且提供简单类型的输入 和返回参数 和返回参数 1 3 BOSWebService 发布发布 1 3 1 1 3 1 发布流程发布流程 先建立需要发布的 Fa ade 建立粗粒度的业务方法 业务方法尽可能提供简单数据类型的 数据参数和返回参数 1 3 2 1 3 2 发布发布 WebServiceWebService 运行 BOS Studio 打开 包分类 视图 在其中选中要发布 WebService 的实体或 Fa ade 对象 可同时选中多个 点击鼠标右键 在弹出菜单中选择 发布 WebService 将弹出 发布 WebService 向导 选择实体或 Fa ade 对象下要发布的方法 手工输入或者点击 浏览 按钮来指定发布生成代码 存放的目录 可以同时勾中 追加到配置文件 这样 BOS Studio 将会根据选中的对象和要发 布的方法生成 WebService 代码和 wsdl 描述 1 3 3 1 3 3 编辑编辑 WebServiceWebService 配置文件配置文件 在 包分类 视图中 选择要编辑其配置文件的解决方案 点击工具栏上的 编辑 WebService 配置文件 按钮 将会弹出配置文件编辑向导 在其间 可以增加或删除要发布的对象 方法 选择好要发布的对象 方法 后 点击 完 成 按钮 即可完成对配置文件的编辑 配置文件位于解决方案的根目录下 1 4 BOSWebService 部署部署 1 4 1 1 4 1 部署发布文件部署发布文件 发布成功以后 在临时目录里会生成一个 wsdd 文件和一个目录 例如 D webtest AcctCussentCheckFacade wsdd D webtest com kingdee eas fi gl app webservice WSAcctCussentCheckFacadeSrv Proxy 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 1 4 2 测试是否正确测试是否正确 上面的步骤操作完成后 快测已经可以看到新建的 WebService 通过浏览器输入服务 的地址 访问服务是否正确 如输入 http server ip port ormrpc services BOS 快测启动的默认端口为 56898 1 4 3 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 1 4 4 WebWeb 工程目录及文件截图工程目录及文件截图 1 5 客户端代码客户端代码 1 5 1 1 5 1 获取获取 wsdlwsdl 服务描述文件服务描述文件 WebService 已经成功部署到应用服务器上 本文以 Apusic 为例进行说明 客户端可以 通过浏览器访问到已部署的 WebService 要构建相关的客户端 就要获取已经部署的 WebService 的相应的 WSDL 文件 用鼠标右键点击 蓝色的部分 wsdl 选取 目标另存为 菜单 这时将出现选择保存文件位置的对话框 在文件名处将文件的后缀名由 xml 改为 wsdl 将 wsdl 文件保存至本地 1 5 2 1 5 2 下载工具下载工具 通过 www eclipse org 下载 eclipse 下载 j2ee 版本 或通过命令行来生成 java Djava ext dirs lib org apache axis wsdl WSDL2Java 其中 lib 是 axis 包目录生成客户端代码 1 5 3 1 5 3 建立一个新工程建立一个新工程 例如建立一个工程名为 GenerateWSClient 的 Java 工程 将获取到的 WSDL 文件拷贝到工程的根目录下 用鼠标右键点击要生成客户端的 WSDL 文件 选取菜单 Web Services Generate Client 将会弹出生成客户端向导 如图 使用默认值 点击 Next 进入下一步 依然使用默认值 点击 Next 进入下一步 依然使用默认值 点击 Finish 即可生成相应的客户端工程 是一个 Web 工程 1 5 4 1 5 4 使用使用 javajava 客户端客户端 新生成的工程中有一个 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 1 5 5 importVoucherimportVoucher 凭证引入 凭证引入 1 凭证引入接口 两个接口方法都可用 且用法一致 2 凭证 webService 接口生成客户端 可参考 EASLogin 方法 3 凭证引入参数 importVoucher wsvoucher int isVerify int isCashflow 传参数第1个 WSWSVoucher 普通对象数组 见构造EAS凭证字段以及含义说 明 传参数第2个 isverify 0 不核销 暂存 1 核销 暂存 2 不核销 提交 3 核销 提交 传参数第3个 isImpCashflow 是否引入现金流量 0 不引入1 引入 4 凭证引入代码调用说明 5 返回值 String 是一个长度为凭证数 宽度是 5 的字符串数据 宽度的定义 外部系统凭证号 凭证字 会计年度 会计期间 处理信息 异常信 息 金蝶凭证号 1 6 BOS webservice 安全性安全性 1 6 1 1 6 1 BOSBOS webservicewebservice 安全性概述安全性概述 BOS webservice 安全 有两种模式 启用安全性 和 不启用安全性 默认配置是不 启用安全性 1 6 2 1 6 2 不启用安全性不启用安全性 在不启用安全性 则访问业务 webservice 前 先成功调用 EASLogin 登陆的 webservice 服务 则系统将记住相关登陆信息 下次调用业务方法是 直接从服务器 中获取相关登陆信息 如果多次调用 EASLogin webservice 服务 则以最后一次为准 1 6 3 1 6 3 启用安全性启用安全性 在启用安全性后 每次 WEBSERVICE 访问 必须带上相关的 SessionID 信息 如下 红字部分 系统将根据 SOAP 头中的 SessionID 信息 获取相关的上下文信息 ada894c0 8223 41dc b816 61eb67dc38bd BF76D8D1 id 1 6 4 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 文件 1 7 EASLogin 登陆登陆 webservice 说明说明 1 7 1 1 7 1 EASLoginEASLogin 接口说明接口说明 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 1 7 2 EASLoginEASLogin 异常说明异常说明 在 BOS6 2 版本中 EASLogin 登陆出错将会返回 失败返回报文 SOAP 协议中 soapenv Fault 标签的相关说明 供识别故障的代码 可供人阅读的有关故障的说明 有关是谁引发故障的信息 存留涉及 Body 元素的应用程序专用错误信息 1 7 3 1 7 3 EASLoginEASLogin 和前面版本的差别和前面版本的差别 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 2 3 1 生成生成 JavaJava 客户端客户端 下面将以使用 Eclipse3 1 来生成 java 客户端为例进行说明 Eclipse3 1 可以到 www eclipse org 免费下载 运行后 要为 Eclipse 配置至少一个相应的应用服务器 例如 Tomcat5 5 2 3 2 2 3 2 建立一个新工程建立一个新工程 例如建立一个工程名为 GenerateWSClient 的 Java 工程 2 3 3 2 3 3 将获取到的将获取到的 WSDLWSDL 文件拷贝到工程的根目录下 文件拷贝到工程的根目录下 2 3 4 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 2 5 1 使用命令行使用命令行 运行 cmd 打开命令行窗口 并进入 WSDL 文件所在目录 在此为 C wsdl 目录 2 5 2 2 5 2 运行命令生成客户端运行命令生成客户端 运行命令 wsdl XXX wsdl XXX 为 wsdl 文件的文件名 即可生成 C 的 WebService 客户端代 码 输入途中命令 按回车键 即可自动生成 C 客户端代码 如上图所示 生成了一个文件 WSLoginService cs 这就是我们所需要的客户断代码 2 5 3 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 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 bookAutho