Change Log: JSR-109 : Web Services for Java EE, Version 1.3

Description

Maintenance Review for JSR-109 Web Services for Java EE, Version 1.3

Maintenance Lead

Jitendra Kotamraju, Sun Microsystems, Inc.

Feedback

Comments should be sent to jsr109-spec-comments@sun.com

Rationale for proposed changes

The main goals of this maintenance release: From the specification perspective, these changes are minimal and targeted solely to fulfill the above stated goals.

Changes

The changes to the specification are listed below. Changes are listed in the order of the sections in the specification.

2.1.2 Service Development Goals

Modified as follows to reflect Singleton EJB requirements:
Support mapping and dispatching SOAP 1.1 or 1.2 requests to methods on Java EE Stateless or Singleton Session Beans.

2.1.3 Service Deployment Goals

Modified as follows for Java EE version:
Support mapping and dispatching SOAP 1.1 or 1.2 requests to methods on Java EE Stateless or Singleton Session Beans.

3.2 Web Service

Modified as follows to reflect Singleton EJB requirements:
A service implementation implements the methods of an interface that is describable by WSDL. The methods are implemented using a Stateless/Singleton Session EJB or JAX-RPC/JAX-WS web component.

3.3.1 Web Service Components

Modified as follows to reflect Singleton EJB requirements:
The second uses a constrained implementation of a stateless session EJB or Singleton(only for JAX-WS services) in the EJB container.

3.6.2 JAX-WS 2.2

Add the following:
JAX-WS 2.2 adds a complete Web Services addressing support as specified in Web Services Addressing 1.0 - Core, Web Services Addressing 1.0 - Soap Binding, and Web Services Addressing 1.0 - Metadata.

3.7 Interoperability

Update the JAX-WS version:

3.10 Web Service Server View

Modified as follows to reflect Singleton EJB requirements:
The business logic of a Web service is implemented by a service provider in the following ways:
Add the following:
3. A Singleton EJB:The service provider implements the JAX-WS Web service business logic by creating a singleton Bean that implements the methods of the Service Endpoint Interface as described in the EJB 3.1 specification.

3.11 Java EE profiles

The Java EE 6 platform specification introduces "profiles" to target specific class of applications. See chapter 9 of Java EE 6 specification for more details.

The Java EE 6 platform marks JAX-RPC as a proposed optional technology that may be pruned in a future release. Therefore, requirements in this specification related to JAX-RPC should also be considered proposed optional. Such requirements may be made optional in a future release of this specification.

This specification gives choices for the vendors that want to support only certain containers for JAX-WS web services. A JSR-109 implementation must support at least one of the following configurations for JAX-WS web services:

  1. JAX-WS web component in a Servlet container
  2. Stateless or Singleton Session EJB as JAX-WS web service

4.2.2 javax.xml.ws.WebServiceRef annotation

Add the following:
The annotations (for example, @javax.xml.ws.soap.Addressing) annotated with meta-annotation javax.xml.ws.spi.WebServiceFeatureAnnotation can be used in conjunction with @WebServiceRef. The created reference MUST be configured with annotation's web service feature. If a JAX-WS implementation encounters an unsupported or unrecognized feature annotation, an error must be given. JAX-WS doesn't define any standard portable web service feature for Service references. But it defines @javax.xml.ws.soap.Addressing, @javax.xml.ws.soap.MTOM, @javax.xml.ws.RespectBinding annotations for SEI proxy references.
Modify the example with the following:
The same annotation can also be used to declare a SEI proxy reference, the injected SEI proxy reference is configured with MTOM feature:

   @MTOM
   @WebServiceRef(name="java:comp/env/service/AddressBookService", AddressBookService.class)
   AddressBookPort port;
   Address address = port.getAddress("John Doe");
