jdk8-mips64-public/jaxws: src/share/jaxws_classes/javax/xml/soap/SOAPPart.java@9c07ef4934dd

     1 /*

     2  * Copyright (c) 2004, 2012, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    26 package javax.xml.soap;

    28 import java.util.Iterator;

    30 import javax.xml.transform.Source;

    32 /**

    33  * The container for the SOAP-specific portion of a <code>SOAPMessage</code>

    34  * object. All messages are required to have a SOAP part, so when a

    35  * <code>SOAPMessage</code> object is created, it will automatically

    36  * have a <code>SOAPPart</code> object.

    37  *<P>

    38  * A <code>SOAPPart</code> object is a MIME part and has the MIME headers

    39  * Content-Id, Content-Location, and Content-Type.  Because the value of

    40  * Content-Type must be "text/xml", a <code>SOAPPart</code> object automatically

    41  * has a MIME header of Content-Type with its value set to "text/xml".

    42  * The value must be "text/xml" because content in the SOAP part of a

    43  * message must be in XML format.  Content that is not of type "text/xml"

    44  * must be in an <code>AttachmentPart</code> object rather than in the

    45  * <code>SOAPPart</code> object.

    46  * <P>

    47  * When a message is sent, its SOAP part must have the MIME header Content-Type

    48  * set to "text/xml". Or, from the other perspective, the SOAP part of any

    49  * message that is received must have the MIME header Content-Type with a

    50  * value of "text/xml".

    51  * <P>

    52  * A client can access the <code>SOAPPart</code> object of a

    53  * <code>SOAPMessage</code> object by

    54  * calling the method <code>SOAPMessage.getSOAPPart</code>. The

    55  * following  line of code, in which <code>message</code> is a

    56  * <code>SOAPMessage</code> object, retrieves the SOAP part of a message.

    57  * <PRE>

    58  *   SOAPPart soapPart = message.getSOAPPart();

    59  * </PRE>

    60  * <P>

    61  * A <code>SOAPPart</code> object contains a <code>SOAPEnvelope</code> object,

    62  * which in turn contains a <code>SOAPBody</code> object and a

    63  * <code>SOAPHeader</code> object.

    64  * The <code>SOAPPart</code> method <code>getEnvelope</code> can be used

    65  * to retrieve the <code>SOAPEnvelope</code> object.

    66  * <P>

    67  */

    68 public abstract class SOAPPart implements org.w3c.dom.Document, Node {

    70     /**

    71      * Gets the <code>SOAPEnvelope</code> object associated with this

    72      * <code>SOAPPart</code> object. Once the SOAP envelope is obtained, it

    73      * can be used to get its contents.

    74      *

    75      * @return the <code>SOAPEnvelope</code> object for this

    76      *           <code>SOAPPart</code> object

    77      * @exception SOAPException if there is a SOAP error

    78      */

    79     public abstract SOAPEnvelope getEnvelope() throws SOAPException;

    81     /**

    82      * Retrieves the value of the MIME header whose name is "Content-Id".

    83      *

    84      * @return a <code>String</code> giving the value of the MIME header

    85      *         named "Content-Id"

    86      * @see #setContentId

    87      */

    88     public String getContentId() {

    89         String[] values = getMimeHeader("Content-Id");

    90         if (values != null && values.length > 0)

    91             return values[0];

    92         return null;

    93     }

    95     /**

    96      * Retrieves the value of the MIME header whose name is "Content-Location".

    97      *

    98      * @return a <code>String</code> giving the value of the MIME header whose

    99      *          name is "Content-Location"

   100      * @see #setContentLocation

   101      */

   102     public String getContentLocation() {

   103         String[] values = getMimeHeader("Content-Location");

   104         if (values != null && values.length > 0)

   105             return values[0];

   106         return null;

   107     }

   109     /**

   110      * Sets the value of the MIME header named "Content-Id"

   111      * to the given <code>String</code>.

   112      *

   113      * @param contentId a <code>String</code> giving the value of the MIME

   114      *        header "Content-Id"

   115      *

   116      * @exception IllegalArgumentException if there is a problem in

   117      * setting the content id

   118      * @see #getContentId

   119      */

   120     public void setContentId(String contentId)

   121     {

   122         setMimeHeader("Content-Id", contentId);

   123     }

   124     /**

   125      * Sets the value of the MIME header "Content-Location"

   126      * to the given <code>String</code>.

   127      *

   128      * @param contentLocation a <code>String</code> giving the value

   129      *        of the MIME

   130      *        header "Content-Location"

   131      * @exception IllegalArgumentException if there is a problem in

   132      *            setting the content location.

   133      * @see #getContentLocation

   134      */

   135     public void setContentLocation(String contentLocation)

   136     {

   137         setMimeHeader("Content-Location", contentLocation);

   138     }

   139     /**

   140      * Removes all MIME headers that match the given name.

   141      *

   142      * @param header a <code>String</code> giving the name of the MIME header(s) to

   143      *               be removed

   144      */

   145     public abstract void removeMimeHeader(String header);

   147     /**

   148      * Removes all the <code>MimeHeader</code> objects for this

   149      * <code>SOAPEnvelope</code> object.

   150      */

   151     public abstract void removeAllMimeHeaders();

   153     /**

   154      * Gets all the values of the <code>MimeHeader</code> object

   155      * in this <code>SOAPPart</code> object that

   156      * is identified by the given <code>String</code>.

   157      *

   158      * @param name the name of the header; example: "Content-Type"

   159      * @return a <code>String</code> array giving all the values for the

   160      *         specified header

   161      * @see #setMimeHeader

   162      */

   163     public abstract String[] getMimeHeader(String name);

   165     /**

   166      * Changes the first header entry that matches the given header name

   167      * so that its value is the given value, adding a new header with the

   168      * given name and value if no

   169      * existing header is a match. If there is a match, this method clears

   170      * all existing values for the first header that matches and sets the

   171      * given value instead. If more than one header has

   172      * the given name, this method removes all of the matching headers after

   173      * the first one.

   174      * <P>

   175      * Note that RFC822 headers can contain only US-ASCII characters.

   176      *

   177      * @param   name    a <code>String</code> giving the header name

   178      *                  for which to search

   179      * @param   value   a <code>String</code> giving the value to be set.

   180      *                  This value will be substituted for the current value(s)

   181      *                  of the first header that is a match if there is one.

   182      *                  If there is no match, this value will be the value for

   183      *                  a new <code>MimeHeader</code> object.

   184      *

   185      * @exception IllegalArgumentException if there was a problem with

   186      *            the specified mime header name or value

   187      * @see #getMimeHeader

   188      */

   189     public abstract void setMimeHeader(String name, String value);

   191     /**

   192      * Creates a <code>MimeHeader</code> object with the specified

   193      * name and value and adds it to this <code>SOAPPart</code> object.

   194      * If a <code>MimeHeader</code> with the specified name already

   195      * exists, this method adds the specified value to the already

   196      * existing value(s).

   197      * <P>

   198      * Note that RFC822 headers can contain only US-ASCII characters.

   199      *

   200      * @param   name    a <code>String</code> giving the header name

   201      * @param   value   a <code>String</code> giving the value to be set

   202      *                  or added

   203      * @exception IllegalArgumentException if there was a problem with

   204      *            the specified mime header name or value

   205      */

   206     public abstract void addMimeHeader(String name, String value);

   208     /**

   209      * Retrieves all the headers for this <code>SOAPPart</code> object

   210      * as an iterator over the <code>MimeHeader</code> objects.

   211      *

   212      * @return  an <code>Iterator</code> object with all of the Mime

   213      *          headers for this <code>SOAPPart</code> object

   214      */

   215     public abstract Iterator getAllMimeHeaders();

   217     /**

   218      * Retrieves all <code>MimeHeader</code> objects that match a name in

   219      * the given array.

   220      *

   221      * @param names a <code>String</code> array with the name(s) of the

   222      *        MIME headers to be returned

   223      * @return  all of the MIME headers that match one of the names in the

   224      *           given array, returned as an <code>Iterator</code> object

   225      */

   226     public abstract Iterator getMatchingMimeHeaders(String[] names);

   228     /**

   229      * Retrieves all <code>MimeHeader</code> objects whose name does

   230      * not match a name in the given array.

   231      *

   232      * @param names a <code>String</code> array with the name(s) of the

   233      *        MIME headers not to be returned

   234      * @return  all of the MIME headers in this <code>SOAPPart</code> object

   235      *          except those that match one of the names in the

   236      *           given array.  The nonmatching MIME headers are returned as an

   237      *           <code>Iterator</code> object.

   238      */

   239     public abstract Iterator getNonMatchingMimeHeaders(String[] names);

   241     /**

   242      * Sets the content of the <code>SOAPEnvelope</code> object with the data

   243      * from the given <code>Source</code> object. This <code>Source</code>

   244      * must contain a valid SOAP document.

   245      *

   246      * @param source the <code>javax.xml.transform.Source</code> object with the

   247      *        data to be set

   248      *

   249      * @exception SOAPException if there is a problem in setting the source

   250      * @see #getContent

   251      */

   252     public abstract void setContent(Source source) throws SOAPException;

   254     /**

   255      * Returns the content of the SOAPEnvelope as a JAXP <code>Source</code>

   256      * object.

   257      *

   258      * @return the content as a <code>javax.xml.transform.Source</code> object

   259      *

   260      * @exception SOAPException if the implementation cannot convert

   261      *                          the specified <code>Source</code> object

   262      * @see #setContent

   263      */

   264     public abstract Source getContent() throws SOAPException;

   265 }

Mercurial > jdk8-mips64-public > jaxws / file revision

src/share/jaxws_classes/javax/xml/soap/SOAPPart.java@9c07ef4934dd

src/share/jaxws_classes/javax/xml/soap/SOAPPart.java