JAX-WS：背后的技术JAXB及传递Map

转载：http://www.programgo.com/article/98912703200/

1、什么是JAX-WS

JAX-WS (JavaTM API for XML-Based Web Services)规范是一组XML web services的JAVA API。JAX-WS允许开发者可以选择RPC-oriented或者message-oriented 来实现自己的web services。JAX-WS2.0 (JSR 224)是Sun新的web services协议栈，是一个完全基于标准的实现。在binding层，使用的是the Java Architecture for XML Binding (JAXB, JSR 222)，在parsing层，使用的是the Streaming API for XML (StAX, JSR 173)，同时它还完全支持schema规范。在JDK6.0之后已经整合到SDK中，所以我们以下的实例只需要在JDK6后即可，不需要再添加额外的依赖包

这是网上找到的JAX-WS的原理图

 

为了方便传送过来【以下内容来自http://blog.csdn.net/kkdelta/article/details/4017747】

写道

1、客户端开发者通过URL得到WSDL文件。(通过HTTP访问可以得到,http://<endpoint-address>?wsdl)  
2、客户端根据WSDL的描述,通过HTTP POST发送SOAP消息给服务器端。  
3、服务器端Listener接受到SOAP请求消息,对JAVA来说,通常是一个servlet或者EJB。Listener把消息转发给 Dispatcher,有时候listener和Dispatcher也可能是同一个类。Dispatcher会把请求消息交给WebService的运行终端。  
4、这时候,服务器端会将HTTP request转成服务器端的消息类型,形成javax.xml.ws.handler.MessageContext,并处理SOAP消息的头信息,如mustUnderstand。  
5、如果在服务器端配置了handler,会调用handler的handleMessage方法,通常用handler来保存消息,解密或者保证消息到达的顺序。handler通过在@HandlerChain标注配置handlers.xml文件内容为： 

<handler-chains xmlns="http://java.sun.com/xml/ns/javaee">
  <handler-chain>
       <handler>
           <handler-name>WSSOAPHandler</handler-name>
           <handler-class>com.cxf.test.WSSOAPHandler</handler-class>
           </handler>
       </handler-chain>
   <handler-chain>
   <handler>
       <handler-name>WSHandler</handler-name>
       <handler-class>com.cxf.test.WSHandler</handler-class>
     </handler>
   </handler-chain>
</handler-chains>

  
6、SOAP消息被反序列化为JAVA对象,传到真正的实现业务的类。  
7、调用真正的业务方法,执行后利用JAXB注解序列化成SOAP返回消息。  
8、如果配置了handler,会调用handler的handleMessage方法。如果业务方法有异常抛出,把异常转为SOAP fault 消息。  
9、Listener通过HTTP把response返回给客户端。  
总体来讲:整个过程是一个Requset XML(SOAP)-->JAXB-->JAVA Object-->JAXB-->Response XML(SOAP)的过程 

  

2、从一个例子开始

只需要几个简单的annotation即可发布一个基于JAX-WS的webservice服务：

@WebService
public interface HelloJAXWS {

    public String sayHello();
}

@WebService
public class HelloJAXWSImpl implements HelloJAXWS {

    @WebMethod
    public String sayHello() {
        return "Hello, JAX-WS";
    }

}

在一个main函数中发布该服务：

Endpoint.publish("http://localhost:8080/service/helloJaxWs", new HelloJAXWSImpl());

这样我们就可以在浏览器通过上面的URL访问：

http://localhost:8080/service/helloJaxWs?wsdl

如果看到返回的xml格式的文档表示我们就发布成功。

下面来看看客户端代码，在JDK中也提供了相应的工具来根据wsdl生成客户端代码这就是wsimport，可以通过wsimport -help来查看相应的参数。这里采用了以下几个参数

wsimport -verbose -p com.sample.sws.ws -keep http://localhost:8080/service/helloJaxWs?wsdl
-verbose 显示编译的信息
-p 指定客户端package
-keep 保存生成客户端的源文件和编译好的class文件

在指定的package下就可以看到生成的service代理类，当然具体的类名会根据之前@WebService（）后的参数设置，比如我server端的服务类声明如下：

@WebService(serviceName = "helloJaxWsService", endpointInterface = "org.ws.server.ws.chap1.impl.HelloJAXWSImpl")
@SOAPBinding(style = Style.DOCUMENT)

生成的客户端代理类也是根据上面的serviceName来HelloJaxWsService

下面是客户端调用的代码

HelloJAXWSImpl hellpJaxWs = new HelloJaxWsService().getHelloJAXWSImplPort();
System.out.println(hellpJaxWs.sayHello());

这样就完成了一个创建webservice->发布->生成客户端代码->客户端调用的整个过程

3、传递复杂对象

从上面2中的例子是返回String对象，其实JAX-WS原生对复杂对象都有很好的支持，如我们一些业务上的PO或List对象等。下面来看一个例子：

@WebService
public interface JaxWsService {

    public Address getAddress(String id);

    public Person getPerson(String id);

    List<Address> getAddressList(Address address);
}

这里申明了Address和Person对象，其中Person包含一个List<Address>属性：

public class Person implements Serializable {
    private static final long serialVersionUID = 8336803120311071811L;

    private String            username;
    private Date              birthday;
    private List<Address>     addresses;
       //以下省略若干
}

public class Address implements Serializable {

    private static final long serialVersionUID = 5038515089191304705L;
    private String            street;
    private String            city;
    private int               port;
       //以下省略若干
}

在对上面的接口做简单的实现，按照上面的流程生成客户端代码调用即可达到预期的效果。这里不在赘述例子可见代码，这里想要说明的是JAX-WS中对大多数普通对象不需要做任何处理即可传输

4、wsimport与wsgen

这两个工具位于$JAVA_HOME$/bin目录

• wsimport 前面已经用到这个工具，用来解析一个存在的WSDL文档，生成客户端代码。通过wsimport查询参数或者http://jax-ws.java.net/jax-ws-ea3/docs/wsimport.html
• wsgen 工具还可以用来从一个Web服务中生成对应的WSDL文档

如

@WebService
public class JaxWsWebServiceImpl implements JaxWsWebService {

    @WebMethod
    public @WebResult
    String getMessage() {
        return "Hello";
    }

}

H:gitwebserviceswssws-server	argetclasses>wsgen -verbose -keep -cp "." -wsdl org.ws.server.ws.chap8.impl.JaxWsWebServiceImpl
生成6个文件：
JaxWsWebServiceImplService.wsdl
JaxWsWebServiceImplService_schema1.xsd
orgwsserverwschap8impljaxwsGetMessage.java
orgwsserverwschap8impljaxwsGetMessage.class
orgwsserverwschap8impljaxwsGetMessageResponse.java
orgwsserverwschap8impljaxwsGetMessageResponse.class

 详情介绍见这里 

5、Endpoint.publish初探

从上面我们知道发布一个webservice我们只需要通过

public static Endpoint publish(String address, Object implementor)

即可，其实这后面依赖于JavaSE6提供了一个轻量级的HttpServer。位于rt.jar下的com.sun.net.httpserver，具体可见这里同时这里还有一个小实例

接上文JAX-WS：创建简单的webservice，JAX-WS对大部分复杂对象传递都能直接支持。在服务端传递了自定义的复杂对象Person：

public class Person implements Serializable {
    private static final long serialVersionUID = 8336803120311071811L;

    private String            username;
    private Date              birthday;
    private List<Address>     addresses;
//getter/setter

我们来看看根据wsimport生产的客户端中Person的定义：

@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = "person", propOrder = {
    "addresses",
    "birthday",
    "username"
})
public class Person {

    @XmlElement(nillable = true)
    protected List<Address> addresses;
    @XmlSchemaType(name = "dateTime")
    protected XMLGregorianCalendar birthday;
    protected String username;
//getter/setter
}

在生产的客户端代码中多了很多annotation声明，在前面也说了JAX-WS是一种基于xml传递的webservice，也就是需要将传递的参数转化为xml文档，而这其中转化的过程就是我们见到的客户端对象中各种annotation声明，其背后的技术也就是前面说的JAXB(Java Architecture for XML Binding)简单地说就是一种将JAVA对象和XML互相转换的技术。包含在包
javax.jws
javax.xml.bind下提供了一系列解组、编组已经运行时绑定的API
javax.xml.bind.annotation 定义将 Java 程序元素定制成XML模式映射的注释
javax.xml.bind.annotation.adapters XmlAdapter 及其规范定义的子类允许任意 Java 类与 JAXB 一起使用

---------------------------------------- 

主要的接口或类：

HandlerChain 将 Web Service 与外部定义的处理程序链关联。 
Oneway 指示给定 @WebMethod 只有一条输入消息并且没有输出。 
WebMethod 定制一个公开为 Web Service 操作的方法。 
WebParam 定制单个参数到 Web Service 消息部分和 XML 元素的映射关系。 
WebResult 定制返回值到 WSDL 部分和 XML 元素的映射关系。 
WebService 将 Java 类标记为实现 Web Service，或者将 Java 接口标记为定义 Web Service 接口。

Element 这是一个元素标记接口。 
Marshaller Marshaller 类负责管理将 Java 内容树序列化回 XML 数据的过程。  
Unmarshaller Unmarshaller 类管理将 XML 数据反序列化为新创建的 Java 内容树的过程，并可在解组时有选择地验证 XML 数据。 
UnmarshallerHandler 作为 SAX ContentHandler 实现的 Unmarshaller。 
ValidationEvent此事件指示在执行解组操作期间验证传入的 XML 数据时、对 Java 内容树执行按需验证时或将 Java 内容树编组回 XML 数据时遇到问题。 
DatatypeConverter可以使用 javaType 绑定声明来自定义 XML 模式数据类型到 Java 数据类型的绑定。 
JAXBContext JAXBContext 类提供到 JAXB API 的客户端入口点。 
XmlAdapter 修改 Java 类型以适应自定义编组

主要的Annotation

XmlAccessorOrder  控制类中字段和属性的排序。 
XmlAccessorType  控制默认情况下是否对字段或 Javabean 属性进行系列化。 
XmlAttribute   将 JavaBean 属性映射到 XML 属性。 
XmlElement   将 JavaBean 属性映射到派生于属性名称的 XML 元素。 
XmlElementWrapper  生成一个包装 XML 表示形式的包装器元素。 
XmlList    用来将属性映射到列表简单类型。 
XmlMimeType   关联控制属性 XML 表示形式的 MIME 类型。  
XmlRootElement   将类或枚举类型映射到 XML 元素。 
XmlTransient   阻止将 JavaBean 属性映射到 XML 表示形式。 
XmlType   将类或枚举类型映射到 XML 模式类型。 
XmlValue   支持将类映射到带有 simpleContent 的 XML 模式复杂类型或 XML 模式简单类型。

1、如何解码转码

JAXBContext是JAXB API 的客户端入口，从java到xml的互相转换对应Marshaller和Unmarshaller。一个简单的例子是

JAXBContext jaxbContext = JAXBContext.newInstance(claszz);
Marshaller marshaller = jaxbContext.createMarshaller();

marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);
marshaller.setProperty(Marshaller.JAXB_FRAGMENT, true);
marshaller.setProperty(Marshaller.JAXB_ENCODING, "utf-8");
marshaller.setProperty(Marshaller.JAXB_SCHEMA_LOCATION, "http://sws.org/sample");

