Skip to content

Latest commit

 

History

History
188 lines (147 loc) · 7.62 KB

appendix.adoc

File metadata and controls

188 lines (147 loc) · 7.62 KB
Raw

Appendix A: References

For more information, refer to the following web sites:

Appendix B: Change History

Changes in Version 2.0

  • Changed specification version and license.

  • Changed package name to jakarta.xml.soap

Changes in Maintenance Release 4

The fourth maintenance release of SAAJ, SAAJ 1.4, clarifies and extends the SAAJ 1.3 specification.The goal of this maintenance release proposal is primarily to adopt changes in Java SE Platform and to make a few corrections and clarifications on the existing SAAJ 1.3 APIs. The proposed API changes in SAAJ 1.4 are backward compatible with SAAJ 1.3 APIs.

The "accepted changes", as specified in JSR067 changelog, have been incorporated in this document. The key changes are as follows:

  • Changed the definition of the discovery process of SAAJ implementation.

  • Added support for generics where applicable.

  • Changed MAY to MUST in jakarta.xml.soap.SOAPElements methods.

  • Several corrections and clarifications have been made to the JavaDocs for the API.

Changes in Maintenance Release 3

The third maintenance release of SAAJ, SAAJ 1.3, clarifies and extends the SAAJ 1.2 specification.The goal of this maintenance release proposal is primarily to provide support for SOAP version 1.2 Message Constructs and to make a few corrections and clarifications on the existing SAAJ 1.2 APIs. The proposed API changes in SAAJ 1.3 are backward compatible with SAAJ 1.2 APIs.

SOAP version 1.2 has a number of changes in syntax and provides additional (or clarified) semantics from those described in SOAP 1.1. This proposed changes in this maintenance release are concerned with the following areas:

  • Support for SOAP version 1.2 message constructs in the API.

  • Factoring out the creation of all SAAJ Factory classes into a single SPI that allows creation of SOAP version aware Factories.

  • Addition of a few new classes and new methods in certain existing classes and interfaces.

  • Support for overloaded QName based methods in certain classes and interfaces.

  • Clarification of semantics and correction of wording of JavaDocs and specification

A brief summary of the proposed changes follows:

  • Support for SOAP Version 1.2 message constructs in the API: SOAP Version 1.2 has a number of changes in syntax and introduces several new Message Constructs. SAAJ 1.3 will support SOAP Version 1.2 Message Constructs.

  • SPI for Creation of Factory Instances: SAAJ 1.3 will support SOAP Version 1.2 Message Constructs, while at the same time being backward compatible in its support for SOAP Version 1.1. We would like to define an SPI (SAAJMetaFactory) for factoring out the creation of SOAP Version aware Factory classes into a single place. Changing out the SAAJMetaFactory has the effect of changing out the entire SAAJ implementation. Backward compatibility is maintained by ensuring that the default protocol is set to SOAP Version 1.1.

  • Definition of new Class SAAJResult: A SAAJResult object acts as a holder for the results of a JAXP transformation or a JAXB marshalling, in the form of a SAAJ tree. This class will make it easier for the end user when dealing with transformations in situations where the result is expected to be a valid SAAJ tree.

  • Addition of overloaded methods which accept a QName instead of a Name: QName is the preferred representation of XML qualified names, and hence we would like to introduce overloaded methods in all APIs where a corresponding method was accepting a jakarta.xml.soap.Name as argument. The Name interface may be deprecated in a future release of SAAJ in favor of QName.

  • Clarify and correct the wording of JavaDocs and specification: None of these changes will break backward compatibility for SOAP 1.1 users. Corrections of this nature cost little and improve the overall integrity of the specification making correct implementations easier to create, validate and use.

  • Addition of new methods in certain Interfaces and Classes: A few new methods have been introduced in AttachmentPart, SOAPBody, and SOAPElement. These new methods are intended for ease of use and to assist SAAJ users when dealing with some of the newer SOAP features.

  • Making SOAPPart a jakarta.xml.soap.Node: The SOAPPart is also a SOAP Node.

Deferred Changes:

  • The deprecation of Name Interface has been deferred to a later release.

  • DOM Level 3 Support: Implementations of SAAJ 1.3 must provide support for DOM Level 3 APIs.

Changes in Maintenance Release 2

The second maintenance release of SAAJ, SAAJ 1.2, clarifies and extends the SAAJ 1.1 specification. The "accepted changes", as specified in the Change Log forSOAP with Attachments API for Java™, have been incorporated into this document. A summary of the changes follows:

  • The core SAAJ classes and interfaces: Node , SOAPElement , SOAPPart , and Text now extend the equivalent interfaces in the org.w3c.dom package: Node , Element , Document and Text respectively.

  • The ability to get and set properties on SOAPMessage has been added to SOAPMessage in order to facilitate extensibility and two new properties have been added in order to take advantage of this extensibility: CHARACTER_SET_ENCODING allows the character encoding to be set to "utf-8" or "utf-16" where "utf-8" is the default. Implementations may optionally support other character encodings. WRITE_XML_DECLARATION allows clients to specify whether or not an XML Declaration will be written at the start of the SOAP part of the message. The valid values are "true" and "false" with "false" being the default.

  • Several APIs have been extended in order to provide greater ease of use. The Node interface has gained a setValue () method. SOAPFault has been enhanced with several methods that facilitate the handling of its sub-elements. SOAPMessage , SOAPElement , SOAPBody and SOAPHeader have all been given new methods that enhance navigation of the tree. A removeContents() element has been added to SOAPElement in order to assist in the construction of messages that contain a fault.

  • Several corrections and clarifications have been made to the JavaDocs for the API.

This specification has been derived from the jakarta.XML.SOAP package originally defined in the JAXM 1.0 specification. The "accepted changes," as specified in JSR067 changelog, have been incorporated in this document. The key changes are as follows:

  • jakarta.xml.soap package was moved from the JAXM specification to this document. In the interest of consistency and for simplifying synchronization of specifications, this document has been designated as version 1.1 of the SAAJ specification. There are no prior versions of the SAAJ specification.

  • The call method signature of the SOAPConnection object has been modified so as to remove the dependency of SAAJ on JAXM.

  • The newInstance method of SOAPConnectionFactory may throw an UnsupportedOperationException hence making the implementation of the SOAPConnection.call() functionality optional.

  • The SOAPElementFactory has been deprecated and a new "super" factory for creating Element , Detail , and Name objects created. The previous SOAPElementFactory methods now delegate to the appropriate SOAPFactory methods.