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

JAX-RPC 1.1 Change Log

Java^TMAPI forXML-based RPC 1.1 Change Log

March 12th, 2003
(Updated: April 11th, 2003)
(Updated with approved changes 25 April 2003)

Description

Maintenance revision of the Java^TMAPI for XML-based RPC, version 1.1.

Maintenance Lead

Roberto Chinnici, Sun Microsystems, Inc.

Feedback

Comments should be sent to jsr-101-leads@sun.com.

Proposed changes

The main goal for JAX-RPC 1.1 is to add support for the WS-I BasicProfile 1.0.

Additional goals include fixing some bugs/inconsistencies in the previous version of the specification and making some limited additions to the APIs as requested by users and implementors of JAX-RPC 1.0.

Accepted changes

(Changes accepted by the EC will be moved to this section.)

The sections below correspond to different logical areas in JAX-RPC and don't necessarily match the outline of the JAX-RPC 1.0 specification.

Each change is numbered for ease of reference.

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

1 Mapping Between Java and WSDL (Excluding Data Binding)

The goal of this set of changes is to ensure that JAX-RPC 1.1 tools are capable of producing and consuming WSDL documents which are WS-I Basic Profile 1.0-conformant.

1.1 Add support for rpc/literal -- sections 6.2 and 6.4
The explanation of "wrappers" in section 6.2 must be removed because it conflicts with rpc/literal.
Support for the rpc/literal style in the SOAP binding will be required.
A detailed description of all the rules for the different styles possible in a SOAP binding is deferred to the interoperability requirements section.

1.2 Add mapping for literal faults -- section 4.3.6
Literal faults are mapped to Java exceptions in the usual way. The main difference is that they point to a message part which uses the "element" attribute, so we have to take that into account when deriving a Java type from it.

1.4 Add mapping for headerfaults -- section 6.6
When the explicit service context option is used on some header, all its headerfaults must be mapped to exceptions just like ordinary faults are.

1.5 Add full support for one-way operations -- javadocs and sections 5.5.5, 8.2.4.1, 10.1.2
Specify that methods with void return type and not throwing any checked exceptions aside from RemoteException may be mapped to one-way operations.
Tools need to provide an option (via metadata) to map methods of the kind listed above to one-way operations.
Specify that Call.invokeOneWay() should wait until a HTTP response code is received from the server when using SOAP/HTTP.
Specify that in the servlet-based case, implementations must return a HTTP response code before dispatching a one-way request to a servlet endpoint instance (so as not to block clients during processing).

2 Data Binding and Support for XML Schema

In this section we detail changes related to the data binding support in JAX-RPC.

2.1 Add mapping of the xsd:anyURI schema type to either the java.net.URIclass in J2SE 1.4 or java.lang.String -- section 4.2.1

2.2 Add mapping of the java.net.URI class in J2SE 1.4 to xsd:anyURI schematype -- sections 5.1.3 and 5.3.2
This change complements 2.1.

2.3 Add mapping of the javax.xml.namespace.QName class to xsd:QName --sections 5.1.3 and 5.3.2
This mapping was apparently omitted from the 1.0 specification.

2.4 Add support for mapping additional predefined XML Schema simple types to Java types -- section 4.2.1
The types xsd:NOTATION, xsd:ENTITY and xsd:IDREF are specifically excluded.

2.5 Add support for simple types derived via restriction from a supported simple type -- section 4.2.5
Simple types derived by restriction from a supported simple type and for which there is no predefined mapping (i.e.enumerations) are mapped to the same Java type their base type is mapped to.
In other words, if simple type ns:Foo is derived from ns2:Bar and there are no explicit rules to define the mapping (i.e. ns:Foo is not an enumeration type), then it should be mapped to the same Java type that ns2:Bar was mapped to. In particular, this applies when ns2:Bar is a predefined schema type.

2.6 Add support for simple types defined using xsd:list -- section 4.2.6
They are mapped to the java.util.List class.

2.7 Add support for complex type definitions defined using xsd:simpleContent -- section 4.2.3
The content of the element will appear as an additional property of the enclosing value type with a default name of "value".

2.8 Add support for attributes of a complex type -- section 4.2.3
Attributes are mapped to properties of value types.

2.9 Add support for wildcards (xsd:any) -- section 4.2.3
For analogy with the natural mapping of xsd:anyType, xsd:any is mapped to the javax.xml.soap.SOAPElement class.
If the wildcard has maxOccurs>1 then it is mapped to javax.xml.soap.SOAPElement[].

2.10 Add support for anonymous complex types -- sections 4.2.3 and 4.3.12
Anonymous types are mapped to Java types.
By default, the name of the nearest enclosing xsd:element, xsd:simpleType or xsd:complexType should be used to derive the name of the Java type.
New collision resolution rules are defined for Java classes that are derived from a xsd:element.

