概述
BDF中WebService模块采用Spring WS2实现,采用Contract First开发模式,基于WebService的Username token profile v1.0标准认证方 式对客户端调用进行合法性认证,同时提供基于标准Spring Security的WebService权限管理机制,可以与BDF安全模块无缝接合,实现以角色为核心的WebService权限控制。同时在BDF的 WebService实现当中还提供WebService调用日志数据库记录功能,可以记录每次WebService的调用人、调用的目标 WebService的Endpoint名称(完整的类名以及方法名)、调用客户端IP地址、调用开始时间、调用结束时间、有没有调用成功以及调用失败时 的错误信息,通过日志记录可以方便管理人员对WebService进行维护与统计。
对于WebService的编写我们引入JAXB2,实 现XML与Java对象之前相互转换,这样在编写WebService的Endpoint时不再解析复杂的XML,而直接操作Java对象即可,让 JAXB2负责将XML转换成Java对象,或将响应的Java对象转换成XML传输到客户端。
客户端部分我们提供一个名为 WebServiceClient类,可以快速实现目标WebService调用。客户端当中,你可以方便的为当前SOAP消息添加Username Token(可以选择密码加密或不加密),快速将XML的DOM对象或XML字符串快速转换成SOAP消息发送到WebService服务端。同时在 WebServiceClient类我们也提供了JAXB2的支持,这样无论是发送SOAP消息或接收WebService的响应消息,都可以使用 JAXB2将XML转成Java对象,或将Java对象转成XML发送的WebService服务端。
配置
与 使用BDF其它模块一样,首先我们需要下载BDF的发行包,解压后找到其中的com.bstek.bdf.webservice-[version]目 录,将该目录下bin目录中的com.bstek.bdf.webservice-[version].jar文件复制到目标工程的lib目录下,同时还 需要将BDF WebService模块所依赖的第三方jar复制到目标工程的lib下。之前说过,BDF所有模块都依赖Core模块,所以还需要配置好Core模块功 能,详情查看公共模块说明。
BDF 的WebService模块也需要有数据库支持,目录主要是一张用于记录WebService调用日志的数据库表。打开BDF发行包下 com.bstek.bdf.webservice-[version]/dbschema目录,找到与当前工程吻合的SQL文件,创建BDF模块所需要 的数据库表。同时如果我们需要覆盖ws模块当中的默认属性,您可在dorado7项目的dorado-home目录下bdf.properties文件 中,添加需要覆盖的属性条目即可。目前可用的属性如下表所示。
属性名称
描述
bdf.webservice.useSecurity |
客户端在调用当前BDF的WebService模块中的webservice时是否需要验证,该属性默认值为true,表示需要验证,这样后面的两个属性才会起作用,如果设置为false,则不需要验证。 |
bdf.webservice.userService |
WebService 在验证客户端用户名、密码合法性时采用的UserService实现类,默认使用的是BDF公共模块里的UserService对象,同样也是一个定义在 Spring当中名为bdf.userService的Spring的Bean,如果您要自定义这个userService,那么需要实现Spring Security当中的 org.springframework.security.core.userdetails.UserDetailsService接口,并将其配置 到Spring当中,这里设置为这个Bean的ID即可。该属性仅在bdf.webservice.useSecurity属性值为true是起作用。 |
bdf.webservice.webServiceSecurityMetadataSource |
在对WebService进行权限验证时采用的验证资源,默认这个比较简单,没有任何资源可供验证,也就是说不对WebService资源进行权限方面控制,只要认证通过都可以访问。 |
bdf.webservice.accessDecisionManager |
在对WebService进行权限验证时采用的AccessDecisionManager类,默认所以WebService都不进行权限控制,只要认证通过都可以访问。 |
最后一步就是在目标工程的web.xml当中添加一些配置信息,具体配置信息如下:
<
servlet
>
<
servlet-name
>bdf-ws</
servlet-name
>
<
servlet-class
>org.springframework.ws.transport.http.MessageDispatcherServlet</
servlet-class
>
<
init-param
>
<
param-name
>transformWsdlLocations</
param-name
>
<
param-value
>true</
param-value
>
</
init-param
>
<
init-param
>
<
param-name
>contextConfigLocation</
param-name
>
<
param-value
></
param-value
>
</
init-param
>
<
load-on-startup
>1</
load-on-startup
>
</
servlet
>
<
servlet-mapping
>
<
servlet-name
>bdf-ws</
servlet-name
>
<
url-pattern
>/webservice/*</
url-pattern
>
</
servlet-mapping
>
|
可以看到,我们配置了一个Servlet,这个servlet是由Spring WS提供处理所有路径以webservice开头的请求,在BDF的webservice模块当中,我们提供了一个示例webservice,该示例WebService的WSDL地址就是http://localhost:8080/webservice/demo.wsdl,通过查看wsdl我们知道,这个webservice可以接收一个请求,根据请求中要获得的用户数量,返回对应数量的用户信息。
这个名为bdf-ws的servlet会拦截所有根URL为webservice的请求,这也就提醒我们在业务开发的过程当中不要使用这个名为webservice的URL。
配置完成之后,接下来就可以重启应用,在浏览器中打开http://localhost:8080/webservice/demo.wsdl查看这个演示用的WebService的WSDL信息,当然也可以使用SOAPUI之类的WebService客户端测试工具对这个示例WebService进行测试。
首选项配置
在 BDF默认实现当中,提供了对Webservice调用的日志记录功能,如果您采用BDF发布了若干个webservice,那么默认情况下,对于客户端 调用都会记录到bdf_webservice_logs表当中,记录的内容包括调用人、调用时间、请求的xml文件内容等。
在某些情况下,出于性能角度考虑,您可能不需要对webservice调用进行日志记录,那么我们唯一需要做的就是修改首选项目配置表,将其中名为“persistence_webservice_logs”的首选值改为N即可(默认为Y,表示对webservice调用进行日志记录。)
概述
我们这里要编写一个WebService的 Endpoint,它可以接收一个UserRequest对象,这个对象当中只包含一个userCount的参数,Endpoint接收到参数后,会产生 与userCount相同数量的User对象,最后将这个User对象的集合放在一个名为UserResponse的对象当中作为Endpoint的调用 响应发送给调用这个WebService的客户端。接下来我们先从编写WebService服务端开始,看看如何实现这个WebService示例。
WebService服务端开发
因 为在我们的WebService服务端当中引入了JAXB2,所以整个服务端Endpoint类编写变的简单,同时Spring-WS2.0支持将XSD 文档自动转换成WSDL,这样我们就不用直接编写复杂的WSDL,而只需要编写好XSD文档即可实现WSDL发布。一般来说,一个WebService的 编写是从定义WSDL开始的,对于我们这里来说,因为我们可以将XSD自动转换成WSDL,所以我们就是从编写简单的XSD开始。
关于XSD文档的语法规范,如果您不熟悉,可以从http://www.w3school.com.cn/schema/index.asp上面了解。
我们这里规定,所有的进站参数在定义XSD时要以Request结尾,比如我们这里的UserRequest;所有的出站参数要以Response结尾,比如我们这里的UserResponse。了解这些之后就可以定义们的XSD文档,具体内容如下:
<?xml version="1.0" encoding="UTF-8"?> <schema targetNamespace="http://www.bstek.com/ws/demo" elementFormDefault="qualified" xmlns="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://www.bstek.com/ws/demo"> <element name="UserResponse"> <complexType> <sequence> <element name="users" type="tns:User" maxOccurs="unbounded"></element> </sequence> </complexType> </element> <element name="UserRequest"> <complexType> <all> <element name="userCount" type="int"></element> </all> </complexType> </element> <complexType name="User"> <sequence> <element name="username" type="string"></element> <element name="birthday" type="date"></element> <element name="gender" type="boolean"></element> <element name="email" type="string"></element> <element name="dept" type="tns:Dept"></element> </sequence> </complexType> <complexType name="Dept"> <sequence> <element name="deptId" type="string"></element> <element name="deptName" type="string"></element> </sequence> </complexType> </schema>
XSD文档的编写是非常简单的,如果您使用的IDE是Eclipse,那么您可以直接使用Eclipse当中提供了XSD图形化编辑器来编写这个XSD文档。从文档内容中可以看到,我们定义消息的namespace为http://www.bstek.com/ws/demo,同时定义了一个名为UserRequest的Element为进站参数;一个名为UserResponse的Element为出站参数。
XSD文档编写完成之后,我们就可以利用Spring-WS提供的配置功能将XSD直接转换成我们需要的WSDL。
因为我们采用的是Spring-WS为基础实现WebService,所以一旦XSD文档编写完成我们就可以通过配置的方式将XSD转换成WSDL,新建一个Spring配置文件,在文件当中添加如下内容:
<?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:sws="http://www.springframework.org/schema/web-services" xmlns:context="http://www.springframework.org/schema/context" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd http://www.springframework.org/schema/web-services http://www.springframework.org/schema/web-services/web-services-2.0.xsd http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd"> <context:component-scan base-package="com.bstek.bdf.webservice.demo"></context:component-scan> <sws:dynamic-wsdl id="demo" portTypeName="UserResource" locationUri="/webservice/demo"> <sws:xsd location="classpath:com/bstek/bdf/webservice/demo/demo.xsd" /> </sws:dynamic-wsdl> </beans>
我们需要关注的就是这个配置文件当中以sws:dynamic-wsdl开头的配置片断,这里采用位于classpath下的一个xsd文档,发布成 WSDL的ID为demo,同时客户端调用这个WebService的地址我们定义为/webservice/demo。启用我们的应用,打开浏览器,可 以浏览到这个动态生成的名为demo的wsdl文档。如下图所示。
WSDL发布成功之后,接下来我们就需要动手来编写我们的WebService服务端的Endpoint,由这个EndPoint来接收客户端的调用请求。
Endpoint实际上是WebService真正的服务类,我们只需要按照之前发布的WSDL规则来编写即可,由它来接收客户端请求,同时将响应回写到 客户端当中。因为Spring提供了Endpoint的annotation,同时我们又添加了JAXB2支持,所以Endpoint类编写是非常简单 的。下面是我们编写的与之前发布的WSDL对应的Endpoint类源码:
package com.bstek.bdf.webservice.demo; import java.util.ArrayList; import java.util.Date; import java.util.List; import org.springframework.ws.server.endpoint.annotation.Endpoint; import org.springframework.ws.server.endpoint.annotation.PayloadRoot; import org.springframework.ws.server.endpoint.annotation.RequestPayload; import org.springframework.ws.server.endpoint.annotation.ResponsePayload; @Endpoint public class UserServiceEndpoint{ @PayloadRoot(namespace=" http://www.bstek.com/ws/demo",localPart="UserRequest") @ResponsePayload public UserResponse findUsers(@RequestPayload UserRequest request) throws Exception{ List<User> userList=new ArrayList<User>(); for(int i=0;i<request.getUserCount();i++){ User u=new User(); u.setBirthday(new Date()); u.setGender(true); u.setUsername("从WS中取到的User "+i); u.setEmail("bstek.user"+i+".bstek.com"); userList.add(u); } for(int i=0;i<100;i++){ Thread.sleep(50); } UserResponse res=new UserResponse(); res.setUsers(userList); return res; } }
可以看到,我们这里采用了四个annotation,在类上的@Endpoint标明我们将这个类发布成一个Endpoint服务 类,findUsers方法上有两个annotation:@PayloadRoot用于标明findUser可以授受的XML信息,这里取的是XML的 namespace为http://www.bstek.com/ws/demo, 同时XML的ROOT为UserRequest的信息;下面的@ResponsePayload标明findUsers方法有返回值,返回值需要回写给 Webservice调用客户端;参数中还有一个@RequestPayload的annotation,它表示从请求负载中取值作为参数,我们这里因为 采用了JAXB2,所以可以将负载的XML消息直接转换成一个名为UserRequest的Java对象。
从findUsers方法体中可以看到,其中都是针对Java对象的操作,是非常简单的。这是因为我们添加了JAXB2支持的原因,如果没有我们这里就只能操作复杂的XML了。
我们这里涉及到的需要使用JAXB2实现Java对象与XML相互转换的类有下面几个:
UserRequest
package com.bstek.bdf.webservice.demo; import javax.xml.bind.annotation.XmlAccessType; import javax.xml.bind.annotation.XmlAccessorType; import javax.xml.bind.annotation.XmlElement; import javax.xml.bind.annotation.XmlRootElement; @XmlRootElement(namespace="http://www.bstek.com/ws/demo",name="UserRequest") @XmlAccessorType(XmlAccessType.FIELD) public class UserRequest { @XmlElement(namespace=Constants.DEMO_NAMESPACE) private int userCount; public int getUserCount() { return userCount; } public void setUserCount(int userCount) { this.userCount = userCount; } } ? UserResponse package com.bstek.bdf.webservice.demo; import java.util.List; import javax.xml.bind.annotation.XmlAccessType; import javax.xml.bind.annotation.XmlAccessorType; import javax.xml.bind.annotation.XmlRootElement; @XmlRootElement @XmlAccessorType(XmlAccessType.FIELD) public class UserResponse { private List<User> users; public List<User> getUsers() { return users; } public void setUsers(List<User> users) { this.users = users; } }
User
package com.bstek.bdf.webservice.demo; import java.util.Date; import javax.xml.bind.annotation.XmlAccessType; import javax.xml.bind.annotation.XmlAccessorType; import javax.xml.bind.annotation.XmlRootElement; @XmlRootElement(name="User",namespace="http://www.bstek.com/ws/demo") @XmlAccessorType(XmlAccessType.FIELD) public class User { private String username; private Date birthday; private boolean gender; private String email; private Dept dept; public String getUsername() { return username; } public void setUsername(String username) { this.username = username; } public Date getBirthday() { return birthday; } public void setBirthday(Date birthday) { this.birthday = birthday; } public boolean isGender() { return gender; } public void setGender(boolean gender) { this.gender = gender; } public String getEmail() { return email; } public void setEmail(String email) { this.email = email; } public Dept getDept() { return dept; } public void setDept(Dept dept) { this.dept = dept; } @Override public String toString() { return "User [username=" + username + ", birthday=" + birthday + ", gender=" + gender + ", email=" + email + ", dept=" + dept + "]"; } }
可以看到,这三个类都是非常普通的POJO对象,它们都用到了@XmlRootElement、@XmlAccessorType,这两个annotation都是JAXB2提供,要了解详情请查看JAXB2相关文档。
到这里为止,我们的Endpoint编写就完成了,因为我们使用了Spring-WS提供的Endpoint的annotation,所以不需要在 Spring配置当中进行任何配置,唯一需要的就是添加一个context:component-seca即可,这样Spring会自动扫描位于 base-package属性指定包下所有的Endpoint类。
可以看到,这三个类都是非常普通的POJO对象,它们都用到了@XmlRootElement、@XmlAccessorType,这两个annotation都是JAXB2提供,要了解详情请查看JAXB2相关文档。
到 这里为止,我们的Endpoint编写就完成了,因为我们使用了Spring-WS提供的Endpoint的annotation,所以不需要在 Spring配置当中进行任何配置,唯一需要的就是添加一个context:component-seca即可,这样Spring会自动扫描位于 base-package属性指定包下所有的Endpoint类。
<context:component-scan base-package="com.bstek.bdf.webservice.demo"></context:component-scan>
WebService的服务端我们开发完成,接下来我们就来看看客户端如何对这个服务端进行调用。
WebService客户端调用
前面提到过,我们为了实现快速调用目标WebService服务端,我们提供了一个名为WebServiceClient对象,通过它可以快速实现调用目标WebService服务端;当然你也可以使用诸如SOAPUI之类客户端工具实现对目标WebService调用测试。
我们这里以之前编写的服务端为类,看看WebServiceClient对象如何调用这个WebService。具体代码如下:
package com.bstek.bdf.webservice.demo; import com.bstek.bdf.webservice.client.WebServiceClient; public class DemoWebserviceClient { public static void main(String[] args) throws Exception{ WebServiceClient client=new WebServiceClient(); //设置目标webservice地址,这个可以在WSDL文档当中看到 client.setDefaultUri("http://localhost:8080/bdf-sample/webservice/demo"); //设置服务验证方式,我们这里采用Username Token用户密码加密方式 ,默认我们的服务端要求用户名与密码相同即可通过认证 client.setUsernameToken("admin", "admin", true); //添加JAXB2支持 client.setMarshallerUnmarshallerClass(new Class[]{User.class,UserResponse.class,UserRequest.class}); UserRequest request=new UserRequest(); request.setUserCount(20); //向目标WebService发送请求,并将响应结果通过JAXB2转换成Java对象 UserResponse response=(UserResponse)client.marshalSendAndReceive(request); int i=1; for(User user:response.getUsers()){ //打印响应结果 System.out.println("webservice 产生的用户"+i+":"+user); i++; } } }
我们已在代码当中进行了注释,这里就不再解释。一旦调用完成(不管是成功还是失败),我们可以在bdf_webservice_logs表中看到日志记录情况。同时在默认情况下我们没有启用权限功能,所以所有用户名密码相同的用户都可以进行调用。
关于WebServiceClient类还有一个方法, 详情可查看WebServiceClient的javadoc。
概述
在BDF的WebService模块当中,我们对于WebService的服务端添加权限控制控制功能,所谓针对WebService进行权限控 制,指的是哪些WebService的Endpoint可以被哪些人访问。在权限控制当中,我们基于Spring Security的权限机制实现,并且与BDF的安全模块进行的集成,也就是说如果您在使用BDF的WebServive的同时,又使用了BDF框架的安 全模块,那么您可以在只修改一些配置属性的情况下,采用BDF的安全模块为您的WebService添加权限控制。
配置
前面在介绍bdf.webservice.properties配置文件时我们了解到几个属性,一个是 bdf.webservice.webServiceSecurityMetadataSource,另一个是 bdf.webservice.accessDecisionManager,前面讲过,这两个属性的默认值是由BDF的WebService模块默认提 供的,默认提供的不带权限控制功能。
这里的bdf.webservice.webServiceSecurityMetadataSourcent属性对应的值是一个配置在 Spring当中的Bean的ID,这个要求实现Spring Security的 org.springframework.security.web.access.intercept.FilterInvocationSecurityMetadataSource 接口,该接口作用是用来在系统启动的时候加载需要进行权限管控的资源(这里的WebService的Endpoint资源),默认BDF的 WebService中提供了一个非常简单的实现,也就是不需要任何类型的WebService的Endpoint资源,相应就表示不对任何 WebService的Endpoint进行权限管控。
bdf.webservice.accessDecisionManager属性对应同样也是一个配置在Spring当中的Bean的ID,要求这个 Bean要实现org.springframework.security.access.AccessDecisionManager接口,同时我们提 供的默认实现里没有添加任何vote(投票器),也就是对任何资源访问权限的投票都是允许。
了解完上面这两个属性后,我们知道如果需要使用WebService的权限控制功能,那么就需要修改这两个属性的值。在BDF的安全模块当中已内置 了对BDF WebService模块的权限控制功能,对于bdf.webservice.webServiceSecurityMetadataSourcent属 性需要的一个可以加载需要进行权限控制的WebService的Endpoint资源的类,在BDF安全模块中对应的类的Bean的ID为 bdf.webserviceSecurityMetadataSourceService;而对于 bdf.webservice.accessDecisionManager属性需要一个AccessDecisionManager,我们直接使用 BDF安全模块当中的名为bdf.resourceDecisionManager即可。所以修改后的这两个属性值如下代码所示。
bdf.webservice.webServiceSecurityMetadataSource=bdf.webserviceSecurityMetadataSourceService
bdf.webservice.accessDecisionManager=bdf.resourceDecisionManager
|
配置好这两个属性之后,接下来我们将需要进行权限管控的WebService的Endpoint添加到位于BDF安全模块的 BDF_WEBSERVICE_RESOURCES表中,该表作用就是用于存放需要 进行权限管制的WebService的Endpoint信息表,定义完成之后再将该表定义的WebService Endpoint信息与角色关联起来,再将允许或拒绝访问的角色成员(用户、部门、群组)与当前角色对应起来,从而完成WebService的权限控制 (具体请参见BDF安全模块介绍)
部署问题
如 果您的目标应用服务器为Weblogic10.3,那么在使用我们的webservice模块时可能会出现启动或调用时错误问题(This class does not support SAAJ 1.1),如果是这样,请在您的Spring环境当中添加如下bean配置:
<
bean
id
=
"messageFactory"
class
=
"org.springframework.ws.soap.saaj.SaajSoapMessageFactory"
>
<
property
name
=
"messageFactory"
>
<
bean
class
=
"com.sun.xml.messaging.saaj.soap.ver1_1.SOAPMessageFactory1_1Impl"
/>
</
property
>
</
bean
>
|
这样Spring WS在初始化时就会采用这里bean中定义的MessageFactory实现类,对进入的消息进行处理。
如果在weblogic10上部署时出现如下异常,
java.lang.LinkageError: loader constraints violated when linking javax/xml/namespace/NamespaceContext
class
|
出现上述异常后,可以通过在工程当中添加下面三个jar应该就可以解决出现的异常
xalan-
2.7
.x+.jar
xercesImpl-
2.8
.x+.jar
xml-apis-
1.3
.x+.jar
|
在Weblogic11g上,即使添加了上述三个jar包,同时也配置了上述的messageFactory,也还可能出现下面这种类型的异常:
Caused by: com.sun.xml.messaging.saaj.SOAPExceptionImpl: Unable to internalize message
at com.sun.xml.messaging.saaj.soap.MessageImpl.init(MessageImpl.java:
470
)
at com.sun.xml.messaging.saaj.soap.MessageImpl.<init>(MessageImpl.java:
273
)
at com.sun.xml.messaging.saaj.soap.ver1_1.Message1_1Impl.<init>(Message1_1Impl.java:
68
)
at com.sun.xml.messaging.saaj.soap.ver1_1.SOAPMessageFactory1_1Impl.createMessage(SOAPMessageFactory1_1Impl.java:
62
)
at org.springframework.ws.soap.saaj.SaajSoapMessageFactory.createWebServiceMessage(SaajSoapMessageFactory.java:
184
)
...
27
more
Caused by: java.lang.LinkageError: loader constraint violation: when resolving overridden method "com.sun.xml.messaging.saaj.soap.SOAPDocumentImpl.createAttribute&#
40
;Ljava/lang/String&#
59
;&#
41
;Lorg/w3c/dom/Attr&#
59
;" the
class
loader &#
40
;instance of weblogic/utils/classloaders/ChangeAwareClassLoader&#
41
; of the current
class
, com/sun/xml/messaging/saaj/soap/SOAPDocumentImpl, and its superclass loader &#
40
;instance of <bootloader>&#
41
;, have different Class objects
for
the type org/w3c/dom/Attr used in the signature
at com.sun.xml.messaging.saaj.soap.SOAPPartImpl.<init>(SOAPPartImpl.java:
88
)
at com.sun.xml.messaging.saaj.soap.ver1_1.SOAPPart1_1Impl.<init>(SOAPPart1_1Impl.java:
58
)
at com.sun.xml.messaging.saaj.soap.ver1_1.Message1_1Impl.getSOAPPart(Message1_1Impl.java:
78
)
at com.sun.xml.messaging.saaj.soap.MessageImpl.initCharsetProperty(MessageImpl.java:
1304
)
at com.sun.xml.messaging.saaj.soap.MessageImpl.init(MessageImpl.java:
363
)
|
解决办法是添加另外一种类型的messageFactory bean(将原来添加的messageFactory bean删除),添加方法是在spring配置文件当中添加如下配置信息:
<bean id=
"messageFactory"
class
=
"org.springframework.ws.soap.axiom.AxiomSoapMessageFactory"
>
<property name=
"payloadCaching"
value=
"true"
/>
</bean>
|
然后将我们的spring-ws升级到2.0.5或以上版本以及axiom升级到1.2.12或以上版本,这样我们的webservice应该就可以正常运行了。
最后,在Spring WS官网上已详细罗列了在各种不同应用服务器当中可能出现的问题,具体请参考http://static.springsource.org/spring-ws/site/faq.html,这里就不再赘述。