marshaller.marshal(t, System.out);
marshaller.marshal(t, new File("c:\t.xml"));

 这里只是java转xml的例子。设置了格式化输出、encoding等属性、schema等信息，同时输出到控制台和指定文件路径 

2、常用annotation
常用的annotation用来绑定转换运行过程中的各种属性，如绑定属性、绑定的顺序、格式化处理等。下面介绍一些常用

@XmlRootElement(name="",namespace="")
标注此类作为xml的一个root节点，常用在顶层类或枚举类型。以下注释一起使用： XmlType、XmlEnum、XmlAccessorType、 XmlAccessorOrder。作为生产xml的root节点，名称可通过name来指定，默认会为该类名

@XmlAccessorType(XmlAccessType.FIELD)
控制对JavaBean的访问方式，一般有PROPERTY(getter/setter)、FIELD，PUBLIC_MEMBER(public getter/setter,fileds)、NONE可用于包，顶层类。若用于包表示该包下所有的类都照此处理，顶层类也即如果该类有其他的实体也将照此处理
默认为@XmlAccessorType(XmlAccessType.PUBLIC_MEMBER)

@XmlAccessorOrder(XmlAccessOrder.ALPHABETICAL)
指定序列化javabean的顺序

@XmlElement
@XmlElement 注释可以与以下程序元素一起使用： JavaBean 属性 ,非 static、非 transient 字段 ,XmlElements 中的程序元素

