jaxws/src/java.xml.ws/share/classes/javax/xml/soap/package.html
changeset 33548 42ca9d5434cc
parent 33546 d811489c5649
parent 33547 e4c76ac38b12
child 33549 5b9a259327ec
equal deleted inserted replaced
33546:d811489c5649 33548:42ca9d5434cc
     1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
       
     2 <!--
       
     3  Copyright (c) 1993, 2012, Oracle and/or its affiliates. All rights reserved.
       
     4  DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
       
     5 
       
     6  This code is free software; you can redistribute it and/or modify it
       
     7  under the terms of the GNU General Public License version 2 only, as
       
     8  published by the Free Software Foundation.  Oracle designates this
       
     9  particular file as subject to the "Classpath" exception as provided
       
    10  by Oracle in the LICENSE file that accompanied this code.
       
    11 
       
    12  This code is distributed in the hope that it will be useful, but WITHOUT
       
    13  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
       
    14  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
       
    15  version 2 for more details (a copy is included in the LICENSE file that
       
    16  accompanied this code).
       
    17 
       
    18  You should have received a copy of the GNU General Public License version
       
    19  2 along with this work; if not, write to the Free Software Foundation,
       
    20  Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
       
    21 
       
    22  Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
       
    23  or visit www.oracle.com if you need additional information or have any
       
    24  questions.
       
    25 -->
       
    26 
       
    27 <html>
       
    28 <head>
       
    29    
       
    30   <title></title>
       
    31 
       
    32 </head>
       
    33    <body bgcolor="white">
       
    34     Provides the API for creating and building SOAP messages. This package
       
    35  is defined in the <i>SOAP with Attachments API for Java<sup><font
       
    36  size="-2">TM</font></sup> (SAAJ) 1.3</i> specification.
       
    37 <p> The API in the <code>javax.xml.soap</code> package allows you to do the
       
    38  following: </p>
       
    39 
       
    40 <ul>
       
    41      <li>create a point-to-point connection to a specified endpoint   </li>
       
    42     <li>create a SOAP message   </li>
       
    43     <li>create an XML fragment   </li>
       
    44     <li>add content to the header of a SOAP message   </li>
       
    45     <li>add content to the body of a SOAP message   </li>
       
    46     <li>create attachment parts and add content to them   </li>
       
    47     <li>access/add/modify parts of a SOAP message   </li>
       
    48     <li>create/add/modify SOAP fault information   </li>
       
    49     <li>extract content from a SOAP message   </li>
       
    50     <li>send a SOAP request-response message   </li>
       
    51 
       
    52 </ul>
       
    53 
       
    54 <p>   <!-- <h2>Package Specification</h2> -->  <!-- The SAAJ 1.1 specification gives an overview of the  -->
       
    55  <!-- <code>javax.xml.soap</code> package and --> <!-- explains how its classes and interfaces work. -->
       
    56  <!-- <ul> --> <!--   <li><a href="http://java.sun.com/xml/downloads/jaxm.html"> -->
       
    57  <!-- 	SAAJ 1.1 Specification</a> --> <!-- </ul> -->  <!-- <h2>Related Documentation</h2> -->
       
    58  <!-- 	For overviews, tutorials, examples, guides, and tool documentation, please see: -->
       
    59  <!-- 	<ul> --> <!-- 	  <li><a href="../../../../tutorial/doc/JAXM.html">JAXM Tutorial</a> -->
       
    60  <!-- 	  <li><a href="../../../../jaxm/index.html">JAXM Reference Implementation (RI) -->
       
    61  <!-- 			  Documentation</a> --> <!-- 	</ul> -->  </p>
       
    62 In addition the APIs in the <code>javax.xml.soap</code> package extend
       
    63 their  counterparts in the <code>org.w3c.dom</code> package. This means that
       
    64 the  <code>SOAPPart</code> of a <code>SOAPMessage</code> is also a DOM Level
       
    65 2 <code>Document</code>, and can be manipulated as such by applications,
       
    66 tools and libraries that use DOM (see http://www.w3.org/DOM/ for more information).
       
    67 It is important to note that, while it is possible to use DOM APIs to add
       
    68 ordinary DOM nodes to a SAAJ tree, the SAAJ APIs are still required to return
       
    69 SAAJ types when examining or manipulating the tree. In order to accomplish
       
    70 this the SAAJ APIs (specifically {@link javax.xml.soap.SOAPElement#getChildElements()})
       
    71 are allowed to silently replace objects that are incorrectly typed relative
       
    72 to SAAJ requirements with equivalent objects of the required type. These
       
    73 replacements must never cause the logical structure of the tree to change,
       
    74 so from the perspective of the DOM APIs the tree will remain unchanged. However,
       
    75 the physical composition of the tree will have changed so that references
       
    76 to the nodes that were replaced will refer to nodes that are no longer a
       
    77 part of the tree. The SAAJ APIs are not allowed to make these replacements
       
    78 if they are not required so the replacement objects will never subsequently
       
    79 be silently replaced by future calls to the SAAJ API.
       
    80 <p>
       
    81 What this means in
       
    82 practical terms is that an application that starts to use SAAJ APIs on a
       
    83 tree after manipulating it using DOM APIs must assume that the tree has been
       
    84 translated into an all SAAJ tree and that any references to objects within
       
    85 the tree that were obtained using DOM APIs are no longer valid. Switching
       
    86 from SAAJ APIs to DOM APIs is not allowed to cause invalid references and
       
    87 neither is using SAAJ APIs exclusively. It is only switching from using DOM
       
    88 APIs on a particular SAAJ tree to using SAAJ APIs that causes the risk of
       
    89 invalid references.<br>
       
    90 
       
    91 </body>
       
    92 </html>