Modify the the following for Java EE version:
If the name attribute is not specified in this annotation then default naming rules apply as specified in the Java EE specification.
Add the following:
By using a web service feature annotation explicitly along with a @WebServiceRef, an application overrides WSDL's indication of that feature for the reference. Also, <enable-mtom>, <addressing>, and <respect-binding> deployment descriptor elements can be used to override the @MTOM, @Addressing, and @RespectBinding features respectively for a reference.
Add the following:
@WebServiceRef instances are not guaranteed to be thread safe. If the instances are accessed by multiple threads, usual synchronization techniques can be used to support multiple threads.

4.2.4.1 Stub/proxy access

Add the following JAX-WS methods:
public <T> T getPort(Class<T> serviceEndpointInterface, WebServiceFeature... features);

public <T> T getPort(EndpointReference endpointReference, Class<T> serviceEndpointInterface, WebServiceFeature... features);

public <T> T getPort(QName portName, Class<T> serviceEndpointInterface, WebServiceFeature... features);

4.2.4.5 Service method use with partial WSDL

Add the following to JAX-WS methods:
<T> Dispatch<T> createDispatch(QName portName, Class<T> type, Service.Mode mode, WebServiceFeature... features);

Dispatch<Object> createDispatch(QName portName, JAXBContext context, Service.Mode mode, WebServiceFeature... features);

<T> Dispatch<T> createDispatch(EndpointReference endpointReference, Class<T> type, Service.Mode mode, WebServiceFeature... features);

Dispatch<Object> createDispatch(EndpointReference endpointReference, JAXBContext context, Service.Mode mode, WebServiceFeature... features);

4.2.4.6 Service method use with no WSDL

Add the following JAX-WS methods:
<T> Dispatch<T> createDispatch(QName portName, Class<T> type, Service.Mode mode, WebServiceFeature... features)

Dispatch<Object> createDispatch(QName portName, JAXBContext context, Service.Mode mode, WebServiceFeature... features)

<T> Dispatch<T> createDispatch(EndpointReference endpointReference, Class<T> type, Service.Mode mode, WebServiceFeature... features)

Dispatch<Object> createDispatch(EndpointReference endpointReference, JAXBContext context, Service.Mode mode, WebServiceFeature... features)

4.2.4.7 Service Interface method behavior

Add the following to Table 3:
Method Full WSDL Partial WSDL No WSDL
Dispatch<java.lang.Object> createDispatch(EndpointReference endpointReference,
java.lang.Class<T> type, Service.Mode mode, WebServiceFeature... features)
NormalNormalNormal
<T> Dispatch<T> createDispatch(EndpointReference endpointReference,
javax.xml.bind.JAXBContext context, Service.Mode mode,
WebServiceFeature... features)
NormalNormalNormal
<T> Dispatch<T>createDispatch(javax.xml.namespace.QName portName,
java.lang.Class<T> type, Service.Mode mode)
NormalNormalNormal
<T> Dispatch<T>createDispatch(javax.xml.namespace.QName portName,
javax.xml.bind.JAXBContext context, Service.Mode mode,
WebServiceFeature... features)
NormalNormalNormal
<T>T getPort(java.lang.Class<T> serviceEndpointInterface,
WebServiceFeature... features)
NormalNormalUnspecified
<T>T getPort(EndpointReference endpointReference,
java.lang.Class<T> serviceEndpointInterface, WebServiceFeature... features)
NormalUnspecifiedUnspecified
<T> T getPort(javax.xml.namespace.QName portName,
java.lang.Class<T> serviceEndpointInterface, WebServiceFeature... features)
NormalUnspecifiedUnspecified

4.2.10 MTOM/XOP Support

Add references to new JAX-WS sections that talk about @MTOM, MTOMFeature:
Refer to 6.5.2, 7.14.2, and 10.4.1.1 sections of JAX-WS 2.2 specification.
Rewrite the last paragraph as follows:
SOAP MTOM/XOP mechanism on the client can be enabled or disabled by any one of the following ways:
Add the following:
Deployment descriptor mtom elements override the @MTOM annotation for a corresponding SEI instance.

Table : Relationship between deployment descriptor elements and @MTOM