@XmlElement(name = "firstName")
private String name;
private int age;

如果顶层类中标志了访问类型，如Filed。那么各个fileds的名称会被处理为xml中的节点，若按照上面的标注，此时节点名会是firstName

<firstName>nico</firstName>
<age>20</age>

@XmlTransient 
@XmlTransient 注释对于解决 JavaBean 属性名称与字段名称之间的名称冲突，或者用于防止字段/属性的映射。

@XmlTransient
private String lastName;

则lastName不会被映射

@XmlList 
@XmlList 来将属性映射到列表简单类型。比较两种序列方式：            

 List<String> data;
<foo><data>aaaa</data><data>bbbb</data></foo>

@XmlList
List<String> data;
<foo><data>aaaa bbbb</data></foo>

@XmlJavaTypeAdapter(class)
用来描述自定义的adapter，需要继承XmlAdapter，用来对自定义序列化的格式。如我们对时间的格式化输出

@XmlValue   
支持将类映射到带有 simpleContent 的 XML 模式复杂类型或 XML 模式简单类型。 简单说就是可以指定格式

<msg name="name">robin</msg>

 下面是一个Person的javabean，包含了一系列的声明：

@XmlRootElement(name = "per")
@XmlAccessorType(XmlAccessType.FIELD)
@XmlAccessorOrder(XmlAccessOrder.ALPHABETICAL)
public class Person {
    @XmlElement(name = "firstName")
    private String         name;
    @XmlTransient
    private String         lastName;
    @XmlJavaTypeAdapter(value = DateXmlAdapter.class)
    private Date           birthDay;
    @XmlList
    private List<String>   lang;

