Use of JCP site is subject to the JCP Terms of Use and the Oracle Privacy Policy

JSR-109 Web Services for Java EE, Version 1.2 Maintainance Review

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

Description

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

Maintenance Lead

Dhiru Pandey, Sun Microsystems, Inc.

Feedback

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

Rationale for proposed changes

The main goal of this maintenance release is to align JSR-109 to the latest Web Services specification i.e. JAX-WS 2.0 (http://jcp.org/en/jsr/detail?id=224) and to fix bugs/inconsistencies in the previous version of the specification. From the specification perspective, these changes are minimal and targeted solely to fulfill the above stated goals.

Accepted Changes for Maintenance Review

The changes to the specification are listed below. Each change is numbered for ease of reference.

1.0 Java EE name change

Relevant occurrences of J2EE in the entire 109 specification were changed to Java EE

2.0 JAX-WS changes

Relevant occurrences of JAX-RPC in the entire specification were changed to add JAX-WS to it. This was done to reflect that the 109 specification now also supports JAX-WS which is a follow-on specification to JAX-RPC

3.0 SOAP 1.2 changes

Relevant occurrences of SOAP 1.1 in the entire specification were changed to add SOAP 1.2 to it. This was done to reflect that this specification now also supports SOAP 1.2 via JAX-WS specification

4.0 Client side changes

4.1 Added support for client side annotation to access Web Service (Section 4.2.2)

JSR-109 will require the use of @WebServiceRef annotation with JAX-WS runtime to access a Web Service from the client.

4.2 Changes to support javax.xml.ws.Service Class in JAX-WS (Section 4.2.3)

Service Interface in JAX-RPC was changed to Service Class in JAX-WS. The resulting API changes are documented in this section.

4.3 Changes for JAX-WS properties (Section 4.2.5)

Some security and endpoint address related properties were renamed in JAX-WS. They are documented here.

4.4 Use of javax.xml.ws.Dispatch APIs (Section 4.2.6)

JAX-WS introduces new client side javax.xml.ws.Dispatch APIs. This is a low level API that requires clients to construct messages or message payloads as XML and requires an intimate knowledge of the desired message or payload structure. This is useful in those situations where the client wants to operate at the XML message level. Added section 4.2.6 to allow the use of Dispatch APIs on the client side

4.5 Support for JAX-WS Asynchronous operations (Section 4.2.7)

JAX-WS supports two forms of asynchronous invocations – Polling and Callback. This section was added in the specification to allow usage of both Polling and Callback mechanisms of JAX-WS. Polling invocations are allowed from both within EJBs and Servlets, but Callback invocations are only allowed from Servlets.

4.6 Support for OASIS XML Catalogs specification (Section 4.2.9)

This section on packaging was changed to allow support for OASIS XML Catalogs 1.1 specification

5.0 Server side changes

5.1 Clarification on use of Service Endpoint Interface with JAX-WS (Section 5.3.1)

This section was changed to document that the Service Endpoint Interface (SEI) is no longer required to be provided by the port component developer when JAX-WS is being used.

5.2 Added support for @WebService annotation on Service Implementation Bean (Section 5.3.2.1)

This section was added to detail support for @WebService annotation on Service Implementation Bean. It also provides information on the relationship of the member attributes of this annotation and the deployment descriptor elements.

5.3 Added support for @WebServiceProvider annotation on Service Implementation Bean (Section 5.3.2.2)

This section was added to detail support for javax.xml.ws.Provider interface and @WebServiceProvider annotation on Service Implementation Bean. It also provides information on the relationship of the member attributes of this annotation and the deployment descriptor elements.

5.4 Changes in EJB container programming model (Section 5.2.3.3)

This section was changed to add requirements for creating a Service Implementation Bean as a Stateless EJB when using a JAX-WS based container. It also documents the use of @Stateless annotation from EJB 3.0 specification and lifecycle callback annotations (@PostConstruct and @PreDestroy) from JSR-250 (Common Annotation for Java Platform)

5.5 Web container programming model for JAX-WS (Section 5.3.2.4.2)

This section was added to provide details on Web container programming model for JAX-WS based containers. The programming model is similar to JAX-RPC. It also documents the use of lifecycle callback annotations (@PostConstruct and @PreDestroy) from JSR-250 (Common Annotation for Java Platform) used in JAX-WS.

5.6 Added support for specifying protocol binding (Section 5.3.5)

A JAX-WS implementation must provide support for SOAP1.2/HTTP, SOAP1.1/HTTP and XML/HTTP protocol bindings. It also requires that a JAX-WS implementation provide a facility for the developer to specify the binding. This section was added to support this requirement from JAX-WS.

5.7 Added support for enabling/disabling MTOM/XOP (Section 5.3.6)

JAX-WS compliant implementations are required to support MTOM/XOP specification from W3C. This section was added to provide support for this requirement from JAX-WS.

5.8 Added support for Catalog packaging (Section 5.4.4)

This section on packaging was added to allow support for OASIS XML Catalogs 1.1 specification required by JAX-WS

6.0 Handler related changes

6.1 Changes in Concepts (Section 6.1)

Added some explanation for Logical and Protocol Handlers in JAX-WS

6.2 Changes in Programming Model (Section 6.2.2)

Added a paragraph on HandlerResolver interface of JAX-WS

6.3 Added new section on Handler Lifecycle with JAX-WS (Section 6.2.2.2)

This section was added to show the differences in the lifecycle of Handlers in JAX-WS. Detailed the usage of lifecycle callback annotations @PostConstruct and @PreDestroy.

6.4 Added new section on @HandlerChain annotation (Section 6.2.2.3)

This section details the use of this annotation and also talks about the HandlerResolver interface of JAX-WS

6.5 Clarification in section on Security (Section 6.2.2.4)

Changed the following paragraph here:

“A Handler must not change the message in any way that would cause the previously executed authorization check to execute differently. A Handler.handleRequest() method must not change the operation name, number of parts in the message, or types of the message parts. A container must throw a SOAP fault with a faultcode of soap-env:Server (the namespace identifier for the namespace prefix, soap-env:, is http://schemas.xmlsoap.org/soap/envelope/) back to the client if the Handler does this. Although, not strictly required for security reasons, a Handler.handleResponse() method should not change the number of parts in the message, or types of the message parts. A container should log occurrences of these errors since the client may not be expecting a response (i.e. it may be a one-way invocation).”

“A Handler must not change the message in any way that would cause the previously executed authorization check to execute differently. “

The deleted part of this paragraph is very hard to test and also enforcing this would have significant performance implications. Essentially, what is really required here are the constraints on a handler so that the security checks are executed correctly. The same deletion was also made to the Response part of this section where the language is used is similar and again very hard to test and also enforcing this would have significant performance implications.

6.6 Changes in section on Developer Responsibilities (Section 6.2.3)

This section was changed to update it for JAX-WS Handler specific details

6.7 Changes in section on Container Provider Responsibilities (Section 6.2.4)

This section was changed to update it for JAX-WS Handler specific details

6.8 Changes in section on Packaging (Section 6.3)

Added packaging requirements for handler chain file used in @HandlerChain annotation.

7.0 Deployment Descriptor changes

7.1 Changes in section on server side Developer Responsibilities (Section 7.1.2)

Added description of new deployment descriptor elements like <wsdl-service>, <enable-mtom>, <protocol-binding>, <handler-chains>. Also clarified that JAX-RPC mapping file is no longer required when JAX-WS runtime is being used.

7.2 Changes in section on Web Services Deployment Descriptor XML Schema (Section 7.1.5)

Removed the old schema and added new updated server side schema.

7.3 Changes in section on client side Developer Responsibilities (Section 7.2.2)

Clarified that JAX-RPC mapping file is no longer required when JAX-WS runtime is being used.

7.4 Changes in section on Web Services Client Service Reference XML Schema (Section 7.2.5)

Removed the old schema and added new updated client side schema.

7.5 Changes in section on JAX-RPC Mapping Deployment Descriptor (Section 7.3)

Clarified that the JAX-RPC mapping file is not required in JAX-WS since it uses JAXB specification for all its data binding needs.

7.6 Changes in section on Overview of JAX-RPC Mapping Deployment Descriptor (Section 7.3.1)

The language in this paragraph was changed for improving clarity in the specification

If the conditions are not met, a full mapping must be specified. There must be a java-xml-type-mapping for every root WSDL type. An exception-mapping must be created for each WSDL fault. There must be a service-interface-mapping for every service element in the WSDL file that has a Generated Service Interface used by the developer. There must be a service-endpoint-interface-mapping for every combination of portType and binding in the WSDL file. There must be a package-mapping for every namespace defined in the WSDL file.

TO:

If the conditions are not met, a full mapping must be specified. There must be a java-xml-type-mapping for every global type definition that is reachable from the port types (and its attributes like operations, faults, messages etc.) in the WSDL file. An exception-mapping must be created for each WSDL fault. There must be a service-interface-mapping for every service element in the WSDL file that has a Generated Service Interface used by the developer. There must be a service-endpoint-interface-mapping for every combination of portType and binding in the WSDL file. There must be a package-mapping for every namespace defined in the WSDL file.

The language in this paragraph was changed for improving clarity in the specification

Web Services for J2EE providers may support partial mapping specifications (e.g. not providing a method-param-parts-mapping for every method) regardless of the WSDL content by using standard JAX-RPC WSDL to Java mapping rules to resolve the mappings. If mappings are specified, they take precedence over the mapping rules. Such partial mappings are vendor specific and therefore are non-portable.

TO:

Web Services for Java EE providers may support partial mapping specifications (e.g. not providing a method-param-parts-mapping for every method) regardless of the WSDL content by using standard JAX-RPC WSDL to Java mapping rules to resolve the mappings. If mappings are specified, they take precedence over the mapping rules. Applications that use partial mappings are therefore non-portable.

Accepted Changes for Maintenance Review 2

The major changes to the specification are listed below. Each change is numbered for ease of reference.

1.0 Overview changes

1.1 Clarified transaction propagation in section 3.10

2.0 Client side changes

2.1 Clarified that the use of @WebServiceRef not required with JAX-WS (Section 4.2.2)

JSR-109 will not require the use of @WebServiceRef annotation with JAX-WS runtime to access a Web Service from the client. The developer is free to use the standard JNDI lookup mechanism for the same.

2.2 Mapping for <service-ref-type> client descriptor specified (Section 4.2.2)

Mapping between a new client side deployment descriptor <service-ref-type> and @WebServiceRef annotation attribute type was added

2.3 Clarification on usage of @WebServiceRefs was added (Section 4.2.2)

2.4 Added section on JNDI lookups for Ports (Section 4.2.3)

This is similar to using @WebServiceRef for Service endpoints.

2.5 Clarification on JAX-RPC mapping file (Section 4.2.4.5)

Clarified that under JAX-WS runtime, JAX-RPC mapping file if specified is ignored

2.6 Added support for JAX-WS Asynchronous callback operations from EJBs (Section 4.2.8.2)

Asynchronous callback invocations are now allowed from EJBs as well.

2.7 Added a section clarifying interoperability between JAX-RPC and JAX-WS clients (Section 4.2.9)

2.8 Added support for enabling/disabling MTOM/XOP mechanism (Section 4.2.10)

JAX-WS compliant implementations are required to support MTOM/XOP specification from W3C. This section was added to provide support for this requirement from JAX-WS on the client side.

2.9 Added clarification in Packaging section (4.2.12)

Clarified that Web services client deployment descriptor are not required when JAX-WS annotations are used.

3.0 Server side changes

3.1 Clarified uniqueness requirement for @WebService.name in Java EE module (Section 5.3.2.1)

Uniqueness requirement for @WebService.name was removed, but the mapping between <port-component-name> and @WebService.name specifies the uniqueness criterion.

3.2 Clarified mapping for <ejb-link> and <servlet-link>(Section 5.3.2.1, Section 5.3.2.2)

3.3 Clarified mapping rules for Servlet endpoints with no web.xml (Section 5.3.2.1, Section 5.3.2.2)

3.4 Clarified mapping between <service-endpoint-interface> and @WebService.endpointInterface (Section 5.3.2.1)

3.5 Clarified that a WSDL file must be packaged with a Provider implementation (Section 5.3.2.2)

3.6 Clarified the usage of WebServiceContext with Stateless Session bean (Section 5.3.2.3.2)

3.7 Clarified the usage of WebServiceContext with Servlets (Section 5.3.2.4.2.2)

3.8 Disallowed the publishing of Endpoints (Section 5.3.3)

Disallowed both EJB and Servlet containers to publish Endpoints dynamically using javax.xml.ws.Endpoint API

3.9 Added support for new BindingTypes from JAX-WS (Section 5.3.6)

Added support for new BindingTypes (SOAP1.1 over HTTP with MTOM enabled and SOAP1.2 over HTTP with MTOM enabled) from JAX-WS. Also clarified relationship between <protocol-binding> descriptor and javax.xml.ws.BindingType annotation

3.10 Corrected the MTOM deployment descriptor element name and clarified its usage (Section 5.3.7)

3.11 Clarifications in Packaging (Section 5.4)

Added clarifications like - Service Endpoint Interface class is optional with JAX-WS, a Web services deployment descriptor is not required with JAX-WS when annotations are used etc.

3.12 Added clarification on use of TransactionAttribute annotation (Section 5.5)

3.13 Clarifications in packaging regarding mixing of JAX-RPC and JAX-WS components in a module (Section 5.4)

3.14 Clarified mapping relationship between <port-component> and @WebService (Section 5.3.2.1)

3.15 Clarified mapping relationship between <port-component> and @WebServiceProvider (Section 5.3.2.2)

4.0 Handler related changes

4.1 Clarified order of invocation for Handlers and EJB interceptors (Section 6.2.4)

4.2 Clarification for alignment between Handlers and EJB interceptors for EJB endpoints (Section 6.2.4)

This is inline with the alignment between message handlers and interceptors, for EJB based endpoints with both Handlers and EJB Interceptors present, the Map instance returned by invoking WebServiceContext.getMessageContext() method in the JAX-WS Handler, is the same Map instance that is obtained by invoking InvocationContext.getContextData() in the EJB Interceptor.

5.0 Web Services Deployment Descriptor changes

5.1 Clarified that deployment descriptors were optional (Section 7.1.1 and 7.1.2)

5.2 Added new protocol binding tokens (Section 7.1.2)

Added new protocol binding token ##SOAP11_HTTP_MTOM for new binding id introduced in JAX-WS for SOAP1.1 over HTTP with MTOM enabled and ##SOAP12_HTTP_MTOM for SOAP1.2 over HTTP with MTOM enabled.

5.3 Changes in section on Web Services Deployment Descriptor XML Schema (Section 7.1.5)

Changed minOccurs to 1 from 0 for element handlers in handler-chainType

5.4 Clarified that deployment descriptors were optional (Section 7.2.1)

5.5 Added <service-ref-type> deployment descriptor element (Section 7.2.2)

With JAX-WS the <service-ref-type> element declares the type of the service-ref element that is injected or returned when a JNDI lookup is done.

5.6 Added <enable-mtom> deployment descriptor element (Section 7.2.2)

The developer may specify if MTOM/XOP support for the port-component-ref is enabled or disabled

5.7 Changes in section on Web Services Client Service Reference XML Schema (Section 7.2.5)

Changed minOccurs to 1 from 0 for element handlers in handler-chainType, and added <service-ref-type> and <enable-mtom> deployment descriptor elements.

5.8 Fixed comments in both client and server deployment descriptor schema files

6.0 Deployment changes

6.1 Clarified that JAX-WS specification makes no distinction between stubs and proxies (Section 8.2.7)

6.2 Relevant references to deployment descriptor elements or file webservices.xml were fixed to include Web services metadata annotations allowed by JAX-WS