Deployment Descriptor elements @MTOM
<service-ref>/<port-component-ref>/<enable-mtom> @MTOM.enabled
<service-ref>/<port-component-ref>/<mtom-threshold> @MTOM.threshold

4.2.13 Web Services Addressing support

JAX-WS clients are required to support Web Services Addressing 1.0 - Core, Web Services Addressing 1.0 - Soap Binding, and Web Services Addressing 1.0 - Metadata.

Web Service Addressing requirements for a client can be specified by any one of the following ways:

The above order also defines a precedence order for the addressing requirements. For example, the addressing requirements specified by the @Addressing are overridden by the same from a corresponding <port-component-ref>/<addressing> deployment descriptor element.

Table : Relationship between deployment descriptor elements and @Addressing

Deployment Descriptor elements @Addressing
<service-ref>/<port-component-ref>/<addressing>/<enabled> @Addressing.enabled
<service-ref>/<port-component-ref>/<addressing>/<required> @Addressing.required
<service-ref>/<port-component-ref>/<addressing>/<responses> @Addressing.responses

JAX-WS specifies an abstract javax.xml.ws.EndpointReference that represents a remote reference to a web service endpoint. javax.xml.ws.addressing.W3CEndpointReference class is a concrete EndpointReference implementation for WS-Addressing 1.0 - Core addressing version. Client applications can use an EndpointReference to get a port for an SEI using the getPort methods on javax.xml.ws.Service class. Also these EndpointReference objects can appear as SEI method parameters or return type and can be passed across the applications.

A port's EndpointReference can be got using its javax.xml.ws.BindingProvider's getEndpointReference method. Occasionally, it is necessary for one application component to create an EndpointReference for another web service endpoint. The W3CEndpointReferenceBuilder class provides a standard API for creating W3CEndpointReference instances for web service endpoints. When creating a W3CEndpointReference for an endpoint published by the same Java EE application, a JAX-WS runtime must fill the address(if not set by the application) of the endpoint using its service and port names.

4.2.14 RespectBinding Support

The javax.xml.ws.RespectBinding annotation or its corresponding javax.xml.ws.RespectBindingFeature web service feature is used to control whether a JAX-WS implementation must respect/honor the contents of the wsdl:binding in the WSDL that is associated with the service. See 6.5.3 and 7.14.3 sections in JAX-WS 2.2 specification.

RespectBinding web service feature on the client can be enabled or disabled by any one of the following ways:

Deployment descriptor <respect-binding> element overrides the @RespectBinding annotation for a corresponding SEI instance.

Table : Relationship between deployment descriptor elements and @RespectBinding

Deployment Descriptor elements @RespectBinding
<service-ref>/<port-component-ref>/<respect-binding>/<enabled> @RespectBinding.enabled

5.3.2 Service Implementation Bean

Rewrite the first paragraph as follows:
A service implementation bean for a web service can be implemented as follows: The programming models are fully defined in sections 5.3.2.3 and 5.3.2.4.
Rewrite the second paragraph as follows:
A container may use any bean instance to service a request. In a container that also includes support for JSR-299, an implementation must support use of JSR-299 beans as JAX-WS web service classes in an application. JAX-WS annotations may be directly applied to JSR-299 beans and the JAX-WS implementation must use JSR-299 APIs to obtain bean instances.

5.3.2.1 javax.jws.WebService annotation

Modified as follows to reflect Singleton EJB requirements:
For Stateless or Singleton Session EJBs using this annotation, the name attribute of the javax.ejb.Stateless or javax.ejb.Singleton annotation on the Service Implementation Bean class must be used as the <ejb-link> element in the deployment descriptor to map the Port component to the actual EJB. If name attribute in javax.ejb.Stateless or javax.ejb.Singleton annotation is not specified, then the default value is used as defined in the section 4.4.1 of EJB 3.1.
Modified text:
javax.jws.WebService annotated Service Implementation Beans can be run either as a Stateless or Singleton Session EJB in an EJB container or as a JAX-WS service endpoint in a web container. The two programming models are fully defined in sections 5.3.2.3 and 5.3.2.4.

