Description

Maintenance revision of the Java^TM API for XML Messaging, version 1.1.

Specification Lead

Nicholas Kassem, Sun Microsystems, Inc.

Feedback

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:

public abstract SOAPMessage call(SOAPMessage request,Object to) throws SOAPException

Sends the given message to the specified endpoint and blocks until a response is received.

Parameters:

request - the SOAPMessage object to be sent
to - an Object that identifies where the message should be sent - objects of type java.lang.String and java.net.URL must be supported.

Returns:

the SOAPMessage object that is the response to the message that was sent

Throws:
SOAPException if there is a SOAP error

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:

1. Replacement of the SOAP* naming convention with the more standard mixed case convention of Soap*.
2. Introduction of helper classes to further facilitate the insertion of XML fragments into a preexisting SOAPEnvelope.
3. Introduction of a new base class in order to handle potentially new "emerging" message packaging and attachment handling models in the future.
4. 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.