2.11 Add support for anonymous enumerations -- section 4.2.4
Anonymous enumerations are mapped by default to type safe Java enumeration classes.
The name of the nearest enclosing xsd:element, xsd:attribute, xsd:simpleType or xsd:complexType should be used to derive the name of the Java type.
New collision resolution rules are defined for Java classes that are derived from an enumeration type.
In order to be compatible with JAXB 1.0, implementations must support mapping anonymous enumerations to their base types.

2.12 Require implementations to support mapping any literal part to javax.xml.soap.SOAPElement -- section 6.4.1
Currently, it's impossible to selectively turn off data binding in JAX-RPC, and this makes using data binding frameworks (e.g. JAXB) in conjunction with JAX-RPC hard in certain cases.
With this change, it is always possible to force a tool (via options and/or metadata) to use the default mapping to javax.xml.soap.SOAPElement for any message part, so that application developers can use their favorite data binding technology.
Note that SAAJ 1.2 will have SOAPElement extend the DOM Element interface, thus allowing a JAXB unmarshaller to process a fragment handed over to the application by JAX-RPC. We expect similar functionality to be provided by other data binding frameworks.

2.13 Clearly define the subset of XML Schema that tools must successfully handle -- appendix 18
The table in appendix 18 needs to be updated with all the required data binding features enabled by the previous change items.
Morever, we need to state how tools should behave when encountering documents that use schema features marked as optional.
In addition, tools will be required to support xsd:include and xsd:import constructs.
We will also explicitely mark certain schema features as not required by JAX-RPC 1.1, so that tools do not have to support them in order to comply with the specification. These features include: xsd:redefine, xsd:notation, substitution groups.

3 Interoperability Requirements

This section details changes to the interoperability requirements forJAX-RPC implementations.

3.1 Remove 1.0 interoperability requirements for document/literal --section 14.3.2
Interoperability requirements for all rpc/literal and document/literal style operations will be covered by change 3.2.

3.2 Add WS-I Basic Profile Version 1.0 interoperability requirements --section 14.4
These requirements are classified according to which portion of a JAX-RPC implementation they affect: Java-to-WSDL tools, WSDL-to-Javatools (including dynamic proxies and DII), runtime (further subdivided according to the different operations that it performs).
The goals of these changes are:

to guarantee that a Java-to-WSDL tool is able to produce a conformant description for a large subset of all valid JAX-RPC 1.1 service endpoint interfaces (the main exception being types that are mapped to attachments);
to guarantee that a WSDL-to-Java tool is able to consume a conformant description and produce valid artifacts;
to guarantee that, provided that user-written code or other container functionality beyond the scope of JAX-RPC 1.1 does not alter incoming or outgoing SOAP messages or deliberately cause the generation of a non conformant message, a JAX-RPC 1.1 application will behave in a conformant way.

3.3 Remove mapping of Java remote exceptions to faults with faultcodes defined outside of the SOAP 1.1 specification -- section 14.3.6
These mappings refer to some fault codes defined in a working draft of the SOAP 1.2 specification and violate WS-I Basic Profile Version 1.0 rules.

4 JAX-RPC APIs and Standard Properties

This section describes the proposed new APIs.

4.1 Add prefix field, getPrefix() method and 3-ary constructor tojavax.xml.namespace.QName -- javadocs only

Other specifications, namely JAXB 1.0 and StAX 1.0, depend on the javax.xml.namespace.QName class in JAX-RPC.

In order to address the immediate needs of those technologies, and in particular to enable QName objects to carry with them the prefix that was used to serialize a QName value in a document, we propose to add the following:

Fields:

prefix

private java.lang.String prefix

The prefix of this QName.

Methods:

getPrefix

public java.lang.String getPrefix()

Get the prefix of this QName.

The prefix assigned to a QName may NOT be valid in a different context. For example, a QName maybe assigned a prefix in the context of parsing a document but that prefix may be invalid in the context of a different document.

Returns:: prefix of this QName

Constructors:

QName

public QName(java.lang.String namespaceURI,
             java.lang.String localPart)

QName constructor specifying the Namespace URI and local part.

If the Namespace URI is null, it is set to "". This value represents no explicitly defined Namespace as defined by the Namespaces inXML specification. This action preserves compatible behavior withQName 1.0.

If the local part is null or .equals(""), an IllegalArgumentException is thrown.

When using this constructor, the prefix is set to "".

Parameters:

namespaceURI - Namespace URI of the QName

localPart - local part of the QName

The prefix is included in QName to retain lexical information when present in an XML input source.
The prefix is not used in QName.equals(Object) or to compute theQName.hashCode().
Equality and the hash code are defined using only the Namespace URI and local part.
If not specified, the prefix is set to "" (the empty string).