5.3.2.2 javax.xml.ws.Provider interface and javax.xml.ws.WebServiceProvider annotation

Modified as follows to reflect Singleton EJB requirements:
For Stateless or Singleton Session EJBs using this annotation, the name attribute of the javax.ejb.Stateless or javax.ejb.Singleton annotation on the Service Implementation Bean class must be used as the <ejb-link> element in the deployment descriptor to map the Port component to the actual EJB. If name attribute in javax.ejb.Stateless or javax.ejb.Singleton annotation is not specified, then the default value is used as defined in the section 4.4.1 of EJB 3.1.
Modified as follows to reflect Singleton EJB requirements:
javax.xml.ws.WebServiceProvider annotated Service Implementation Beans can be run either as a Stateless or Singleton Session EJB in an EJB container or as a JAX-WS service endpoint in a web container. The two programming models are fully defined in sections 5.3.2.3 and 5.3.2.4.

5.3.2.3 EJB container programming model

Add the following:
A Singleton Session Bean, as defined by the EJB 3.1 specification, can be used to implement a JAX-WS Web service to be deployed in the EJB container.
Add the following:
A Singleton Session Bean is intended to be shared and supports concurrent access. The access rules are specified in the 4.8.5 section of EJB 3.1.
Modified as follows to reflect Singleton EJB requirements:
The requirements for creating a Service Implementation Bean as a Stateless or Singleton Session EJB are repeated in part here.
Modified as follows to reflect Singleton EJB requirements:
* A Service Implementation Bean of a Stateless EJB must be a stateless object. The Service Implementation Bean must not save client specific state across method calls either within the bean instance's data members or external to the instance.
Add the following:
* A Service Implementation Bean of Singleton EJB can have a shared state. The singleton session bean instance lives for the duration of the application in which it is created. It maintains its state between client invocations.

5.3.2.3.2 Allowed access to container services

Modified as follows to reflect Singleton EJB requirements:
A stateless or singleton session bean that implements a web service endpoint using the JAX-WS APIs should use the javax.xml.ws.WebServiceContext,
Modified as follows to reflect Singleton EJB requirements:
The WebServiceContext interface allows the stateless or singleton session bean instance to get access to the javax.xml.ws.handler.MessageContext. Usage of a WebServiceContext must meet the requirements defined by the JAX-WS specification section 5.3.

5.3.2.3.3 javax.ejb.Singleton annotation

EJB 3.1 introduces Singleton session bean component that provides an easy access to shared state. A Singleton session bean is instantiated once per application. A Singleton session bean must be annotated with the javax.ejb.Singleton annotation or denoted in the deployment descriptor as a singleton session bean.

The full requirements for Singleton Session Bean are defined in the section 4.8 of EJB 3.1 specification.

5.3.7 MTOM/XOP support

Add references to new JAX-WS sections that talk about @MTOM, MTOMFeature:
Refer to 6.5.2, 7.14.2, and 10.4.1.1 sections of JAX-WS specification.
Rewrite the last two paragraphs as follows:
SOAP MTOM/XOP mechanism on the service can be enabled or disabled by any one of the following ways: Deployment descriptor mtom elements override the @MTOM annotation for a corresponding service. These elements also override if MTOM enabled protocol binding is used. In other words, if MTOM enabled protocol binding is used along with <enable-mtom> set to false, then this feature is disabled. This deployment descriptor must be specified in order to be applied to the protocol binding to enable or disable MTOM. Note that JAX-WS recommends the use of MTOM feature instead of mtom enabled bindings:SOAPBinding.SOAP11HTTP_MTOM_BINDING, SOAPBinding.SOAP12HTTP_MTOM_BINDING.

Table : Relationship between deployment descriptor elements and @MTOM

