产品二次开发培训10webservice2组件开发手册

1、文档控制/Control修改审阅人分发日期分发人分发对象备注日期审阅人版本备注日期作者版本备注2011-12-21V1.0草稿目录第一章引言编写目的5文档约定5. 5第二章概述72.1总体设计7第三章系统功能3.7服务. 9运行管理9运行日志10超时. 11用户帐号设置11运行日志备份12辅助功能12第四章WEBSERVICE 数据接口134.14.2组织架构接口13附件接口15第五章WEBSERVICE 服务端开发5.4开发和部署流程18开发 SPRING BEAN18实现扩展19导入并发布19第六章WEBSER

2、VICE 客户端开发6.76.8JAVA 客户端19.NET 客户端20DOMINO 客户端21认证23附件上传23流程表单数据24流程参数25时间类型26第七章FAQ27第八章附录288.1SOAP 消息的结构28第一章 引言1.1 编写目的本文可以指导技术如何在 EKP-J 产品中利用 WebService2 组件来开发、部署和发布WebService ， 以及在集成的第系统中， 如何开发客户端程序来产品中的WebService。系统管理也可以参考此文档来管理 WebService2 组件的日常运行，WebService 的运行状况。1.2 文档约定

3、本文档采用 MS word（兼容 office2003）编写，采用风格编写，正文风格为：五号中文宋体、五号英文 Ariai 字体、行距 1.5 行。针对需要重点主要的段落，采用红色描色。针对代码片段，采用斜体字加框的样式，为了排版美观，建议保留 eclipse 的样式，如下：1.3扩展点和扩展的容器，此容器与 Java 容器的生命周期一致。根据 plugin.xml插件工厂：的配置，自动把相应的配置信息到工厂容器中，以备扩展点的提供方调用。WSDL： 网络服务描述语言（Web ServiDescription Language），是用于描述 Web Service以及如何对它们进行的 XML

4、语言。SOAP：一种基于 XML 的轻量级协议，用于在分布式环境换信息，它使应用程序通过HTTP 来交换信息。Servi。CXF 来自于 XFire 项目，实现了 ESB（企业服务总线）。JAX-WS 规范：提供了一组 XML web servi的 JAVA API。JAX-WS 允许开发者可以选择RPC-oriented 或者 message-oriented 来实现自己的 web servi。在 JAX-WS 中，一个Apache CXF：一个开源的 Servi框架，它提供了 Frontend 编程 API 来构建和开发public sic SysElement getSalesByAre

5、a(String area) /在这里编写您的业务逻辑调用可以转换为一个基于 XML 的协议例如 SOAP。在使用 JAX-WS 过程中，开发者不需要编写任何生成和处理 SOAP 消息的代码。JAX-WS 的运行时实现会将这些 API 的调用转换成为对应的 SOAP 消息。MTOM：全称 Message TransmisOptimization Mechanism，即消息传输优化机制。使用MTOM 的目的在于优化对较大的二进制负载的传输，如上传文档和等。第二章 概述Web Service 是一个开放的标准，适用于处理异构系统之间的通信和。WebService2 组件对系统中的 Web Serv

6、ice 进行管理，提供对 WebService 的发布和查找机制、安全认证服务、运行日志和审计功能以及服务运行的和。WebService2 组件简化了 WebService 的部署和开发过程，使开发可以专注于业务实现，并且提供了一些辅助工具和数据接口以提高开发效率。2.1 总体设计2.1.1总体结构图2.1.2设计思路WebService2 组件是基于 Apache CXF 开源框架，采用 JAX-WS 规范设计和开发的。系统在底层处理对webservice 的安全认证和服务运行，并WebService 的执行情况。开发根据业务编写 Spring Bean，在插件工厂中添加 WebServic