4.2 Add javax.xml.rpc.server.ServletEndpointContext.isUserInRole(String) method -- javadocs and section 10.1.3

isUserInRole

public boolean isUserInRole(java.lang.String role)

Returns a boolean indicating whether the authenticated user for the current method invocation on the endpoint instance is included in the specified logical "role".

4.3 Add javax.xml.rpc.ServiceFactory.loadService(java.net.URL, java.lang.Class, java.util.Properties) method -- javadocs and section 8.2.5

loadService

public abstract Service loadService(java.net.URL wsdlDocumentLocation,
                                    java.lang.Class serviceInterface,
                                    java.util.Properties properties)
                             throws ServiceException

Create an instance of the generated service implementation class for a given service interface, if available. An implementation may use the provided wsdlDocumentLocation and properties to help locate the generated implementation class. If no such class is present, a ServiceException will be thrown.

4.4 Add javax.xml.rpc.ServiceFactory.loadService(java.net.URL, javax.xml.namespace.QName, java.util.Properties) method - javadocs and section 8.2.5

loadService

public abstract Service loadService(java.net.URL wsdlDocumentLocation,
                                    javax.xml.namespace.QName serviceName,
                                    java.util.Properties properties)
                             throws ServiceException

Create an instance of the generated service implementation class for a given service, if available. The service is uniquely identified by the wsdlDocumentLocation and serviceName arguments. An implementation may use the provided properties to help locate the generated implementation class. If no such class is present, a ServiceException will be thrown.

4.5 Add javax.xml.rpc.ServiceFactory.loadService(java.lang.Class) method - javadocs and section 8.2.5

loadService

public abstract Service loadService(java.lang.Class serviceInterface)
                             throws ServiceException

Create an instance of the generated service implementation class for a given service interface, if available.

5 Clarifications and Bug Fixes

The following changes are sorted by the chapter of the JAX-RPC 1.0 spec they affect.

5.1 Remove reference to the TCK -- section3 (R05)

5.2 Clarify the name mapping for the get<Port> method -- section 4.3.11

5.3 Clarify the name mapping for the getter methods of boolean propertiesin value types -- section 4.2.3
Following standard JavaBeans conventions, the getter method for a boolean properties should use "is" as a prefix instead of "get".

5.4 Clarify treatment of the minOccurs="0" case for primitive types -- section 4.2.1
Wrappers should be used instead of primitive types when minOccus="0" and maxOccurs="1" (or absent).

5.5 Clarify treatment of the maxOccurs="1" case -- section 4.2.3
Arrays should not be used when maxOccurs="1" is specified.

5.6 Deprecate mapping of java.lang.Byte[] to xsd:base64Binary type -- 5.3.3
The Java Byte[] type cannot be mapped to the xsd:base64Binary type because the latter doesn't allow null values to be represented.
Since the main reason that developers have to use Byte[] over byte[] is that the former allows null values, this mapping is incorrect and should be removed.

5.7 Allow mapping of value types to complex type using the xsd:sequence compositor -- section 5.4.1
The XML Schema specification places restrictions on the contents of a particle that uses the xsd:sequence compositor.
For this reason, many implementations already used xsd:sequence when mapping value types instead of xsd:all as required in JAX-RPC 1.0.

5.8 Clarify that one-way operations cannot have wsdl:output and wsdl:fault elements -- section 5.5.5

5.9Clarify the rules used to recognize a "wrapper" in document/literal style operations -- sections 6.4.1 and 6.4.3

5.10 Clarify that support for encoding attachments of type image/gif is not required -- section 7.5

5.11 Clarify that for one-way operations only the handleRequest methods are called -- section 12.1.4

5.12 Clarify that constants defined on the Call and Stub interfaces can be used in lieu of the hardcoded "javax.xml.rpc.security.auth.[username|password]" strings --section 13.1.1

6 Dependencies

These changes concern the dependencies that JAX-RPC has on other technologies.

6.1 Update dependency on SAAJ to require SAAJ 1.2 -- section3 (R013)
The SAAJ 1.2 maintenance review is being submitted in parallel with the present one.

Deferred Changes

(Changes deferred by the EC will be moved to this section.)

JavaTM API forXML-based RPC 1.1 Change Log

Description

Maintenance Lead

Feedback

Proposed changes

Accepted changes

1 Mapping Between Java and WSDL (Excluding Data Binding)

2 Data Binding and Support for XML Schema

3 Interoperability Requirements

4 JAX-RPC APIs and Standard Properties

prefix

getPrefix

QName

isUserInRole

loadService

loadService

loadService

5 Clarifications and Bug Fixes

6 Dependencies

Deferred Changes

Java^TMAPI forXML-based RPC 1.1 Change Log