Find JSRs
Submit this Search


Ad Banner
 
 
 
 

Web Services for J2EE, Version 1.0 Change Log

Web Services for J2EE, Version 1.0

Change Log

Document last updated: 07/31/2003

Description

This document describes the set of change requests Proposed, Accepted, and Deferred per the JSPA section 4. These are changes to the Web Services for J2EE Version 1.0 specification and intended to result in a version of the specification for integration with J2EE 1.4.

Maintenance Lead

Jim Knutson, IBM

Feedback

Comments should be sent to wsee-spec-comments@us.ibm.com.

Proposed Changes

All changes to the final release must be listed here and approved by the EC.

Request Summary Specification Changes
21 Add SOAP Header fault mappings Section 7.3.5, add part-name element to exception-mappingType to allow for associating a header fault with the actual header in question (by part-name of the message). This is necessary when more than one header is passed.
22 Add additional JAX-RPC 1.1 type mappings Clarifies request 16 and adds support for mapping attribute elements. Section 7.3.5, add xml-attribute-name element, xml-wildattribute element, and xml-wildcard element to variable-mappingType. These are modeled after xml-element-name use.
23 Clarify how element refs should be handled in variable-mappingType. Section 7.3.5, add the following description to xml-element-name:

The value of an xml-element-name element must match the value of the ref attribute if mapping an element reference.

A similar phrase will be added to xml-attribute-name as part of request 22.
24 Fix java-xml-type-mapping class-type A java-xml-type-mapping can map to more than just a Java class. It can map to primitives and arrays of types. In section 7.3.5, rename class-type to java-type and change its type to j2ee:java-typeType.

Accepted Changes

Changes approved by the EC move to this section.

Request Summary Specification Changes
1 Change version to 1.1 Title page, replace:
Version 1.0
With:
Version 1.1
Page 2, replace
Version: 1.0
With:
Version: 1.1
2 Add EJB 2.1 web services view. Itemize references to EJB remote interface/home interface requirements where the EJB 2.1 web services client view needs to be injected.

Section 3.10, item 1, replace:

The service provider implements the Web service business logic by implementing a stateless session EJB. The EJB�s remote interface method signatures must match the method signatures of the Service Endpoint Interface and must include all methods of the Service Endpoint Interface.

With:

The service provider implements the Web service business logic by creating a stateless session Bean that implements the methods of the Service Endpoint Interface as described in the Enterprise JavaBeans 2.1 specification.

Section 8.1 paragraph 6, replace:

In general, the deployment tool generates a servlet to handle parsing the incoming SOAP request, create a remote stateless session EJBObject and dispatch the request to the stateless session EJB. The methods of the SEI are described by the remote interface, the deployment tool can generate a servlet that dispatches to the remote interface of the EJB.

With:

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 session EJB.
3 Make EJB 2.0 based web services optional. Itemize references to EJB remote interface/home interface requirements that need to be made optional. Optional support for J2EE 1.3 based web services is accomplished by referring to the original Web Services for J2EE 1.0 specification.

Section 3.10 item 1, remove:

The EJB�s remote interface method signatures must match the method signatures of the Service Endpoint Interface and must include all methods of the Service Endpoint Interface.

Section 5.3.2.1.3, remove entire section:

5.3.2.1.3 Exposing an existing EJB
An existing Enterprise JavaBean may be used as a Service Implementation Bean if it meets the following requirements:
� The business methods of the EJB bean class that are exposed on the SEI must meet the Service Implementation Bean requirements defined in section 5.3.1.
� The Service Endpoint Interface methods must be a subset of the remote interface methods of the EJB and the SEI must meet the requirements described in the JAX-RPC specification for Java->WSDL mapping.
� The transaction attributes of the SEI methods must not include Mandatory.
The developer must package the Web service as described in section 5.4 and must specify an ejb-link from the port in the Web services deployment descriptor to the existing EJB.

Section 8.1, 3rd bullet, remove:

If the Service Implementation Bean is an EJB, the SEI methods are fully contained by the remote interface.
Section 8.2.9, bullet 7, remove:
If the Service Implementation Bean is an EJB, the SEI methods are not fully contained by the remote interface.
Add Appendix:
Optional support for J2EE 1.3 platforms

Web Services for J2EE Version 1.1 does not require support for applications built according to the Web Services for J2EE Version 1.0 specification. A vendor may optionally support Web Services for J2EE 1.0 by implementing that version of the specification. See the Web Services Version 1.0 Change Log for more details on the differences between the two specifications.

