March 12th, 2003
(Updated: April 11th, 2003)
(Updated with approved changes 25 April 2003)
Maintenance revision of the JavaTM API for XML-based RPC, version 1.1.
Roberto Chinnici, Sun Microsystems, Inc.
Comments should be sent to firstname.lastname@example.org.
The main goal for JAX-RPC 1.1 is to add support for the WS-I
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
The sections below correspond to different logical areas in
JAX-RPC and don't necessarily match the outline of the JAX-RPC 1.0
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
| 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, 184.108.40.206, 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.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
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 --
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.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:
|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.1 Add prefix field,
getPrefix() method and 3-ary constructor tojavax.xml.namespace.QName --
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:
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).
-- javadocs and section 10.1.3
java.lang.Class, java.util.Properties) method -- javadocs and section
javax.xml.namespace.QName, java.util.Properties) method - javadocs and
javax.xml.rpc.ServiceFactory.loadService(java.lang.Class) method -
javadocs and section 8.2.5
|5.1 Remove reference to the TCK -- section3
|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
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.
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.
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.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.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.