Deployment Descriptor elements @MTOM
<service>/<port-component>/<enable-mtom> @MTOM.enabled
<service>/<port-component>/<mtom-threshold> @MTOM.threshold

5.3.8 Web Services Addressing support

JAX-WS services are required to support Web Services Addressing 1.0 - Core, Web Services Addressing 1.0 - Soap Binding, and Web Services Addressing 1.0 - Metadata.

Web Service Addressing requirements for a service can be specified by any one of the following ways:

The above order also defines a precedence order for the addressing requirements. For example, the addressing requirements specified by the @Addressing are overridden by the same from a corresponding <port-component>/<addressing> deployment descriptor element.

Table : Relationship between deployment descriptor elements and@Addressing

Deployment Descriptor elements @Addressing
<service>/<port-component>/<addressing>/<enabled> @Addressing.enabled
<service>/<port-component>/<addressing>/<required> @Addressing.required
<service>/<port-component>/<addressing>/<responses> @Addressing.responses

JAX-WS specifies an abstract javax.xml.ws.EndpointReference that represents a remote reference to a web service endpoint. javax.xml.ws.addressing.W3CEndpointReference class is a concrete EndpointReference implementation for WS-Addressing 1.0 - Core addressing version. Also these EndpointReference objects can appear as SEI method parameters or return type and can be passed across the applications.

A service's EndpointReference can be got using WebServiceContext's getEndpointReference method during service invocation. Occasionally, it is necessary for one application component to create an EndpointReference for another web service endpoint. The W3CEndpointReferenceBuilder class provides a standard API for creating W3CEndpointReference instances for web service endpoints. When creating a W3CEndpointReference for an endpoint published by the same Java EE application, a JAX-WS runtime must fill the address(if not set by the application) of the endpoint using its service and port names.

5.3.9 RespectBinding support

The javax.xml.ws.RespectBinding annotation or its corresponding javax.xml.ws.RespectBindingFeature web service feature is used to control whether a JAX-WS implementation must respect/honor the contents of the wsdl:binding in the WSDL that is associated with the service. See 6.5.3 and 7.14.3 sections in JAX-WS 2.2 specification.

RespectBinding web service feature on a service can be enabled or disabled by any one of the following ways:

Deployment descriptor <respect-binding> element overrides the @RespectBinding annotation for the corresponding service.

Table : Relationship between deployment descriptor elements and @RespectBinding

Deployment Descriptor elements @RespectBinding
<service>/<port-component>/<respect-binding>/<enabled> @RespectBinding.enabled

5.4 Packaging

Modified as follows to reflect Singleton EJB requirements:
Port components may be packaged in a WAR file, or in a EJB-JAR file. Port components packaged in a WAR file must use a JAX-RPC/JAX-WS Service Endpoint or a Stateless/Singleton session bean for the Service Implementation Bean. Port components packaged in a EJB-JAR file must use a Stateless or Singleton Session Bean for the Service Implementation Bean.

5.4.2 EJB Module Packaging

Modified as follows to reflect EJB packaging requirements:
Stateless or Singleton Session EJB Service Implementation Beans can be packaged in an EJB-JAR or in a WAR that contains the class files and WSDL files. The packaging rules follow those defined by the EJB specification. In addition, the Web services deployment descriptor location within the EJB-JAR file is META-INF/webservices.xml and the wsdl directory is located at META-INF/wsdl. See 5.4.3 section for packaging Stateless or Singleton session beans in a WAR file.

5.4.3 Web App Module Packaging

Modified as follows to reflect EJB packaging requirements:
JAX-RPC/JAX-WS Service Endpoints or Statesless/Singleton EJB service implementation beans can be packaged in a WAR file that contains the class files and WSDL files. The packaging rules for the WAR file are those defined by the Servlet specification. The packaging rules for Statless or Singleton EJB within a WAR are defined by the EJB specification. In addition, a Web services deployment descriptor is located in a WAR at WEB-INF/webservices.xml and the wsdl directory is located at WEB-INF/wsdl.