4 Add J2EE 1.4 based XML Schemas Create new Chapter 7 info with XML Schema specific info. Describe the general 1-1 mapping of DTD to XML Schema elements for most elements and detail where it isn't 1-1 and why.

Section 7.1.5, replace DTD with XML Schema

Section 7.2.2, 4th bullet, remove:

Scope. If the service reference is being defined within an EJB-JAR, the service-ref elements must be defined within a component-scoped-refs element so that the service-ref can be associated with a particular EJB. The association with the EJB is defined by the component-name element.

Section 7.2.2?, add note regarding service-endpoint declaration in EJB 2.1 deployment descriptor.

Section 7.2.5, replace DTD with XML Schema.

Section 7.3.5, replace section name:

JAX-RPC Mapping DTD
with:
JAX-RPC Mapping Schema
Section 7.3.5: replace DTD with XML Schema.
5 Make the DTD based schemas optional. See Appendix change in item 3.
6 Make Holders required for EJB container. Modify statement saying that Holders are optional for the EJB container to say they are optional only for an EJB 2.0 container.

Section 5.3, first definition list item, move the following to the appendix:

Support for OUT and IN/OUT parameters is optional for the EJB container.

Section 5.3, second definition list item, move the following to the appendix:

Support for Holder parameters is optional for the EJB container.

Section 5.3.1, move the last paragraph to the appendix:

JAX-RPC defines Holders as non-serializable classes which cannot be implemented by the remote interface of an Enterprise JavaBean. Therefore, support for an SEI which uses Holders for parameters is not required for Port components deployed in the EJB container
7 Make Handler support required for EJB container Remove statement saying that Handlers are optional for the EJB container.

Section 6.1, last paragraph, remove:

This specification makes Handler support in the EJB container optional due to the required EJB container changes that would be necessary to implement Handler support. It is expected that EJB Handler support will be made required in a future J2EE specification.

Section 6.2.4, last paragraph, remove:

A container provider is not required to support Handlers for Port component�s that run in the EJB container. It is expected this will be required when this specification is included in J2EE 1.4.
8 Change references to extension of J2EE 1.3 to include integration into J2EE 1.4 Chapter 2, last paragraph, remove:
The relation of this specification to J2EE 1.4 is defined in Appendix A.
Section 2.1.3, second bullet, replace:
The Web service deployment is supported on top of existing J2EE 1.3 environments.
With:

The Web service deployment is supported on J2EE 1.4 environments.

Appendix A, J2EE APIs, replace:

Enterprise JavaBeans 2.0 defines the programming model for implementing Web services which run in the EJB container.
Servlet 2.3 defines the packaging and container service model for implementing Web services which run in the servlet container.
J2EE 1.4, EJB 2.1, and Servlet 2.4 will include the Web services specification defined within this specification. An effort will be made to maintain compatibility and ease migration to J2EE 1.4, but there is no guarantee that compatibility will be ensured. A JSR 109 1.1 maintenance release will address XML Schema based deployment descriptors, the EJB 2.1 Web services view, as well as Holder and Handler class usage in the EJB container for use by J2EE 1.4

With:

Enterprise JavaBeans 2.1 defines the programming model for implementing Web services which run in the EJB container.

Servlet 2.4 defines the packaging and container service model for implementing Web services which run in the servlet container.

9 Clarify port address requirement. Section 4.2.2.4, replace:

The port address attribute may be absent from the WSDL or may be a dummy value.

with:

The port address location attribute may be absent from the WSDL or may be a dummy value.

10 Clarify publication requirements.

Section 4.2.6, replace:

WSDL files are located relative to the root of the module and are typically co-locatedwith the module's deployment descriptor.

with:

WSDL files are located relative to the root of the module and are typically located in the wsdl directory that is co-located with the module deployment descriptor or a subdirectory of it.
Section 5.4, replace:
WSDL files are located relative to the root of the module and are typically co-located with the module deployment descriptor.
with:
WSDL files are located relative to the root of the module and are typically located in the wsdl directory that is co-located with the module deployment descriptor or a subdirectory of it.
Add new section 5.4.1 before current 5.4.1 (renumber appropriately):

5.4.1                     The wsdl directory

The wsdl directory is a well-known location that contains WSDL files and any relative content the WSDL files may reference. WSDL files and their relative references will be published during deployment. See section 8.2.4 and 8.2.5 for more details.

