About JCP
Get Involved
Community Resources
Community News
FAQ
Contact Us
|
|
JAXM 1.1 Change Log
JavaTM
API
for XML Messaging 1.1
March 08, 2002
Updated April 15, 2002
Description
Maintenance revision of the JavaTM
API for XML Messaging, version 1.1.
Specification Lead
Nicholas Kassem, Sun Microsystems, Inc.
Feedback
Rationale for accepted changes
This minor maintenance release has two main goals.
The first is to increase the usage and applicability of javax.xml.soap
package and the second is to enhance the XML fragment model of the JAXM 1.0
specification.
- The soap package was first introduced in JAXM 1.0 and was designed to provide
a simple abstraction of the W3C SOAP 1.1 (with attachments) note & specification.
However, currently the soap package is an integral part the overall JAXM1.0
specification and there are bi-directional dependencies between the soap and
messaging packages. The Java community feedback to-date suggests that it is
acceptable to have the messaging package depend on the soap package. However,
it would be desirable to have the soap package have no such dependency on
the messaging package. Removing the latter dependency will likely broaden
the applicability of the soap package.
- The JAXM 1.0 specifications introduced a SOAPElementFactory
object in order to enable the manipulation of a soap message by developers
who choose to use SOAPElement objects
as abstractions for XML fragments. The underlying assumption necessitating
this factory object, lies in the fact that there appears to be a class of
developers who may not have easy access to the SOAPEnvelope
and the subordinate nodes in the soap message tree. Having introduced a factory
method for SOAPElement objects
in JAXM 1.0, it appears that additional factory methods are desirable.
Accepted changes
In order to accomplish the stated goals, the following
changes were accepted:
- The javax.xml.soap package
will be moved to a new document designated as "SOAP with Attachments
API for Java ('SAAJ')". The dependency of the soap package
on the messaging package will be removed by modifying the
call method signature of the SOAPConnection
object as follows:
In addition it was accepted that the
newInstance method of SOAPConnectionFactory
throw an UnsupportedOperationException
in order to handle cases where an implementation chooses not to support the
SOAPConnection.call() functionality.
The URLEndpoint object from
the javax.xml.messaging package
was retained for compatibility reasons. The JAXM 1.1 specification will require
that the SOAPConnectionFactory
produce SOAPConnection objects
that support URLEndpoint objects.
- The javax.xml.soap package
will be modified to include a factory object that will be responsible for
creating SOAPElement, Detail
and Name objects. It was therefore
accepted that the SOAPElementFactory
be deprecated and have its' methods delegate to SOAPFactory
methods.
The class details are as follows:
- public abstract class SOAPFactory
extends java.lang.Object
SOAPFactory is a factory
for creating various objects that exist in the SOAP XML tree. SOAPFactory
can be used to create XML fragments that will eventually be associated
with the SOAPPart of a message. These fragments can be inserted as children
of the SOAPHeaderElement
or SOAPBodyElement or SOAPEnvelope.
SOAPFactory also has methods
to create javax.xml.soap.Detail
objects as well as java.xml.soap.Name
objects.
The SOAPFactory class
will support the following methods:
- public abstract SOAPElement
createElement(Name name) throws SOAPException
Create a SOAPElement
object initialized with the given Name
object.
Parameters:
name - a Name
object with the XML name for the new element
Returns:
the new SOAPElement
object that was created
Throws:
SOAPException - if
there is an error in creating the SOAPElement
object
- public abstract SOAPElement
createElement(java.lang.String localName) throws SOAPExceptionCreate
a SOAPElement object
initialized with the given local name.
Parameters:
localName - a String
giving the local name for the new element
Returns:
the new SOAPElement
object that was created
Throws:
SOAPException - if
there is an error in creating the SOAPElement
object
- public abstract SOAPElement
createElement(java.lang.String localName,java.lang.String prefix,java.lang.String
uri) throws SOAPException
Create a new SOAPElement
object with the given local name, prefix and uri.
Parameters:
localName - a String
giving the local name for the new element
prefix - the prefix
for this SOAPElement
uri - a String giving
the URI of the namespace
to which the new element belongs
Throws:
SOAPException - if
there is an error in creating the SOAPElement
object
- public abstract Detail createDetail()
throws SOAPException
Creates a new Detail
object which serves as a container for DetailEntry
objects. This factory method creates Detail
objects for use in situations where it is not practical to use the
SOAPFault abstraction.
Returns:
a Detail object
Throws:
SOAPException - if
there is a SOAP error
- public abstract Name createName(java.lang.String
localName,
java.lang.String prefix,java.lang.String uri)throws SOAPException
Creates a new Name
object initialized with the given local name, namespace prefix,
and namespace URI.
This factory method creates Name
objects for use in situations where it is not practical to use the
SOAPEnvelope abstraction.
Parameters:
localName - a String
giving the local name
prefix - a String
giving the prefix of the namespace
uri - a String giving
the URI of the namespace
Returns:
a Name object initialized
with the given local name, namespace prefix, and namespace URI
Throws:
SOAPException - if
there is a SOAP error
- public abstract Name createName(java.lang.String
localName)
throws SOAPException
Creates a new Name object initialized with the given local name.
This factory method creates Name objects for use in situations where
it is not practical to use the SOAPEnvelope abstraction.
Parameters:
localName - a String
giving the local name
Returns:
a Name object initialized
with the given local name
Throws:
SOAPException - if
there is a SOAP error
- public static SOAPFactory
newInstance()
throws SOAPException
Creates a new instance of SOAPFactory.
Returns:
a new instance of a SOAPFactory
Throws:
SOAPException - if
there was an error creating the default SOAPFactory
Deferred Changes
The following change requests have been noted but were deferred for this maintenance
release cycle:
- Replacement of the SOAP* naming convention with the more standard mixed
case convention of Soap*.
- Introduction of helper classes to further facilitate the insertion of XML
fragments into a preexisting SOAPEnvelope.
- Introduction of a new base class in order to handle potentially new "emerging"
message packaging and attachment handling models in the future.
- Alignment with the W3C SOAP1.2 specification. This alignment is considered
critical for both the javax.xml.messaging
and javax.xml.soap packages
and will receive the highest priority once the disposition of the SOAP1.2
specification becomes clear.
|