    private List<KeyValue> msg;
//getter/setter
}

 其中DateXmlAdapter如下：

public class DateXmlAdapter extends XmlAdapter<String, Date> {

    @Override
    public String marshal(Date v) throws Exception {
        SimpleDateFormat format = new SimpleDateFormat("yyyy-MM-dd");
        return format.format(v);
    }

    @Override
    public Date unmarshal(String v) throws Exception {
        SimpleDateFormat format = new SimpleDateFormat("yyyy-MM-dd");
        return format.parse(v);
    }

}

 KeyValue：

@XmlAccessorType(XmlAccessType.FIELD)
public class KeyValue {

    @XmlAttribute
    private String name;
    @XmlValue
    private String value;

序列化结果为：

Person p = new Person();
p.setName("robin");
p.setLastName("yang");
p.setBirthDay(new Date());
List<String> lang = Arrays.asList(new String[] { "java", "javascript", "python" });
p.setLang(lang);
List<KeyValue> msg = new ArrayList<KeyValue>();
msg.add(new KeyValue("aa", "aaa-value"));
msg.add(new KeyValue("bbb", "bbb-value"));
p.setMsg(msg);

<per>
    <birthDay>2012-11-17</birthDay>
    <lang>java javascript python</lang>
    <msg name="aa">aaa-value</msg>
    <msg name="bbb">bbb-value</msg>
    <firstName>robin</firstName>
</per>

3、JAX-WS传递Map

前面在说到可以传递复杂对象时并没有指定Map，是因为并不支持原生的Map传递。如果需要传递我们需要做一个简单的包装，同时需要利用到上面说的XmlJavaTypeAdapter来对bean到xml转换转换。下面的例子是传递Map实例：

@WebService
public interface JaxWsMapService {

    @WebMethod
    public WrapperMapResult getPersonMap();

}

 WrapperMapResult 只是对Map的一个简单封装：

@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public class WrapperMapResult {

    private String              message;
    private boolean             success;

    @XmlJavaTypeAdapter(value = MapAdapter.class)
    private Map<String, Person> map;

 其中最重要的是MapAdapter：

public class MapAdapter extends XmlAdapter<MapConvertor, Map<String, Person>> {

    @Override
    public Map<String, Person> unmarshal(MapConvertor convertor) throws Exception {
        List<MapEntry> entries = convertor.getEntries();
        if (entries != null && entries.size() > 0) {
            Map<String, Person> map = new HashMap<String, Person>();
            for (MapEntry mapEntry : entries) {
                map.put(mapEntry.getKey(), mapEntry.getValue());
            }
            return map;
        }
        return null;
    }

    @Override
    public MapConvertor marshal(Map<String, Person> map) throws Exception {
        MapConvertor convertor = new MapConvertor();
        for (Map.Entry<String, Person> entry : map.entrySet()) {
            convertor.addEntry(new MapConvertor.MapEntry(entry));
        }
        return convertor;
    }

}

这里声明了MapConvertor用来解析Map<String, Person>

@XmlType(name="MapConvertor")
@XmlAccessorType(XmlAccessType.FIELD)
public class MapConvertor {

    private List<MapEntry> entries = new ArrayList<MapConvertor.MapEntry>();  //这里的思路是将Map传入List中传递

    public void addEntry(MapEntry entry) {
        entries.add(entry);
    }

    public List<MapEntry> getEntries() {
        return entries;
    }

    //结构依赖于需要Conver的Map，比如这里Map<String, Person>
    public static class MapEntry {
        private String key;
        private Person value;

        public MapEntry() {

        }

        public MapEntry(String key, Person person) {
            this.key = key;
            this.value = person;
        }

        public MapEntry(Map.Entry<String, Person> entry) {
            this.key = entry.getKey();
            this.value = entry.getValue();
        }

        public String getKey() {
            return key;
        }

        public void setKey(String key) {
            this.key = key;
        }

        public Person getValue() {
            return value;
        }

        public void setValue(Person value) {
            this.value = value;
        }

    }

}

其他的步骤按照wsimport生产客户端代码调用即可，这样就完成了JAX-WS中map的传递