Topic
  • 3 replies
  • Latest Post - ‏2010-09-16T06:55:29Z by padamstx
padamstx
padamstx
5 Posts

Pinned topic Feature Focus Week: Java EE 6 Web Services Specification Updates

‏2010-09-13T04:43:26Z |
Java EE 6 contains updates to several Web Services-related specifications: Web Services for Java EE (JSR 109) version 1.3 [1], JAX-WS (JSR 224) version 2.2 [2], and JAXB (JSR 222) version 2.2 [3]. The IBM WebSphere Application Server Beta release contains several new features related to these specification updates. In this initial post, I'll provide a brief overview of the features contained in the Beta release, then in subsequent posts I'll provide a few more details about some of these new features, along with some examples.

JAX-WS 2.2 Update
The Beta release contains an updated version of the JAX-WS implementation (APIs, runtime, and tooling) that brings us closer to compliance with the JAX-WS 2.2 specification. To create portable JAX-WS artifacts, you can use the "wsgen" or "wsimport" tools which are delivered with the Application Server in the <WAS_ROOT>/bin directory. When using the "bottom-up" approach to developing a JAX-WS web service where you start with an SEI class, use "wsgen". If you're using the "top-down" approach where you start with an existing WSDL document, use "wsimport".

JAXB 2.2 Update
The Beta release also contains an updated version of JAXB (tooling and runtime) that complies with the JAXB 2.2 specification. JAXB 2.2 provides minor enhancements to its annotations for improved schema generation and better integration with JAX-WS.

WebServiceFeature annotations and deployment descriptors
Together, the Web Services for Java EE v1.3 [1] and JAX-WS v2.2 [2] specifications support the use of WebServiceFeature annotations and their corresponding deployment descriptors on JAX-WS endpoints and proxy references. JAX-WS 2.1 introduced the WebServiceFeature concept (AddressingFeature, MTOMFeature, RespectBindingFeature) and the various WebServiceFeature annotations (Addressing, MTOM, RespectBinding) for use with endpoints. JAX-WS 2.2 expands on that by extending the use of the WebServiceFeature classes to the various factory-related methods belonging to the JAX-WS Service interface, and by extending the use of the annotations to injected proxy references. Web Services for Java EE 1.3 introduces new deployment descriptor elements that can be used as an alternative to the WebServiceFeature classes and annotations.

The following three standard features are defined:

1) Addressing
The @javax.xml.ws.soap.Addressing annotation and the corresponding <addressing> deployment descriptor element can be used to configure the Addressing feature on JAX-WS endpoints and proxy references. In addition, the AddressingFeature class can be used to configure the Addressing feature when using various methods belonging to the JAX-WS Service interface. In the Beta release, we've added support for the "responses" attribute on the Addressing annotation and the AddressingFeature class, as well as the <addressing> deployment descriptor element and its sub-elements.

2) MTOM
The @javax.xml.ws.soap.MTOM annotation and the corresponding <enable-mtom> and <mtom-threshold> deployment descriptor elements are used to configure the use of MTOM on JAX-WS endpoints and proxy references. In addition, the MTOMFeature class can be used to configure the MTOM feature when using various methods belonging to the JAX-WS Service class.
In the Beta release, we've added support for the "threshold" attribute on the MTOM annotation and the MTOMFeature class, as well as the <mtom-threshold> deployment descriptor element.

3) RespectBinding
The @javax.xml.ws.RespectBinding annotation and the corresponding <respect-binding> deployment descriptor element are used to configure the RespectBinding feature on JAX-WS endpoints and proxy references. In addition, the RespectBindingFeature class can be used to configure the RespectBinding feature when using various methods belonging to the JAX-WS Service class.
In the Beta release, we've extended our support of the RespectBinding feature to include proxy references, and we've added support for the <respect-binding> deployment descriptor element.

In my next post, I'll provide a closer look at the Addressing feature.

