diff --git a/spec/src/main/asciidoc/SOAPAttachments.adoc b/spec/src/main/asciidoc/SOAPAttachments.adoc index 3813fb8..27ebe24 100644 --- a/spec/src/main/asciidoc/SOAPAttachments.adoc +++ b/spec/src/main/asciidoc/SOAPAttachments.adoc @@ -10,7 +10,7 @@ Java™ Community Process (JCP2.10). Comments from experts, participants, and the broader developer community were reviewed and incorporated into this specification. -The SAAJ Specification, version 1.1 was a +The SOAP with Attachments API for Java Specification, version 1.1 was a maintenance release of the Java™ API for XML Messaging (JAXM) 1.0 specification. JAXM 1.0 was the final deliverable of JSR067 Expert Group (EG). The proposed changes specified in the JSR067 changelog and @@ -18,15 +18,15 @@ accepted on 15 April 2002, have been incorporated into this document. The proposed changes specified in the second JSR067 changelog and accepted on 23 April 2003, have been incorporated -into this document as SAAJ Specification, version 1.2. +into this document as SOAP with Attachments API for Java Specification, version 1.2. The proposed changes specified in the third -JSR067 changelog have been incorporated into this document as SAAJ +JSR067 changelog have been incorporated into this document as SOAP with Attachments API for Java Specification, version 1.3. The proposed changes specified in the fourth -JSR067 changelog have been incorporated into this document as SAAJ -Specification, version 1.4. +JSR067 changelog have been incorporated into this document as +SOAP with Attachments API for Java Specification, version 1.4. Starting with Jakarta SOAP Attachments Specification, Version 2.0, this document is developed under https://jakarta.ee/about/jesp/[Jakarta EE Specification Process] @@ -40,6 +40,9 @@ collaborative work within the Java community. === Terminology +References in this document to SAAJ refer to the Jakarta SOAP with Attachments API +unless otherwise noted. + The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL, when they appear in this document, are to be interpreted as described in RFC 2119 @@ -99,13 +102,13 @@ assumed. Jakarta SOAP with Attachments defines an API enabling developers to produce and consume messages conforming to the SOAP 1.1, SOAP 1.2 and SOAP Attachments Feature. -In the interest of backward compatibility, SAAJ +In the interest of backward compatibility, Jakarta SOAP Attachments Specification continues to offer a client-side communication capability enabling developers to communicate in a point-to-point and request-response manner with SOAP services bound to HTTP. This communication capability, -within the context of the SAAJ specification, is optional. However, -specifications depending on SAAJ are free to require support for the -SOAP to HTTP binding. +within the context of the Jakarta SOAP Attachments Specification specification, +is optional. However, specifications depending on Jakarta SOAP Attachments Specification +are free to require support for the SOAP to HTTP binding. == Typographic Conventions @@ -146,7 +149,7 @@ To delete a file, type `rm` __filename__ . == Package Overview -This chapter presents an overview of the SAAJ +This chapter presents an overview of the Jakarta SOAP Attachments which consists of the single package; `jakarta.xml.soap` . The intent here is to provide an overview of the package only, the details of which can be found in the following chapter. @@ -173,7 +176,7 @@ object is encoded as a MIME message otherwise it is encoded as a simple XML message. Attachments may contain data of any type including XML. The SOAPPart is always XML. -SAAJ allows for creation and consumption of +Jakarta SOAP Attachments allows for creation and consumption of both SOAP 1.1 and SOAP 1.2 messages by introducing the notion of Protocol aware MessageFactories. The protocol here refers to a particular version of SOAP. For example a SOAP 1.2 aware MessageFactory @@ -210,13 +213,13 @@ type or an `InputStream` object that contains the content as bytes. The removal of all the content from an `AttachmentPart` object while leaving the header information. -A SAAJ implementation must support the +A Jakarta SOAP Attachments implementation must support the following MIME types. Additional MIME types may be supported using the `jakarta.activation.DataHandler` class and the Jakarta Activation Framework. -.SAAJ supported MIME types +.Jakarta SOAP Attachments supported MIME types [cols="1,2",options="header"] |=== |MIME Type @@ -232,7 +235,7 @@ following MIME types. Additional MIME types may be supported using the |`javax.xml.transform.Source` |=== -SAAJ provides methods for setting and getting +Jakarta SOAP Attachments API provides methods for setting and getting the Raw content of an Attachment. Methods have also been provided to get the content as Base64 encoded character data. Additionally a getAttachment method on the SOAPMessage provides for retrieval of an @@ -316,14 +319,14 @@ models the contents of the SOAP header of a SOAP envelope. The `SOAPConnection` object represents a simple client-side view of a request-response style of SOAP messaging. A -SAAJ client may choose to establish a synchronous point-to-point +Jakarta SOAP Attachments client may choose to establish a synchronous point-to-point connection to a SOAP service using the `createConnection` method of the `SOAPConnectionFactory` object. Subsequently, a `SOAPMessage` may be sent to a remote party using the call method on the `SOAPConnection` object. Note that the call method will block until a `SOAPMessage` object is received. -A SAAJ based application may choose to use the +A Jakarta SOAP Attachments Specification based application may choose to use the call method to implement the client side of a simple point-to-point synchronous one-way message exchange scenario. In such a case, it is the application’s responsibility to ignore the `SOAPMessage` object returned @@ -332,7 +335,7 @@ unblock the client. It is assumed that a one-way service will not return a response to a request using the same connection when the `SOAPConnection.call` method was used to send the request. -SAAJ also provides support for the SOAP 1.2 +Jakarta SOAP Attachments Specification also provides support for the SOAP 1.2 Response Message Exchange Pattern (http://www.w3.org/TR/2003/REC-soap12-part2-20030624/#soapresmep) via the `SOAPConnection.get` method. This method can be used for pure @@ -376,10 +379,10 @@ and `Detail` objects. === SAAJMetaFactory This Factory is the access point for the -implementation classes of all the other factories defined in the SAAJ -API. All of the newInstance methods defined on factories in SAAJ defer -to instances of this class to do the actual object creation. The -implementations of newInstance() methods (in SOAPFactory and +implementation classes of all the other factories defined in the Jakarta SOAP +Attachments API. All of the newInstance methods defined on factories in Jakarta +SOAP Attachments API defer to instances of this class to do the actual object +creation. The implementations of newInstance() methods (in SOAPFactory and MessageFactory) that existed in SAAJ 1.2 have been updated to also delegate to the SAAJMetaFactory when the SAAJ 1.2 defined lookup fails to locate the Factory implementation class name. @@ -391,9 +394,9 @@ interface. There are no public methods on this class. This concrete class acts as a holder for the results of a JAXP transformation or a Jakarta XML Binding marshalling, -in the form of a SAAJ tree. This class will make it easier +in the form of a Jakarta SOAP Attachments 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. +where the result is expected to be a valid Jakarta SOAP Attachments tree. The results can be accessed by using the getResult method. @@ -404,7 +407,7 @@ The results can be accessed by using the getResult method. Provides the API for creating and building SOAP messages. This package is defined in the Jakarta SOAP -with Attachments (SAAJ) specification. +with Attachments Specification. The API in the `jakarta.xml.soap` package allows you to do the following: @@ -426,34 +429,36 @@ means that the `SOAPPart` of a `SOAPMessage` is also a DOM Level 2 `Document`, and can be manipulated as such by applications, tools and libraries that use DOM (see http://www.w3.org/DOM/ for more information). It is important to note that, while it is possible to use -DOM APIs to add ordinary DOM nodes to a SAAJ tree, the SAAJ APIs are -still required to return SAAJ types when examining or manipulating the -tree. In order to accomplish this the SAAJ APIs (specifically +DOM APIs to add ordinary DOM nodes to a Jakarta SOAP Attachments tree, +the Jakarta SOAP Attachments APIs are +still required to return Jakarta SOAP Attachments types when examining or manipulating the +tree. In order to accomplish this the Jakarta SOAP Attachments APIs (specifically `SOAPElement.getChildElements()`) are allowed to silently replace objects that are -incorrectly typed relative to SAAJ requirements with equivalent objects -of the required type. These replacements must never cause the logical +incorrectly typed relative to Jakarta SOAP Attachments Specification requirements +with equivalent objects of the required type. +These replacements must never cause the logical structure of the tree to change, so from the perspective of the DOM APIs the tree will remain unchanged. However, the physical composition of the tree will have changed so that references to the nodes that were replaced will refer to nodes that are no longer a part of the tree. The -SAAJ APIs are not allowed to make these replacements if they are not +Jakarta SOAP Attachments APIs are not allowed to make these replacements if they are not required so the replacement objects will never subsequently be silently -replaced by future calls to the SAAJ API. +replaced by future calls to the Jakarta SOAP Attachments API. What this means in practical terms is that an -application that starts to use SAAJ APIs on a tree after manipulating it +application that starts to use Jakarta SOAP Attachments APIs on a tree after manipulating it using DOM APIs must assume that the tree has been translated into an all -SAAJ tree and that any references to objects within the tree that were -obtained using DOM APIs are no longer valid. Switching from SAAJ APIs to +Jakarta SOAP Attachments tree and that any references to objects within the tree that were +obtained using DOM APIs are no longer valid. Switching from Jakarta SOAP Attachments APIs to DOM APIs is not allowed to cause invalid references and neither is using -SAAJ APIs exclusively. It is only switching from using DOM APIs on a -particular SAAJ tree to using SAAJ APIs that causes the risk of invalid -references. +Jakarta SOAP Attachments APIs exclusively. It is only switching from using DOM APIs on a +particular Jakarta SOAP Attachments tree to using Jakarta SOAP Attachments APIs +that causes the risk of invalid references. -=== Discovery of SAAJ implementation +=== Discovery of Jakarta SOAP Attachments implementation There are several factories defined in the -SAAJ API to discover and load specific implementation: +Jakarta SOAP Attachments API to discover and load specific implementation: * SOAPFactory * MessageFactory @@ -467,7 +472,7 @@ uses a common lookup procedure to determine the implementation class: name as the factory class is set (e.g. `jakarta.xml.soap.SOAPFactory`). If such property exists then its value is assumed to be the fully qualified name of the implementation class. This phase of the look up enables -per-JVM override of the SAAJ implementation. +per-JVM override of the Jakarta SOAP Attachments implementation. * Use the configuration file "jaxm.properties". The file is in standard `Properties` format and typically located in the diff --git a/spec/src/main/asciidoc/appendix.adoc b/spec/src/main/asciidoc/appendix.adoc index 2acf512..951c855 100644 --- a/spec/src/main/asciidoc/appendix.adoc +++ b/spec/src/main/asciidoc/appendix.adoc @@ -163,11 +163,11 @@ of messages that contain a fault. 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 +`javax.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 +* `javax.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