• JSRs by Platform
• JSRs by Technology
• JSRs by Stage
• JSRs by Committee
• List of All JSRs



Register for Site

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


• About JCP
  • Program Overview
  • JCP Process Document
  • Calendar
  • JCP Members
  • Executive Committee
  • Elections
• Get Involved
  • Overview
  • Becoming a JCP Member
  • Java in Education
• Community Resources
  • Overview
  • Tutorials
  • JCP Podcasts
  • Spec Lead Guide
  • TCK Tool & Info
  • License Reference
• Community News
  • News
  • Programs & Awards
  • Press Releases
  • Success Stories
• FAQ
• Contact Us

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

Description

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

Maintainance 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 maintainance 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.

Proposed Changes

The changes to the specification are listed below.

Each change is numbered for ease of reference.

The actual verbiage for most of the changes can be found in the attached specification draft (with change bars) at the section (or sections) mentioned below.

1.0 Java EE name change

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

2.0 JAX-WS changes

Relevant occurances 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 occurances 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 lifecyle 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 lifecyle 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).”

TO

“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.