Maintainance Review for JSR-109 Web Services for Java EE, Version 1.2
Dhiru Pandey, Sun Microsystems, Inc.
Comments should be sent to jsr109-spec-comments@sun.com
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.
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.
Relevant occurances of J2EE in the entire 109 specification were changed to Java EE
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
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
JSR-109 will require the use of @WebServiceRef annotation with JAX-WS runtime to access a Web Service from the client.
Service Interface in JAX-RPC was changed to Service Class in JAX-WS. The resulting API changes are documented in this section.
Some security and endpoint address related properties were renamed in JAX-WS. They are documented here.
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
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.
This section on packaging was changed to allow support for OASIS XML Catalogs 1.1 specification
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.
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.
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.
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)
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.
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.
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.
This section on packaging was added to allow support for OASIS XML Catalogs 1.1 specification required by JAX-WS
Added some explanation for Logical and Protocol Handlers in JAX-WS
Added a paragraph on HandlerResolver interface of JAX-WS
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.
This section details the use of this annotation and also talks about the HandlerResolver interface of JAX-WS
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.
This section was changed to update it for JAX-WS Handler specific details
This section was changed to update it for JAX-WS Handler specific details
Added packaging requirements for handler chain file used in @HandlerChain annotation.
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.
Removed the old schema and added new updated server side schema.
Clarified that JAX-RPC mapping file is no longer required when JAX-WS runtime is being used.
Removed the old schema and added new updated client side schema.
Clarified that the JAX-RPC mapping file is not required in JAX-WS since it uses JAXB specification for all its data binding needs.
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.