JAVA服务开发指南.doc

XXXX 塔里木油田SOA标准过程编制及平台研发Web服务提供与消费(Java)开发指南版本：V1.0中国石油塔里木油田公司2011年3月JAVA服务开发指南文件版本历史文件版本修订日期修订人审核人批准人修订说明0.12011-3-24于鹏创建文档0.22011-3-25杜少华加入cxf客户端开发说明和demo源代码附件。1.02011-3-27杜少华复杂对象参数和反向工程目 录1概述11.1文档目的11.2文档内容12相关资料12.1WSDL12.2WS-Security22.3SOAP23CXF开发服务33.1CXF介绍33.2准备工作33.3WEB服务开发43.4服务发布验证63.5支持WS-Security63.6复杂参数83.7CXF开发webservice客户端83.7.1wsdl2java83.7.2客户端加入安全认证83.7.3客户端运行93.7.4源码附件93.8POJO改造成CXF服务94ePlanet开发服务104.1ePlanet介绍104.2准备工作104.3WEB服务开发114.3.1管理系统中定义服务114.3.2Service代码实现114.3.3服务配置144.4服务发布验证154.5ePlanet插件开发服务客户端154.6Service Demo154.7安全服务的提供与消费164.7.1提供164.7.2消费16Copyright 中国石油塔里木油田公司 III 1 概述1.1 文档目的本文档对JAVA开发WEB服务进行说明，用以指导WEB服务的开发工作。相关人员通过阅读本文档，可获得足够的信息，完成JAVA的WEB服务开发。使用对象：有Java开发基础，能配Java开发环境，熟悉eclipse开发，能在tomcat上部署应用程序的程序员。1.2 文档内容主要内容包括： 相关资料：介绍WEB服务开发领域的相关资料。 CXF开发服务：详细讲述CXF开发WEB服务的过程，用以指导实际的服务开发。 ePlanet开发服务：详细讲述CXF开发WEB服务的过程，用以指导实际的服务开发。2 相关资料2.1 WSDLWSDL（网络服务描述语言，Web Services Description Language）是一门基于XML的语言，用于描述Web Services以及如何对它们进行访问。在Web服务的世界里，应用程序基本上由远程的、XML驱动的组件构成，这些组件采用不同的语言编写，再采用标准的远程激活协议通过Web连接。服务提供者定义所提供服务需要用到的数据格式。同样的，当你在以上应用模式下接受Web服务时，你也需要采取措施保证你的客户程序采用了服务器期望的数据格式。这正是WSDL（Web服务定义语言）大显身手的地方。2.2 WS-Security随着 Web 服务由技术概念到实践应用的不断发展，种种迹象表明Web服务将是未来应用架构的一个极为重要的模式。当 Web 服务用于试验计划和大规模生产时，拥有一种松散耦合的、与语言和平台无关的、在组织内跨企业、跨因特网链接应用程序的方法的好处正变得愈发明显。而当 Web 服务日益成为主流时，要解决的关键问题便是安全性。WS-Security应运而生。WS-Security(Web服务安全) 是一种提供在Web服务上应用安全的方法的网络传输协议。2004年4月19日，OASIS组织发布了WS-Security标准的1.0版本。 2006年2月17日，发布了1.1版本。WS-Security是最初IBM,微软,VeriSign和Forum Systems开发的，现在协议由Oasis-Open下的一个委员会开发，官方名称为WSS。协议包含了关于如何在Web服务消息上保证完整性和机密性的规约。WSS协议包括SAML（安全断言标记语言）、Kerberos和认证证书格式（如X.509）的使用的详细信息。WS-Security描述了如何将签名和加密头加入SOAP消息。除此以外，还描述了如何在消息中加入安全令牌，包括二进制安全令牌，如X.509认证证书和Kerberos门票（ticket）。WS-Security将安全特性放入一个SOAP消息的消息头中，在应用层处理。这样协议保证了端到端的安全。2.3 SOAP简单对象访问协议（SOAP）是一种轻量的、简单的、基于 XML 的协议，它被设计成在 WEB 上交换结构化的和固化的信息。 SOAP 可以和现存的许多因特网协议和格式结合使用，包括超文本传输协议（ HTTP），简单邮件传输协议（SMTP），多用途网际邮件扩充协议（MIME）。它还支持从消息系统到远程过程调用（RPC）等大量的应用程序。当今有很多流行的开源WEB服务框架，比如，Axis2，Celtix，XFire，CXF等。本文主要介绍CXF和ePlanet开发和消费服务。3 CXF开发服务3.1 CXF介绍Apache CXF是由Celtix和XFire两大框架重组演化而来，兼具了二者的特性。Apache CXF 是一个开源的 Services 框架，CXF 帮助您利用其提供的 API 来构建和开发 Services ，如 JAX-WS 。这些 Services 可以支持多种协议，比如：SOAP、XML/HTTP、RESTful HTTP 或者 CORBA ，并且可以在多种传输协议上运行，比如：HTTP、JMS 或者 JBI，CXF 大大简化了 Services 的创建，同时它继承了 XFire 传统，一样可以天然地和 Spring 进行无缝集成。参考文档：/docs/index.html （官方文档永远是最好的老师）参考教程：/developerworks/cn/education/java/j-cxf/index.html3.2 准备工作服务开发IDE：eclipse, 集成tomcatplugin.CXF是一个开源的WEB服务框架，可以和Spring完美集成。从CXF项目主页：上下载CXF二进制版本包apache-cxf-2.3.3.zip至本地。解压缩后便得到开发CXF服务所需要的依赖包和一些Sample和其API文档。CXF服务端和客户端的依赖包在解压后的apache-cxf-2.3.3lib下。在Eclipse中建立一个命名为Test的Dynamic Web project，添加CXF/lib下所有jar到项目的lib中。在Web.xml中添加CXFServlet，为用户提供访问入口。Xml代码cxforg.apache.cxf.transport.servlet.CXFServlet1cxf/services/*由于CXF与Spring的集成非常友好，所以在Web.xml中添加Spring的配置Xml代码contextConfigLocationWEB-INF/applicationContext.xmlorg.springframework.web.context.ContextLoaderListener在WEB-INF下建立applicationContext.xml内容如下Xml代码3.3 WEB服务开发方式一：先开发服务端代码，正确发布后得到wsdl.方式二：先按规范设计出wsdl，用CXF工具wsdl生成server端框架代码。我们以HelloWorld为例，讲解用CXF方式一开发服务的过程。CXF annotation不做详细介绍，请自学。Wsdl2java生成的服务端代码和客户端代码是学习annotation的好教材，它完全遵循CXF annotation。首先，建立服务接口。package com.rf.ws; import javax.jws.WebService; WebService public interface HelloWorld String sayHello(String msg); 其次，实现接口方法package com.rf.ws; import javax.jws.WebService; WebService(endpointInterface=com.rf.ws.HelloWorld) public class HelloWorldImpl implements HelloWorld public String sayHello(String msg) System.out.println(客户端的传值为: +msg); return 你好！ +msg; 至此，便完成了一个CXF服务的开发工作。Wsdl地址说明：http:/yourServerIP:port/yourAppContextName/(serviceAddressInTheContextConfig)?wsdl如：http:/localhost:9080/cxf-demo/ws/helloWorld?wsdl3.4 服务发布验证服务开发完成，即可启动tomcat，完成服务的发布。我们采用SoapUI软件进行服务发布后的验证工作。应用启动后，打开SoapUI软件，创建项目，WSDL地址为http:/localhost:8080/Test/services/helloWorld?wsdl若返回正常，便证明服务发布成功。3.5 支持WS-SecurityWS-Security是WEB服务的安全规范。CXF采用Apache WSS4J对其实现。这里，我们采用UserToken方式完成WS的加密工作。CXF采用了拦截器的方式对WS进行加密。首先在上文项目的applicationContext.xml加入拦截器，最终代码如下： 其中，名称为WSS4JInInterceptor的bean便是所配置的加密拦截器。passwordCallbackClass的值便是验证用户权限的回调类。以下为ServerPasswordCallback类代码package com.rf.ws; import org.apache.ws.security.WSPasswordCallback; import java.io.IOException;import javax.security.auth.callback.Callback; import javax.security.auth.callback.CallbackHandler; import javax.security.auth.callback.UnsupportedCallbackException; public class ServerPasswordCallback implements CallbackHandler public void handle(Callback callbacks) throws IOException, UnsupportedCallbackException WSPasswordCallback pc = (WSPasswordCallback) callbacks0; if (pc.getIdentifier().equals(admin) if (!pc.getPassword().equals(123) throw new SecurityException(wrong password); else throw new SecurityException(wrong username); 该类的handle方法对服务调用进行拦截，判断其用户名和密码（admin，123）是否正确。若正确，服务成功调用，否则返回异常值。至此，便完成了CXF服务发布的安全认证工作。3.6 复杂参数服务的输入输出参数可以是复杂类型。实例（附件中）：http:/localhost:9080/cxf-demo/ws/userSample?wsdl实例是一个用户管理的服务的CRUD的示例，使用User对象做参数。3.7 CXF开发webservice客户端3.7.1 wsdl2java 生成客户端代码（反向工程）：F:softwaredevapache-cxfapache-cxf-2.3.3binwsdl2java -d E:work-tempcxfclient -client http:/localhost:9080/cxf-demo/ws/helloWorld?wsdl 把输出目录下的代码导入到客户端项目的src中， 并可按要求重构HelloWorld_HelloWorldImplPort_Client.java.(比如附件中，生成的HelloWorld_HelloWorldImplPort_Client.java类名已经改为HelloWorldImplPort_Client.java)顺便说一下，已知wsdl时的服务端代码生成指令：F:softwaredevapache-cxfapache-cxf-2.3.3binwsdl2java -d E:work-tempcxfserver -server http:/localhost:9080/cxf-demo/ws/userSample?wsdl3.7.2 客户端加入安全认证如果服务端是需要认证的安全服务，则在HelloWorldImplPort_Client.java,加入security,/ws-security Map outProp = new HashMap(); outProp.put(WSHandlerConstants.ACTION, WSHandlerConstants.USERNAME_TOKEN); outProp.put(WSHandlerConstants.USER, admin); outProp.put(WSHandlerConstants.PASSWORD_TYPE, WSConstants.PW_TEXT); outProp.put(WSHandlerConstants.PW_CALLBACK_CLASS, UserTokenClientCallBack.class.getName(); org.apache.cxf.endpoint.Client client = ClientProxy.getClient(port); Endpoint demoEndpoint = client.getEndpoint(); demoEndpoint.getOutInterceptors().add(new WSS4JOutInterceptor(outProp); 3.7.3 客户端运行运行HelloWorldImplPort_Client，调用服务。3.7.4 源码附件源代码： 其中是两个项目的代码，一个服务端，一个是客户端，直接导入Eclipse IDE中即可使用，要求Eclipse中集成有tomcatplugin。附件源码的包路径与文档中的不尽相同，以代码为准。Project的lib，自行从apache-cxf-2.3.3lib中拷贝并引入到项目。附件中的服务地址：http:/localhost:9080/cxf-demo/ws/helloWorld?wsdlhttp:/localhost:9080/cxf-demo/ws/userSample?wsdl3.8 POJO改造成CXF服务前提：项目使用spring框架 把普通java业务实现类改造成CXF服务，步骤与方式一开发服务基本是一样的： 为原业务实现类编写一个服务接口类，只提取原类中需要暴露给服务消费方的方法。 接口类加标注（annotation）WebService 原实现类中加标注（annotation）WebService(endpointInterface=，如：WebService(endpointInterface = com.rf.ws.cxf.server.hello.HelloWorld)。 配置spring的applicationContext.xml文件。如果有安全控制，需要配置。 部署、重启应用服务器。 验证服务是否成功。4 ePlanet开发服务前提：使用ePlanet-DreamBuilder-Java开发平台去开发应用系统。参看DreamBuilder开发手册第7节。4.1 ePlanet介绍ePlanet是基于SOA的企业级开发平台。平台自身提供了优秀的WEB服务注册，发布，调用功能。利用该平台，可以很方便的发布基于标准的WS服务。4.2 准备工作首先，启动ePlanet平台，本文档采用比较稳定的V4版本。通过所授权的账户登录系统界面。4.3 WEB服务开发4.3.1 管理系统中定义服务服务的名称应该与spring配置的bean的名称一样4.3.2 Service代码实现 Service层根据概要设计中的包前缀定义，创建一个服务类，继承BaseService，如下所示：1. import pc.jcdp.soa.srvMng.BaseService;2. public class LoginAndMenuTreeSrv extends BaseService3.4. public ISrvMsg updateUserLogin(ISrvMsg reqDTO) throws Exception 5. /服务方法的实例例子6.7. /示例说明：从参数Request ISrvMsg中取出各传入节点值8. String loginId = reqDTO.getValue(loginId);9. String userPwd = reqDTO.getValue(userPwd);10. String loginIp = reqDTO.getValue(loginIp);11. 12. UserUtil userUtil = new UserUtil();13. UserToken user = userUtil.authUser(loginId, userPwd,loginIp);14. user.setCharset(reqDTO.getValue(charset);15. 16. /利用传入参数的基本信息（namespace等）构造返回soap消息的基本信息17. responseDTO responseDTO = SrvMsgUtil.createResponseMsg(reqDTO);18. /示例说明：在返回Response ISrvMsg中设定各返回节点值19. responseDTO.setValue(userToken, user);20. responseDTO.setValue(funCodes, RoleUtil.getFunctionCodesByRoleIds(user.getRoleIds();21. 22. Map userProfile = userUtil.queryUserProfile(user.getUserId();23. if(userProfile!=null)24. responseDTO.setValue(userProfile, userProfile);25. 26. 27. return responseDTO; 28. 29.说明：从参数Request ISrvMsg中取出各传入节点值，在返回Response ISrvMsg中设定各返回节点值。2 服务类中操作的层次划分。一个复杂的Operation通常由Service层、Business层、DAO层以及POJO层实现，通常我们把Service层、Business层、DAO层合并到Service层。 Business层此层完成业务逻辑。 DAO层原则上不建议创建个性化的DAO类，通过框架提供的IPureJdbcDao和IBaseDao完成数据访问功能。建议：通过IPureJdbcDao直接完成增、删、改操作（参考基础组件群中的IPureJdbcDao说明），如果通过JDBC实现困难也可参照下面的步骤采用ORM方式。1.DAO实例的获取 在Service层或Business层获取baseDao1. import pc.jcdp.cfg.BeanFactory;2. import pc.jcdp.icg.dao. IPureJdbcDao;3. import pc.jcdp.dao.IBaseDao;4.5. private IPureJdbcDao jdbcDao = BeanFactory.getPureJdbcDAO();6. private IBaseDao baseDao = BeanFactory.getBaseDao(); 创建实体时框架自动设置创建时间字段baseDao.saveWithSysDate(entity); 更新实体时框架自动设置更新时间字段baseDao.updateWithSysDate(entity);2.增删改的实现利用IBaseDao提供的方法实现。更新某个业务实体时，可利用JavaBeanUtils提供的updatePojoFields方法根据MVC的SOAP请求消息更新POJO的指定Fields，从而避免逐个设置Field的操作，具体示例如下：1. import pc.jcdp.util.JavaBeanUtils;2.3. public ISrvMsg updateService(ISrvMsg reqDTO) throws Exception 4. String serviceId = reqDTO.getValue(serviceId);5. /*String client = reqDTO.getValue(client);6. String clientRef = reqDTO.getValue(clientRef);7. String fieldName = reqDTO.getValue(fieldName);8. String wellName = reqDTO.getValue(wellName);*/9. ServiceBussiness bussiness = new ServiceBussiness();10. String fields = serviceId,client,clientRef,fieldName,wellName;11. LogService service = bussiness.getService(serviceId);12. /*service.setClient(client);13. service.setClientRef(clientRef);14. service.setFieldName(fieldName);15. service.setWellName(wellName);*/16. JavaBeanUtils.updatePojoFields(service, reqDTO, fields);17. bussiness.updateService(service);18. ISrvMsg msg = SrvMsgUtil.createResponseMsg(reqDTO);19.20. return msg;21. 3.单表查询利用IBaseDao提供的方法实现。1. public Object get(Class pojoClass,Serializable id) throws DataAccessException; 2. public List queryByHql(String hql, Object. values)；4.多表查询利用IJdbcDao提供的方法实现。5.与ECTable的结合获取ECTable的分页参数PageModel model = QueryUtil.getPageModelByECTable(reqMsg);返回查询结果必须设置总条数，如下所示：msg.setValue(totalRows, pm.getTotalRow();6.返回结果Map中key的设置JDBC查询后，默认按Hibernate规则对库表字段名转换后作为Map的key，如果需要直接用库表字段名作为Map的key，示例如下：PageModel model = new PageModel();model.setRowMapper(Record2ColMap.instance);List nodes = jdbcDao.queryRecordsBySQL(sql, model).getData(); POJO层pojo类由MyEclipse自动生成4.3.3 服务配置 IoC配置利用spring提供的IoC功能，将服务Bean注入容器，同时实现了声明性事务。 服务Bean的配置根据概要设计中约定的配置文件名配置服务，如下所示：1. 3. 4. 5. 6. 事务的配置在app