7、e 扩展，然后导入（类似定时任务）即可完成 WebService 的发布。2.1.3功能介绍WebService2 组件的主要功能有服务管理、运行日志及审计、超时和帐号设置等。服务提供对系统中 Web Service 的集中管理。信息定义了服务的名称、接口及说明等信息。运行管理包括启动服务、停止服务、启动类型设置、安全认证设置、用户最大连接控制等功能。运行日志WebService 的执行情况，为审计分析服务提供依据。的信息包括服务名称、服务标识、用户、客户端 IP 地址、服务启动时间、服务结束时间，执行结果和错误信息等；可以根据这些信息搜索日志；可以对指定的 WebService 开启 Soa

8、p 消息功能，记录服务端完整的入站消息和出站消息内容。超时显示所有运行时间超过最大运行时长设定的服务。用户帐号设置设置 WebService 用户帐号信息。包括用户名、可的 WebService、可以使用的客户端 IP 等。运行日志备份支持定期自动转移日志到备份表中，并且可以定期日志备份表中的数据。辅助功能包括Java 客户端、查看 WSDL、服务接口帮助等功能。第三章 系统功能3.1 服务管理系统中 WebService 的信息，包括服务名称、服务接口及实现类名、接口帮助说明等。如下所示：这些信息定义在各功能模块的 plugin.xml 文件中，由 WebService2 组件管理，可以在系

9、统中导入这些信息。“导入 WEB 服务”功能将插件工厂的扩展中定义的 WebService 信息更新到系统数据库。如果数据库中已存在此 WebService 则更新信息，包括服务名称、服务接口及实现类名、接口帮助说明文档，其它运行配置参数不变；如果不存在则添加此 WebService，启动类型默认自动。服务成功导入后会启动所有启动类型为自动的 WebService，无需重启 EKP 即可供外部。WebService 的过程在第五章中有详细描述，在此略过。3.2 运行管理包括启动服务、停止服务、启动类型设置、安全认证设置、用户最大连接控制等功能。运行配置信息如下图所示，可以对每个 WebServ

10、ice 单独配置运行参数。启动服务：启动选定的 WebService，支持批量操作。服务成功启动后才可以被外部；停止服务：停止选定的 WebService，支持批量操作；已停止的服务不能被外部访问；路径：客户端WebService 的 URL 路径，由系统分配，此项为只读；允许：默认情况下，客户端需要提供用户口令等认证信息才能服务，如果允许，则服务端关闭验证，客户端服务无需提供认证信息；服务状态：分为“已启动”和“已停止”两种状态，管理员可以在系统运行的过程中启动或停止 WebService，服务成功启动后就可以被外部，无需重启服务器；启动类型：分为自动、手动、禁用三种类型。默认情况下，系统启

11、动时会加载自动类型的服务；用户最大连接数：可以限制客户端连续服务的次数，防止客户端不正常的频繁调用 webservice，给 EKP 系统的运行造成压力；服务最大运行时长：设置服务的运行时间限制，超时的服务会在超时模块中显示；用户设置：设置可以此 WebService 的用户帐号。服务端可以对客户端的信息进行验证，包括用户口令、IP 地址等；消息日志：在 Log4j 日志文件 Landray.msg.log 中Soap 消息以供调试，运行模式下请关闭此项，重启服务后生效。3.3运行日志WebService 的执行情况，为审计分析服务提供依据。的信息包括服务名称、服务标识、用户、客户端 IP 地

12、址、服务启动时间、服务结束时间，执行结果和错误信息等；可以根据这些信息搜索日志；也可以运行配置信息中对指定的 WebService 开启 Soap消息功能，服务端完整的入站消息和出站消息内容。执行结果的分类：1、 成功：WebService 正常被执行；2、 服务异常：WebService 执行过程中发生异常，此时系统会在日志中异常堆栈的信息，同时把错误提示信息和异常堆栈返回给客户端；3、用户：客户端提供的登录名或错误，会被；4、5、IP 地址：客户端机器的 IP 地址未被允许此 WebService；超限：用户调用服务的频率超过“用户最大连接次数”的限制，会被。搜索：可以通过服务名称、服务启