6.2.2 Programming Model

Add the following:
In a container that also includes support for JSR-299, an implementation must support use of JSR-299 beans as JAX-WS handler classes in an application. The JAX-WS implementation must use JSR-299 APIs to obtain handler instances.

7.1.2 Developer responsibilities

Modified as follows to reflect Singleton EJB requirements:
Service Implementations using a stateless or singleton session bean may use EJB annotations with no deployment descriptor file. If the EJB annotations are not specified then the stateless or singleton session bean must be defined in the ejb-jar.xml deployment descriptor file using the session element.
Modified as follows to reflect Singleton EJB requirements:
For a stateless or singleton session bean implementation, the ejb-link element associates the port-component with a session element in the ejb-jar.xml.
Add the following:
* Addressing support. The developer may specify an addressing support for the port-component by using addressing element when JAX-WS based runtime is used.
Add the following:
* RespectBinding support. The developer may specify a respect binding support for the port-component by using respect-binding element when JAX-WS based runtime is used.

7.1.5 Web Services Deployment Descriptor XML Schema

Rewrite as follows:
The XML Schema for the Web service deployment descriptor is available at http://java.sun.com/xml/ns/javaee/javaee_web_services_1_3.xsd
Remove the inline schema as it is replaced by a link:

7.2.2 Developer responsibilities

Add the following:
* Addressing support. The developer may specify an addressing support for the port-component-ref by using addressing element when JAX-WS based runtime is used.
Add the following:
* RespectBinding support. The developer may specify a respect binding support for the port-component-ref by using respect-binding element when JAX-WS based runtime is used.

7.2.5 Web Services Client Service Reference XML Schema

Rewrite as follows:
This section defines the XML Schema for the service-ref at http://java.sun.com/xml/ns/javaee/javaee_web_services_client_1_3.xsd. This schema is imported into the common Java EE 6 schema and is used by the application client, web, and EJB module deployment descriptor schemas to declare service-refs. See the Java EE 6, Servlet 3.0, and EJB 3.1 specifications for more details on specifying a service-ref in the deployment descriptors.
Remove the inline schema as it is replaced by a link:

8.1 Overview

Modified as follows to reflect Singleton EJB requirements:
* Stateless or Singleton session bean Web services are packaged within an EJB-JAR or WAR file.
Modified as follows to reflect Singleton EJB requirements:
If the implementation is a stateless or singleton session bean, the deployment tool has a variety of options available to it. In general, the deployment tool generates a servlet to handle parsing the incoming SOAP request, the servlet obtains a reference to an instance of an appropriate EJBObject and dispatches the request to the stateless or singleton session EJB.

8.1.1 JAX-WS HTTP SPI for deployment

JAX-WS 2.2 introduces HTTP SPI that allows a deployment to use any available JAX-WS web services runtime for HTTP transport. This allows 109 implementations to use the JAX-WS 2.2 runtime in a Java SE platform when it is available. For more details on the HTTP SPI, see the section 6.6 of JAX-WS specification.

8.2.2 Generate Web Service Implementation classes

Modified as follows to reflect Singleton EJB requirements:
Generation of any run-time classes the container requires to support a JAX-RPC or JAX-WS Service Endpoint or Stateless Session Bean or Singleton Bean Service Implementation is provider specific.
Add the following:
A Singleton Bean Service Implementation must match the behavior defined by the javax.ejb.Singleton annotation or <session> element and the <assembly-descriptor> in the ejb-jar.xml deployment descriptor.

8.2.10 Deployment failure conditions

Modified as follows to reflect Singleton EJB requirements:
* Stateless or Singleton session bean Web services are not packaged within an EJB-JAR or WAR file.

9.3.1 Authentication

Add the following clarification to BASIC-AUTH :
Also, these containers must provide a way to configure each instance of the generated static stub or dynamic proxy implementation with credential information.

Appendix C. References

Add the following:

Accepted Changes

None

Deferred Changes

None