Add to the end of old section number 5.4.1 EJB Module Packaging (now 5.4.2):

The wsdl directory is located at META-INF/wsdl.

Add to the end of old section number 5.4.2 Web App Module Packaging (now 5.4.3):

The wsdl directory is located at WEB-INF/wsdl.

Add to section 7.1.2 Port's WSDL description bullet:
The WSDL file may reference (e.g. import) other files contained within the module using relative references. It may also reference other files external to the module using an explicit URL. Relative imports are declared relative to the file defining the import. Imported files may import other files as well using relative locations or explicit URLs. It is recommended that the WSDL file and relative referenced files be packaged in the wsdl directory as described in section 5.4.1. Relative references must not start with a �/�.
Add to section 7.2.2 WSDL definition bullet:
The WSDL file may reference (e.g. import) other files contained within the module using relative references. It may also reference other files external to the module using an explicit URL. Relative imports are declared relative to the file defining the import. Imported files may import other files as well using relative locations or explicit URLs. Relative references must not start with a �/�.

Section 8.2.3, add to end of first paragraph:

The container must not update a WSDL file located in the document root of a WAR file.

Add new section 8.2.4:

8.2.4                     Publishing the service-ref WSDL

The deployment tool and/or container must make the WSDL document that a service-ref is bound to available via a URL returned by the Service Interface getWSDLDocumentLocation() method. This may or may not be the same WSDL document packaged in the module. The process of publishing the bound service-ref WSDL is analogous to publishing deployed WSDL, but only the service-ref that is bound to it is required to have access to it. A Web Services for J2EE provider is required to provide a URL that maintains the referential integrity of the WSDL document the service-ref is bound to if the wsdl-file element refers to a document located in the wsdl directory or one of its subdirectories.

Add to the end of section 8.2.5 (was 8.2.4):

A Web Services for J2EE provider is required to support publishing a deployed WSDL document if the Web services deployment descriptor (webservices.xml) wsdl-file element refers to a WSDL file contained in the wsdl directory or subdirectory, as described in section 5.4.1. A provider may publish the static content (e.g. no JSPs or Servlets) of the entire wsdl directory and all its subdirectories if the deploy tool cannot compute the minimal set of documents to publish in order to maintain referential integrity. The recommended practice is to place WSDL files referenced by awsdl-file element and their relative imported documents under the wsdl directory.

Web Services for J2EE providers are free to organize the published WSDL documents however they see fit so long as referential integrity is maintained. For example, the wsdl directory tree may be collapsed to a flat published directory structure (updating import statements appropriately). Clients should not depend on the wsdl directory structure being maintained during publication. Access to relatively imported documents should only be attempted by traversing the published WSDL document at the location chosen by the deployer.
11Clarify resource access from handlersSection 6.2.3, replace:
A Handler may access transactional resources in a local transaction mode.

with

A Handler may access transactional resources defined by a component's resource-refs. Resources are accessed under a transaction context according to section 6.2.2.3.
12Clarify request 9

Section 4.2.24, replace:

The port address location attribute may be absent from the WSDL or may be a dummy value.

with:

The port address location attribute of a port using a SOAP/HTTP binding must begin with http: or https:.
Section 8.1, replace:
The WSDL port address for the Port component is the combination of the web app context-root and servlet url-pattern.

with:

The WSDL port address for the Port component is the combination of the web app context-root and url-pattern of the servlet-mapping.
13Correct WSDL filenamesSection (newly renumbered) 8.2.5, replace:
StockQuoteDescription.xml

with:

StockQuoteDescription.wsdl
14Remove redundant text.Section 9.1.1, remove:
J2EE application server can handle the request similar to how it handles other HTTP requests.
15Clarify request 10Section 8.2.5, add:
A vendor may support publication of WSDL files packaged in other locations, but these are considered non-portable.
16Add support for xsd:anyAdd new section 7.3.2.1 Mapping xsd:any:

Mapping for xsd:any is described by the JAX-RPC specification.  JAX-RPC defines this as a mapping to/from javax.xml.soap.SoapElement or an array of type SoapElement. 

17Add support for anonymous typesAdd section 7.3.2.2 Mapping anonymous types:

Anonymous types require some special handling in order to provide a mapping. Anonymous types have no QName, but dealing with mappings, serializers, and deserializers becomes much easier if they are assigned QNames. Anonymous types are treated as root WSDL types with special QNames and are mapped using the java-xml-type-mapping. In order to achieve some portability in determining what anonymous type a java-xml-type-mapping refers to, the following rules must be used.