13、动和结束时间、执行结果等搜索运行日志。3.4超时显示所有运行时间超过服务最大运行时长设定的服务。服务最大运行时长在WebService 的运行配置信息中设置。3.5 用户帐号设置设置 WebService 用户帐号信息。包括用户名、可的 WebService、可以使用的客户端 IP 等。用户名：供外部系统使用的用户名称，作为显示和外部系统活动信息的标识；登录 ID：外部系统WebService 的凭据；可的 WEB 服务：用户可以的 WebService，一个用户帐号可以多个 WebService，一个 WebService 也可以被多个用户帐号；可使用的客户端 IP：限制可以WebServi

14、ce 的客户端机器，默认为空时不限制客户端 IP。多个 IP 地址之间用“,” 或者“;” 分隔， 如： 7,2。IP 地址的格式为 a.b.c.d 或者 a.b.c.*或者 a.b.*.*，其中*表示 0-255之间的任意数值，如：192.168.5.*, 10.1.*.*。3.6运行日志备份支持定期自动转移日志到备份表中，并且可以定期日志备份表中的数据。3.7辅助功能生成客户端代码：自动生成 WebService 的客户端 JAVA 代码和服务接口存根，并提供打包；查看 Wsdl：显示完整 Wsdl 文本，供客户端开发和测试时使用。当 WebService 正常启动后，可以查看到完整的 W

15、sdl 文本。第四章 WebService 数据接口由于 WebService 协议是采用 XML 文本格式来交换数据，因此需要将文本信息转换成系统可以识别的数据。为了方便开发开发 WebService 服务端程序，WebService2 组件提供 了组 织 架 构 转 换 和 附 件 保存 等 常 用 接 口 ， 这 些 接 口 位 于com.landray.kmss.sys.webservice2.erfa包中。4.1 组织架构接口4.1.1接口定义com.landray.kmss.sys.webservice2.erfa.ISysWsService4.1.2功能描述将客户端发送的 JSo

16、n 格式的组织架构数据转换为 EKP 系统的组织架构对象SysElement，供 EKP 系统的 WebService 使用。4.1.3调用方式使用 Spring 的 Set 方式注入“sysWsService”后即可调用此接口，如下所示：/*流程主文档Form*/public class KmRevieramterForm / 流程发起人private String docCreator;public String getDocCreator() return docCreator;public void setDocCreator(String docCreator) this.docCr

17、eator = docCreator;/*启动流程4.1.4数据格式客户端必须按如下格式发送组织架构的数据到 EKP 服务端：单值的格式为类型: 值，多值的格式为类型 1: 值 1 ,类型 2: 值 2.。支持的类型有主键（Id）、（No、DeptNo、tNo、GroupNo）、登录名（LoginName）、关键字（Keyword）、LDAP的 DN 值（LdapDN），其中表示群组。表示个人，Dept 表示机构/部门，t 表示岗位，Group4.1.5接口方法方法名参 数返回值描 述findSysElementjsonObjStr（Json 字符串）组 织 架 构 对 象SysElement

18、根据 JSON 对象字串查找单个组织架构findSysListjsonArrStr（Json 字符串）组织架构对象链表（ List）根据 JSON 数组字串查找多个组织架构*/public class KmReviewWebservierviceImp implements IKmReviewWebserviervice / 注入组织架构数据接口服务private ISysWsServiysWsService;public void setSysWsService(ISysWsServiysWsService) this.sysWsService = sysWsService;public S