References:
[1] - Web Services for Java EE v1.3 specification (JSR 109): http://jcp.org/en/jsr/detail?id=109
[2] - JAX-WS v2.2 specification (JSR 224): http://jcp.org/en/jsr/detail?id=224
[3] - JAXB v2.2 specification (JSR 222): http://jcp.org/en/jsr/detail?id=222

---
Phil Adams
WebSphere Application Server Development - Web Services
IBM - Austin, TX
Updated on 2010-09-16T06:55:29Z at 2010-09-16T06:55:29Z by padamstx
  • padamstx
    padamstx
    5 Posts

    Re: Feature Focus Week: Java EE 6 Web Services Specification Updates

    ‏2010-09-14T03:10:33Z  
    The Addressing feature
    One of the features mentioned in my initial post above is support for the Addressing feature on JAX-WS endpoints and proxy references. This feature can be used to configure the behavior of WS-Addressing within the JAX-WS runtime.

    Configuration of endpoints

    Annotation
    Here's an example of how to configure the Addressing feature on a JAX-WS endpoint implementation class with an annotation:
    
    
    
    import javax.jws.WebService; 
    
    import javax.xml.ws.soap.Addressing; 
    
    import javax.xml.ws.soap.AddressingFeature;   @Stateless(name=
    "MyServiceBean") @Addressing(enabled=true, required=true, responses=AddressingFeature.Responses.NON_ANONYMOUS) @WebService 
    
    public 
    
    class MyServiceImplBean 
    { . . . 
    }
    

    The @Addressing annotation, as used above, would indicate that WS-Addressing is enabled and required (i.e. a WS-Addressing SOAP Header must be present in the SOAP request message), and that the endpoint requires the use of non-anonymous responses.

    Deployment Descriptor
    Here's an example of how to configure the same WS-Addressing behavior via the <addressing> element within the webservices.xml deployment descriptor:
    
    <webservices version=
    "1.3" xmlns=
    "http://java.sun.com/xml/ns/javaee" xmlns:xsi=
    "http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation=
    "http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/javaee_web_services_1_3.xsd">   <webservice-description> <webservice-description-name>MyService</webservice-description-name>   <port-component> <port-component-name>MyServicePort1</port-component-name> <addressing> <enabled>true</enabled> <required>true</required> <responses>NON_ANONYMOUS</responses> </addressing> <service-impl-bean> <!-- 
    
    this maps to a stateless session bean named 
    "MyServiceBean" --> <ejb-link>MyServiceBean</ejb-link> </service-impl-bean> </port-component>   </webservice-description>   </webservices>
    


    Configuration of Proxy References

    Annotation
    Client application developers can use the @WebServiceRef and @Resource annotations, as well as the <service-ref> deployment descriptor element, to declare references to web services that will be invoked by the client application. In addition to declaring a reference to a service, the client application developer could declare a reference to a specific port belonging to that service, thereby avoiding the need for the client application to explicitly retrieve the port by calling one of the Service interface's "getPort"-type methods. These references to ports (or proxies) are called proxy references, and a proxy reference defined via the @WebServiceRef or @Resource annotation is called an injected proxy reference.

    In the examples that follow, suppose that the web service that will be invoked is called com.example.MyService and that the Service Endpoint Interface (SEI) implemented by the service is called com.example.MyServiceSEI.

    Here's an example of how to declare an injected proxy reference with an @WebServiceRef annotation and configure the WS-Addressing behavior associated with that injected proxy reference:
    
    
    // This class could be any of the Java EE component types in which resource injection is supported 
    // (e.g. EJB, Servlet, Handler, JAX-WS endpoint impl class, Application Client main class, etc.)   
    
    import javax.xml.ws.WebServiceRef; 
    
    import javax.xml.ws.soap.Addressing; 
    
    import com.example.MyService; 
    
    import com.example.MyServiceSEI;   
    
    public 
    
    class MyClientApplication 
    {   @Addressing(enabled=true, required=
    
    true) @WebServiceRef(type=MyServiceSEI.class, value=MyService.class) 
    
    private MyServiceSEI myInjectedPort; ... 
    }
    

    Note that the @Addressing annotation can only be used in conjunction with injected proxy references. In other words, it can only be used on a field or method which also has an @WebServiceRef or @Resource annotation that declares an injected proxy reference.

    Deployment Descriptor
    Here's an example of how to declare a similar proxy reference with the <service-ref>/<port-component-ref> deployment descriptor element, and configure the WS-Addressing behavior with the <addressing> element:
    
    <service-ref> <service-ref-name>service/MyServicePort</service-ref-name> <service-interface>com.example.MyService</service-interface> <service-ref-type>com.example.MyServiceSEI</service-ref-type> <wsdl-file>META-INF/wsdl/MyService.wsdl</wsdl-file> <port-component-ref> <service-endpoint-interface>com.example.MyServiceSEI</service-endpoint-interface> <addressing> <enabled>true</enabled> <required>true</required> </addressing> </port-component-ref> </service-ref>
    

    To use this proxy reference, the client application could perform a JNDI lookup, similar to the following:
    
    
    // Retrieve the proxy reference named "service/MyServicePort". InitialContext ic = 
    
    new InitialContext(); MyServiceSEI myPort = (MyServiceSEI) ic.lookup(
    "java:comp/env/service/MyServicePort");
    


    AddressingFeature
    Another way to configure WS-Addressing on the client is to use the javax.xml.ws.soap.AddressingFeature class when calling the Service.getPort() method. Here's an example:
    
    
    // Injected instance of MyService @WebServiceRef MyService myService;   AddressingFeature addressingFeature = 
    
    new AddressingFeature(true, 
    
    true); MyServiceSEI myPort = myService.getMyServicePort(addressingFeature);
    

    That concludes the discussion of the Addressing feature. Feel free to post any questions or comments you may have.

    In my next post, I'll focus on the MTOM feature.

    ---
    Phil Adams
    WebSphere Application Server Development - Web Services
    IBM - Austin, TX
  • padamstx
    padamstx
    5 Posts

    Re: Feature Focus Week: Java EE 6 Web Services Specification Updates

    ‏2010-09-15T14:40:09Z  
    The MTOM feature
    In today's post, I'll focus on the MTOM (Message Transmission Optimization Mechanism) feature. JAX-WS supports the use of MTOM for transmitting binary attachments along with SOAP request and response messages. By enabling MTOM, you can send and receive binary data more efficiently by avoiding the cost of encoding the attachments within a text-based XML message.

    The MTOM feature is used to configure the MTOM behavior forJAX-WS endpoints and proxy references, and follows the same general pattern as the Addressing feature.

    Configuration of endpoints

    Annotation
    Here's an example of how to configure the MTOM feature on a JAX-WS endpoint implementation class with an annotation:
    
    
    
    import javax.jws.WebService; 
    
    import javax.xml.ws.soap.MTOM;   @Stateless(name=
    "MyServiceBean") @MTOM(enabled=true, threshold=2048) @WebService 
    
    public 
    
    class MyServiceImplBean 
    { . . . 
    }
    

    The @MTOM annotation, as used above, would indicate that MTOM is enabled when sending response messages, and that any attachment which is 2048 bytes or larger will be represented as a separate MIME part (separate from the MIME part containing the SOAP envelope) within the response message.

    Deployment Descriptor
    Here's an example of how to configure the same MTOM behavior via the <enable-mtom> and <mtom-threshold> elements within the webservices.xml deployment descriptor:
    
    <webservices version=
    "1.3" xmlns=
    "http://java.sun.com/xml/ns/javaee" xmlns:xsi=
    "http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation=
    "http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/javaee_web_services_1_3.xsd">   <webservice-description> <webservice-description-name>MyService</webservice-description-name>   <port-component> <port-component-name>MyServicePort1</port-component-name> <enable-mtom>true</enable-mtom> <mtom-threshold>2048</mtom-threshold> <service-impl-bean> <!-- 
    
    this maps to a stateless session bean named 
    "MyServiceBean" --> <ejb-link>MyServiceBean</ejb-link> </service-impl-bean> </port-component>   </webservice-description>   </webservices>
    


    Configuration of Proxy References

    Annotation
    The @MTOM annotation can be used to configure the MTOM behavior of injected proxy references (for more information about injected proxy references, see the prior post related to the Addressing feature).

    In the examples that follow, suppose that the web service that will be invoked is called com.example.MyService and that the Service Endpoint Interface (SEI) implemented by the service is called com.example.MyServiceSEI.

    Here's an example of how to declare an injected proxy reference with an @WebServiceRef annotation and configure the MTOM behavior associated with that injected proxy reference:
    
    
    // This class could be any of the Java EE component types in which resource injection is supported 
    // (e.g. EJB, Servlet, Handler, JAX-WS endpoint impl class, Application Client main class, etc.)   
    
    import javax.xml.ws.soap.MTOM; 
    
    import javax.xml.ws.WebServiceRef; 
    
    import com.example.MyService; 
    
    import com.example.MyServiceSEI;   
    
    public 
    
    class MyClientApplication 
    {   @MTOM(enabled=true, threshold=3072) @WebServiceRef(type=MyServiceSEI.class, value=MyService.class) 
    
    private MyServiceSEI myInjectedPort; ... 
    }
    

    The @MTOM annotation, as used above, would indicate that MTOM is enabled when sending request messages associated with this proxy reference, and that any attachment which is 3072 bytes or larger will be represented as a separate MIME part (separate from the MIME part containing the SOAP envelope) within the request message.

    Also note that the @MTOM annotation can only be used in conjunction witth injected proxy references. In other words, it can only be used on a field or method which also has an @WebServiceRef or @Resource annotation that declares an injected proxy reference.

    Deployment Descriptor
    Here's an example of how to declare a similar proxy reference with the <service-ref>/<port-component-ref> deployment descriptor element, and configure the MTOM behavior with the <enable-mtom> and <mtom-threshold> elements:
    
    <service-ref> <service-ref-name>service/MyServicePort</service-ref-name> <service-interface>com.example.MyService</service-interface> <service-ref-type>com.example.MyServiceSEI</service-ref-type> <wsdl-file>META-INF/wsdl/MyService.wsdl</wsdl-file> <port-component-ref> <service-endpoint-interface>com.example.MyServiceSEI</service-endpoint-interface> <enable-mtom>true</enable-mtom> <mtom-threshold>3072</mtom-threshold> </port-component-ref> </service-ref>
    

    To use this proxy reference, the client application could perform a JNDI lookup, similar to the following:
    
    
    // Retrieve the proxy reference named "service/MyServicePort". InitialContext ic = 
    
    new InitialContext(); MyServiceSEI myPort = (MyServiceSEI) ic.lookup(
    "java:comp/env/service/MyServicePort");
    


    MTOMFeature
    Another way to configure the MTOM behavior of the client is to use the javax.xml.ws.soap.MTOMFeature class when calling the Service.getPort() method. Here's an example:
    
    
    // Injected instance of MyService @WebServiceRef MyService myService;   MTOMFeature mtomFeature = 
    
    new MTOMFeature(true, 3072); MyServiceSEI myPort = myService.getMyServicePort(mtomFeature);
    

    That concludes the discussion of the MTOM feature. Feel free to post any questions or comments you may have.

    In my next post, I'll focus on the RespectBinding feature.

    ---
    Phil Adams
    WebSphere Application Server Development - Web Services
    IBM - Austin, TX
  • padamstx
    padamstx
    5 Posts

    Re: Feature Focus Week: Java EE 6 Web Services Specification Updates

    ‏2010-09-16T06:55:29Z  
    The RespectBinding feature
    In today's final post in this series, I'll focus on the RespectBinding feature. The RespectBinding feature is used to configure the JAX-WS runtime's enforcement of the contents of the wsdl:binding within the WSDL document associated with an endpoint or proxy reference. If RespectBinding is enabled, then the JAX-WS runtime must respect/honor the wsdl:binding associated with the endpoint or proxy reference. Any failure encountered while enforcing the RespectBinding behavior will result in an exception.

    As an example, consider the following partial WSDL document which might be associated with an endpoint or proxy reference:
    
    <?xml version=
    "1.0" encoding=
    "UTF-8" standalone=
    "yes"?> <definitions targetNamespace=
    "http://test.com/" name=
    "Service1Service" xmlns:wsdl=
    "http://schemas.xmlsoap.org/wsdl/" xmlns:xsd=
    "http://www.w3.org/2001/XMLSchema" xmlns:tns=
    "http://test.com/" xmlns:soap=
    "http://schemas.xmlsoap.org/wsdl/soap/" xmlns:xyz=
    "http://xyz.com"> <wsdl:types> ... </wsdl:types> ... <wsdl:portType name=
    "Service1"> ... </wsdl:portType> <wsdl:binding name=
    "Service1PortBinding" type=
    "tns:Service1"> <soap:binding transport=
    "http://schemas.xmlsoap.org/soap/http" style=
    "document"/> <xyz:XYZComponentConfig uri=
    "http://test/binding" required=
    "true"/> <wsdl:operation name=
    "Operation1"> ... </wsdl:operation> ... </wsdl:binding> <wsdl:service name=
    "Service1Service"> <wsdl:port name=
    "Service1Port" binding=
    "tns:Service1PortBinding"> <soap:address location=
    "http://host1:9081/MyApp/Service1"/> </wsdl:port> </wsdl:service> </wsdl:definitions>
    

    Notice that within the <wsdl:binding> element, there is an extensibility element named "xyz:XYZComponentConfig". This element represents additional component-specific configuration which might be required by a component within the web services stack. This could be a native component such as WS-Addressing, or it could be a third-party component of some sort. Extensibility elements such as the <xyz:XYZComponentConfig> element could appear within the <wsdl:binding> element or any of its child elements such as <wsdl:operation>, <wsdl:input> or <wsdl:output>.

    Notice that the "required" attribute of the <xyz:XYZComponentConfig> element is set to "true". If RespectBinding is enabled, and the "required" attribute is set to "true", then the web services stack will ensure that a component exists which supports this extensibility element. If one does not exist, then an exception is thrown. For an endpoint, it will fail initialization and will not be available for request processing. For a client, the exception would be thrown during the client-side request processing prior to the point at which the SOAP request message is sent to the endpoint.

    So in general, if RespectBinding is enabled, an extra level of validation is performed by the web services engine to ensure that any "required" extensibility elements contained with the wsdl:binding (and its child elements) are, in fact, understood and supported by the components within the web services stack.
    Configuration of endpoints

    Annotation
    Here's an example of how to configure the RespectBinding feature on a JAX-WS endpoint implementation class with an annotation:
    
    
    
    import javax.jws.WebService; 
    
    import javax.xml.ws.RespectBinding;   @Stateless(name=
    "MyServiceBean") @RespectBinding(enabled=
    
    true) @WebService 
    
    public 
    
    class MyServiceImplBean 
    { . . . 
    }
    


    Deployment Descriptor
    Here's an example of how to configure the same RespectBinding behavior via the <respect-binding> element within the webservices.xml deployment descriptor:
    
    <webservices version=
    "1.3" xmlns=
    "http://java.sun.com/xml/ns/javaee" xmlns:xsi=
    "http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation=
    "http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/javaee_web_services_1_3.xsd">   <webservice-description> <webservice-description-name>MyService</webservice-description-name>   <port-component> <port-component-name>MyServicePort1</port-component-name> <respect-binding> <enabled>true</enabled> </respect-binding> <service-impl-bean> <!-- 
    
    this maps to a stateless session bean named 
    "MyServiceBean" --> <ejb-link>MyServiceBean</ejb-link> </service-impl-bean> </port-component>   </webservice-description>   </webservices>
    


    Configuration of Proxy References

    Annotation
    The @RespectBinding annotation can be used to configure the RespectBinding behavior of injected proxy references (for more information about injected proxy references, see the prior post related to the Addressing feature).

    As in the examples presented in previous posts, suppose that the web service that will be invoked is called com.example.MyService and that the Service Endpoint Interface (SEI) implemented by the service is called com.example.MyServiceSEI.

    Here's an example of how to declare an injected proxy reference with an @WebServiceRef annotation and configure the RespectBinding behavior associated with that injected proxy reference:
    
    
    // This class could be any of the Java EE component types in which resource injection is supported 
    // (e.g. EJB, Servlet, Handler, JAX-WS endpoint impl class, Application Client main class, etc.)   
    
    import javax.xml.ws.RespectBinding; 
    
    import javax.xml.ws.WebServiceRef; 
    
    import com.example.MyService; 
    
    import com.example.MyServiceSEI;   
    
    public 
    
    class MyClientApplication 
    {   @RespectBinding(enabled=
    
    true) @WebServiceRef(type=MyServiceSEI.class, value=MyService.class) 
    
    private MyServiceSEI myInjectedPort; ... 
    }
    

    Note that the @RespectBinding annotation can only be used in conjunction with injected proxy references. In other words, it can only be used on a field or method which also has an @WebServiceRef or @Resource annotation that declares an injected proxy reference.

    Deployment Descriptor
    Here's an example of how to declare a similar proxy reference with the <service-ref>/<port-component-ref> deployment descriptor element, and configure the RespectBinding behavior with the <respect-binding> element:
    
    <service-ref> <service-ref-name>service/MyServicePort</service-ref-name> <service-interface>com.example.MyService</service-interface> <service-ref-type>com.example.MyServiceSEI</service-ref-type> <wsdl-file>META-INF/wsdl/MyService.wsdl</wsdl-file> <port-component-ref> <service-endpoint-interface>com.example.MyServiceSEI</service-endpoint-interface> <respect-binding> <enabled>true</enabled> </respect-binding> </port-component-ref> </service-ref>
    

    To use this proxy reference, the client application could perform a JNDI lookup, similar to the following:
    
    
    // Retrieve the proxy reference named "service/MyServicePort". MyServiceSEI myPort = (MyServiceSEI) ic.lookup(
    "java:comp/env/service/MyServicePort");
    


    RespectBindingFeature
    Another way to configure the RespectBinding behavior of the client is to use the javax.xml.ws.RespectBindingFeature class when calling the Service.getPort() method. Here's an example:
    
    
    // Injected instance of MyService @WebServiceRef MyService myService;   RespectBindingFeature rbFeature = 
    
    new RespectBindingFeature(
    
    true); MyServiceSEI myPort = myService.getMyServicePort(rbFeature);
    


    This post is the last in this series of posts dedicated to the Java EE 6 Web Services Specification Updates. I hope you have found these discussions helpful. Please feel free to respond with any questions or comments you may have.

    Note that a Customer Experience Program (CEP) Reflections session will be conducted at the end of this Feature Focus Week (FFW) period, tentatively scheduled for Sept 23rd. If you would like to participate in this reflection session, please be sure to sign up for the CEP at this link: https://www14.software.ibm.com/iwm/web/cc/earlyprograms/websphere/wsasoa/other.shtml.

    Regards,
    Phil

    ---
    Phil Adams
    WebSphere Application Server Development - Web Services
    IBM - Austin, TX