1.       For type T, the localname of T is determined as follows:

a.        If T has a name attribute, then it's name is the value of the name attribute

b.       If T has no name attribute, then its name is�>E� where E is the name of its enclosing element.

2.       For element E, the localname of E is:

a. If E is at the root level, then the name is �N� where N is the value of the name attribute.

b. If E is not at the root level, then the name �T>N� where T is the name of the enclosing type and N is the value of the name attribute.

3.       If element E has a maxOccurs attribute greater than 1, then it also has a 'hidden' anonymous type called A.  A is an array of the enclosed type.  The name of A is...

a. If E has a name attribute, then the name of A is "E[<minOccursValue>,<maxOccursValue>]" where E is the value of E�s name attribute.

b. If E has no name attribute, then the name of A is "R[<minOccursValue>,<maxOccursValue>]" where R is the name of the referent element.

Note that only root level types and elements have a namespace, so all anonymous types acquire their namespaces from the enclosing root level element or type.

Hidden anonymous array types, as defined in rule 3, are declared in a param-type element as the name of the Java type of type T appended with �[]� if the mapping is to a Java array. This is the only supported and portable mapping for hidden anonymous array types at this time.  

The following example will help illustrate anonymous types and their mappings. Example name rule uses are underlined:

<schema � targetNamespace=�X�>

<complexType1 name=�root�>

      

</complexType>

<element2 name="root" minOccurs="0" maxOccurs="unbounded"3>

    <complexType4>

        <sequence>

            <element5 name="inside" maxOccurs="10"6>

                <complexType7>

                    ...

                </complexType>

            </element>

            <element ref="someOtherElement" maxOccurs="20"8/>

        </sequence>

    </complexType>

</element>

< element9 name=�someOtherElement� type=�xsd:int�>

There are 9 named types. Their names are defined as:

Use case

Rule based name

Based on rule

1

{X}root

Rule 1.a

2

{X}root

Rule 2.a

3

{X}root[0,unbounded]

2 and rule 3.a

4

{X}>root

2 and rule 1.b

5

{X}>root>inside

4 and rule 2.b

6

{X}>root>inside[,10]

5 and rule 3.a

7

{X}>>root>inside

5 and rule 1.b

8

{X}someOtherElement[,20]

9 and rule 3.b

9

{X}someOtherElement

Rule 2.a

 

18Update Interoperability RequirementsSection 3.7, add a bullet:
  • WS-I Basic Profile 1.0
Section 8.1, add a paragraph:
It is recommended that containers provide logging functionality similar to that of the WS-I "Monitor" tool. Such contains would log all incoming and outgoing messages in the format defined by the WS-I Testing Tools group and would allow capturing SOAP messages exchanged over the HTTPS protocol in a way that allows analysis by the WS-I tools.
Section 8.2.1, add a paragraph:
A deployment tool must be able to deploy a WS-I Basic Profile 1.0 compliant application. Validating an application for WS-I Basic Profile 1.0 conformance is considered a value add.
New Section 8.2.5, add a paragraph:
Requirements for publishing WSDL documents to a UDDI V2 directory are described by the WS-I Basic Profile 1.0 specification.
19Correct namespaceSection 6.2.2.2, replace
http://www.w3.org/2001/09/soap-envelope
with:
http://schemas.xmlsoap.org/soap/envelope/
20Clarify interoperability requirementsSection 4.2 and 5.6, add:
The container must comply with the JAX-RPC specification Chapter 14 Interoperability requirements.
Section 6.1, add:
J2EE applications that define one or more port components or service references include WSDL descriptions for each of them as well as application logic and (optionally) SOAP message handlers associated with them. In order for such applications to behave predictably, all three elements (description, handlers and application logic) must be well aligned. Developers should program handlers carefully in order not to create invalid SOAP envelope format that contradicts WS-I BP 1.0 requirements or violates the message schema declared in the WSDL. In particular, containers cannot provide any guarantees beyond those specified as part of the interoperability requirements on the behavior of an application that violates the assumptions embedded in a WSDL document either in its business logic or in SOAP message handlers.

Note: I looked at the Servlet 2.4 PFD and it doesn't appear that any change needs to be made to cover it.

Deferred Changes

Changes deferred by the EC move to this section.