19、tring addReview(KmRevieramterForm webForm) throws Exception / 调用接口获取流程发起人SysElement creator = sysWsService.findSysElement (webForm.getDocCreator();4.2 附件接口4.2.1接口定义com.landray.kmss.sys.webservice2.erfa.ISysWsAttService4.2.2功能描述将客户端发送的附件内容保 EKP 系统里，并与主文档关联。4.2.3调用方式使用 Spring 的 Set 方式注入“sysWsAttServic

20、e”后即可调用此接口，如下所示：/*流程主文档Form*/public class KmRevieramterForm / 附件内容列表privaistaentForm attaentForms = newArrayListaentForm();public ListaentForm getaentForms() return attaentForms;public void setaentForms(ListaentForm attaentForms) this.attaentForms = attaentForms;/*启动流程*/public class KmReviewWebservi

21、erviceImp implements IKmReviewWebserviervice / 注入附件数据接口服务private ISysWsAttServiysWsAttService;4.2.4附件对象(AttaentForm)附件对象封装了单个附件的信息，包括附件的文件内容。客户端通过传递附件对象来上 传 附 件 。 附 件 对 象 的 类 定 义 在 com.landray.kmss.sys.webservice2.forms.AttaentForm。类的参数定义如下：客户端可以使用 MTOM 编码（二进制编码）和标准文本编码（BASE64 编码）两种方式传输附件内容，详见第六章“We

22、bService 客户端开发”第 5 节。属性名类 型缺省值描 述fdKey字符串（String）fdAttaent附件的关键字，本 模 式 下 为 fdAtta ent，表单模式下为附件控件的 idfdFileName字符串（String）无附件文件名fdAttaent字节数组（byte）无附件内容，格式为字节编码public void setSysWsAttService(ISysWsAttServiysWsAttService) this.sysWsAttService = sysWsAttService;public String addReview(KmRevieramterForm

23、 webForm) throws Exception / 附件内容列表ListaentForm attForms = webForm.getaentForms();/ 校验附件大小sysWsAttService.validateAttSize(attForms);String mId = kmReviewMainService.add(form, reqontext); String m Name = form.getMClass().getName();/ 保存附件sysWsAttServiave(attForms, mId, mName);4.2.5接口方法方法名参 数参数说明返回值描 述

24、saveattForms附 件 链 表（Lista entForm）附件的数据库主键保存多个附件mId主文档 IDmName主文档的 m类名saveattForm附件AttaentForm附件的数据库主键保存单个附件mId主文档 IDmName主文档的 m类名validateAtt SizeattForms附 件 链 表（Lista entForm）无校验附件的大小，包括单个附件的长度和文档所有附件的长度，默认为系统的附件最大长度配置。第五章 WebService 服务端开发5.1 开发和部署流程在中开发和部署 WebService 的过程如下：1、 编写一个 Spring Bean 实现业务

25、逻辑；2、 在 WebService 扩展中定义 WebService 的基础信息；3、 在系统管理模块中点击导入的服务信息。WebService 成功导入后会被自动启动，无需重启 EKP 即可供外部。5.2 开发 Spring Bean1、 SpringBean的服务接口必须继承com.landray.kmss.sys.webservice2.erfa.ISysWebservice，同时在接口上使用WebService 注解将其标识为 WebService 接口。如下所示：2、 编写服务实现类，无特殊要求，如下所示：3、添加 spring bean 配置，无特殊要求，如下所示：public

26、clasrveyService implements ISurveyService private String excludeName;privateleastPonit;public SurveyResult vote(String username,po) WebServicepublicerface ISurveyService extends ISysWebservice public SurveyResult vote(String username,po);5.3 实现扩展在功能模块中添加 WebService 的扩展配置，实现 Web 服务的扩展点，如下所示：serviceNa

27、me：Web 服务的名称，如：启动Web 服务，此项必填且唯一；流程、投票等，用于标识一个serviceClass ： Web 服 务 的 接 口 类 名 ， 包 含 类 路 径 ， 如 ：com.landray.kmss.sys.news.service.ISysNewsMainService，此项必填且唯一；serviceBean ： Web 服务实现类在 spring 中的 ID ， 此类必须实现com.landray.kmss.sys.webservice2.erfa.ISysWebservice 接口，必填项；serviceDoc： 帮助文档的根路径，内容包括如何调用 Web 服务以

28、及各项参数说明等，文件类型为 HTML 或者 JSP 格式，比如：/ekp/sys/news/help/WsReadme.html，必填项。5.4导入并发布在 EKP 系统中的 WebService2 模块（/sys/webservice2.index）- 模块设置，或者系统管理模块 - 参数配置 - WEB 服务管理中选择“导入 WEB 服务”。当出现导入成功的提示后，在 WebService2 模块 - 系统服务中，可以看到服务已被更新并发布（启动状态），这时 WebService 已经可以被外部系统了。第六章 WebService 客户端开发6.1 JAVA 客户端系统可以自动生成 We

29、bService 客户端的 JAVA 代码。在 WebService2 模块服务 - WebService 列表（/sys/webservice2.index）- 系统- 查看页面，点击“Java 客户端”。客户端代码压缩包的内容如下：Com 目录：服务接口的客户端接口；AddSoapHeader.java：封装了 Soap 消息头，在 WebService 服务端要求验证的模式下提供客户端认证信息。Cperties：配置文件，包括了 WebService 的地址、用户登录 ID、等信息，其中是 MD5 密文。WebServiceCnt.java：WebService 客户端的主类，负责调用

30、Webservice。WebServiceConfig.java：负责配置文件。6.2.NET 客户端1、 生成客户端类2、 准备 soapheader 类public class AuthHeader : SoapHeaderprivate string userName = string.Empty; private string passWord = string.Empty; public AuthHeader()this.NamespaceInitialize();public AuthHeader(string userName, string passWord)this.user

31、Name = userName; this.passWord = passWord;XmlNamespaceDeclarationspublic XmlSerializerNamespaxmlns; private void NamespaceInitialize()xmlns = new XmlSerializerNamespa();wsdl/nologo /n:Landray.EKP.Cnt3、 建立客户端类和 soapheader 直接关系，类增加如下属性：方法增加如下属性：4、 调用服务6.3 Domino 客户端建议采用 axis 方式调用 webservice。开发步骤如下：1、

32、到axis1.42、 解压缩，并用命令行到 axis 中 lib 文件夹下执行命令，生成客户端存根 java -classpathmons-logging-1.0.mons-discovery-0.2.jar;jaxrpc.jar;wsdl4j-1.5.1ISurveyServiervice cnt = new ISurveyServiervice();cnt.AuthHeaderValue = new AuthHeader(); cnt.AuthHeaderValue.UserName = admin;cnt.AuthHeaderValue.PassWord = Util.md5(1234)

33、;surveyResult result = cnt.vote(test, 5);SoapHeaderAttribute(authHeaderValue)public AuthHeader authHeaderValue = new AuthHeader();xmlns.Add(tns, );XmlElement(Namespace = ,ElementName = user)public string UserNameget return userName; set userName = value; XmlElement(Namespace = ,ElementName = passwor

34、d)public string PassWordget return passWord; set passWord = value; .jar;saaj.jar;activation.jar;.jar.apache.axis.wsdl.WSDL2Java-ocnt3、 将 lib 中 jar 包放入 domino 服务器中4、 新建 JS 库，将存根按照原有包路径放入 JS 库中5、 新建 JAVA，引入创建的 JS 库，并采用如下代码调用 WS：注：wsdl 地址，需要根据情况更改。String endpoURL =;Serviervice = new Service();Call call

35、 = (Call) service.createCall();call.setEndpoAddreew .URL(endpoURL); call.setSOAPActionURI(/+ RequestSOAPHeader);/ 设置操作的名称call.setOperationName(new QName(ISurveyService, vote);/ 设置soap头信息SOAPHeaderElement soapHeaderElement = new SOAPHeaderElement(/,tns:RequestSOAPHeader); soapHeaderElement.setNamespa

36、ceURI(/);soapHeaderElement.addChildElement(tns:userName).setValue(admin); soapHeaderElement.addChildElement(tns:password).setValue(password);soapHeaderElement.addChildElement(tns:serviceName).setValue(投票调查);call.addHeader(soapHeaderElement);call.setReturnType(new QName(urn:SurveyResult, ns1:voteResp

37、onse),SurveyResult.class);/设置参数类型call.addParameter(arg0, XMLType.XSD_STRING, ParameterMode.IN); call.addParameter(arg1, XMLType.XSD_, ParameterMode.IN);/ 执行调用SurveyResult rs = (SurveyResult) call.invoke(new Object new String(zhangsan), neweger(88) );6.4认证在 WebService 服务端要求验证的模式（关闭）下，客户端需要添加 Soap 消息头

38、以提供认证信息。消息头的格式如下所示：tns:RequestSOAPHeader：一个 SOAP 请求的消息头，xmlns:tns 指定命名空间；tns: user：WebService 用户的登录 ID；tns:password：对应 WebService 用户帐号的，要求使用 MD5 加密。，则客户端不需要添加 Soap 消如果 WebService 服务端不要求验证，即开启了息头。6.5 附件上传附件接口目前支持 MTOM 编码（二进制编码）和标准文本编码（BASE64 编码）两种方式传输附件内容。标准文本编码为默认格式。6.5.1选择编码格式而对于纯文本的数据，建议使用标准编码。对较大

39、的二进制负载的传输，如上传文档和等，建议使用 MTOM 编码。因为标准文本编码使用 Base64 对二进制数据进行编码，这要求每三个字节对应符，从而使得数据的大小增加三分之一。MTOM 能够以原始字节形式传输二进制数据，这会缩短编码 /时间并生成较小的消息。MTOM 编码主要针对二进制数据有优势。要使用 MTOM 编码处理消息，需要开启 MTOM 功能，请参考 JAVA 客户端代码。6.5.2约束不建议使用 WebService 协议传输大附件（附件总长度大于 100M）。.6.5.3参考代码客户端上传附件需要传递附件对象，附件对象的定义请参考第四章“WebService 数据接口-附件对象”

40、。参考代码如下所示：6.6 流程表单数据流程表单数据是采用 Json 格式传输，而流程表单原始数据的格式为 xml，定义在km_review_main 表中的 extend_data_xml 字段里。因此开发需要提取出流程表单中输入项的控件 ID 和控件值，组装成 Json 格式。其中明细表是按列来设置，格式为明细表 id.列 id:列值 1,列值 2,列值 3.，每列单独组一个集合。参考代码如下：/*创建附件对象列表*/privaistaentForm createAllAtts() throws Exception ListaentForm attForms = new ArrayList

41、aentForm(); String fileName = 采购订单说明书1.doc;AttaentForm attForm01 = createAtt(fileName); fileName = 采购订单说明书2.doc;AttaentForm attForm02 = createAtt(fileName);attForms.add(attForm01); attForms.add(attForm02); return attForms;/*创建附件对象*/private AttaentForm createAtt(String fileName) throws Exception Atta

42、entForm attForm = new AttaentForm(); attForm.setFdFileName(fileName);/ 设置附件关键字，表单模式下为附件控件的idattForm.setFdKey(fd_2eddbf161a3268);byte data = file2bytes(C: + fileName); attForm.setFdAttaent(data);return attForm;6.7 流程参数流程参数是采用 JSon 格式传输，格式为auditNode:意见, futureNodeId:节点名, changeNodeHandlers:节点名 1：用户 ID

43、1;户 ID2.。用户 ID2., 节点名 2：用户 ID1;用6.7.1参数定义6.7.2参考代码/ 流程参数String floram = auditNode:请审核, futureNodeId:N7, changeNodeHandlers:N7:1183b0b84ee4f581bba001c47a78b2d9;131d019fbac 792eab0f0a684c8a8d0ec;form.setFloram(floram);序号属性名类 型缺省值描 述1auditNode字符串（Json）无意见2futureNodeId字符串（Json）无流向下一节点的 ID，需要人工决策时设置此参数3changeNodeHandler