SOAPPart.java revision 325
325N/A * Copyright (c) 2004, 2011, Oracle and/or its affiliates. All rights reserved. 325N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 325N/A * This code is free software; you can redistribute it and/or modify it 325N/A * under the terms of the GNU General Public License version 2 only, as 325N/A * published by the Free Software Foundation. Oracle designates this 325N/A * particular file as subject to the "Classpath" exception as provided 325N/A * by Oracle in the LICENSE file that accompanied this code. 325N/A * This code is distributed in the hope that it will be useful, but WITHOUT 325N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 325N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 325N/A * version 2 for more details (a copy is included in the LICENSE file that 325N/A * accompanied this code). 325N/A * You should have received a copy of the GNU General Public License version 325N/A * 2 along with this work; if not, write to the Free Software Foundation, 325N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 325N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 325N/A * or visit www.oracle.com if you need additional information or have any 325N/A * The container for the SOAP-specific portion of a <code>SOAPMessage</code> 325N/A * object. All messages are required to have a SOAP part, so when a 325N/A * <code>SOAPMessage</code> object is created, it will automatically 325N/A * have a <code>SOAPPart</code> object. 325N/A * A <code>SOAPPart</code> object is a MIME part and has the MIME headers 325N/A * Content-Id, Content-Location, and Content-Type. Because the value of 325N/A * Content-Type must be "text/xml", a <code>SOAPPart</code> object automatically 325N/A * has a MIME header of Content-Type with its value set to "text/xml". 325N/A * The value must be "text/xml" because content in the SOAP part of a 325N/A * message must be in XML format. Content that is not of type "text/xml" 325N/A * must be in an <code>AttachmentPart</code> object rather than in the 325N/A * <code>SOAPPart</code> object. 325N/A * When a message is sent, its SOAP part must have the MIME header Content-Type 325N/A * set to "text/xml". Or, from the other perspective, the SOAP part of any 325N/A * message that is received must have the MIME header Content-Type with a 325N/A * A client can access the <code>SOAPPart</code> object of a 325N/A * <code>SOAPMessage</code> object by 325N/A * calling the method <code>SOAPMessage.getSOAPPart</code>. The 325N/A * following line of code, in which <code>message</code> is a 325N/A * <code>SOAPMessage</code> object, retrieves the SOAP part of a message. 325N/A * SOAPPart soapPart = message.getSOAPPart(); 325N/A * A <code>SOAPPart</code> object contains a <code>SOAPEnvelope</code> object, 325N/A * which in turn contains a <code>SOAPBody</code> object and a 325N/A * <code>SOAPHeader</code> object. 325N/A * The <code>SOAPPart</code> method <code>getEnvelope</code> can be used 325N/A * to retrieve the <code>SOAPEnvelope</code> object. 325N/A * Gets the <code>SOAPEnvelope</code> object associated with this 325N/A * <code>SOAPPart</code> object. Once the SOAP envelope is obtained, it 325N/A * can be used to get its contents. 325N/A * @return the <code>SOAPEnvelope</code> object for this 325N/A * <code>SOAPPart</code> object 325N/A * @exception SOAPException if there is a SOAP error 325N/A * Retrieves the value of the MIME header whose name is "Content-Id". 325N/A * @return a <code>String</code> giving the value of the MIME header 325N/A * Retrieves the value of the MIME header whose name is "Content-Location". 325N/A * @return a <code>String</code> giving the value of the MIME header whose 325N/A * name is "Content-Location" 325N/A * @see #setContentLocation 325N/A * Sets the value of the MIME header named "Content-Id" 325N/A * to the given <code>String</code>. 325N/A * @param contentId a <code>String</code> giving the value of the MIME 325N/A * @exception IllegalArgumentException if there is a problem in 325N/A * setting the content id 325N/A * Sets the value of the MIME header "Content-Location" 325N/A * to the given <code>String</code>. 325N/A * @param contentLocation a <code>String</code> giving the value 325N/A * header "Content-Location" 325N/A * @exception IllegalArgumentException if there is a problem in 325N/A * setting the content location. 325N/A * @see #getContentLocation 325N/A * Removes all MIME headers that match the given name. 325N/A * @param header a <code>String</code> giving the name of the MIME header(s) to 325N/A * Removes all the <code>MimeHeader</code> objects for this 325N/A * <code>SOAPEnvelope</code> object. 325N/A * Gets all the values of the <code>MimeHeader</code> object 325N/A * in this <code>SOAPPart</code> object that 325N/A * is identified by the given <code>String</code>. 325N/A * @param name the name of the header; example: "Content-Type" 325N/A * @return a <code>String</code> array giving all the values for the 325N/A * Changes the first header entry that matches the given header name 325N/A * so that its value is the given value, adding a new header with the 325N/A * given name and value if no 325N/A * existing header is a match. If there is a match, this method clears 325N/A * all existing values for the first header that matches and sets the 325N/A * given value instead. If more than one header has 325N/A * the given name, this method removes all of the matching headers after 325N/A * Note that RFC822 headers can contain only US-ASCII characters. 325N/A * @param name a <code>String</code> giving the header name 325N/A * @param value a <code>String</code> giving the value to be set. 325N/A * This value will be substituted for the current value(s) 325N/A * of the first header that is a match if there is one. 325N/A * If there is no match, this value will be the value for 325N/A * a new <code>MimeHeader</code> object. 325N/A * @exception IllegalArgumentException if there was a problem with 325N/A * the specified mime header name or value 325N/A * Creates a <code>MimeHeader</code> object with the specified 325N/A * name and value and adds it to this <code>SOAPPart</code> object. 325N/A * If a <code>MimeHeader</code> with the specified name already 325N/A * exists, this method adds the specified value to the already 325N/A * Note that RFC822 headers can contain only US-ASCII characters. 325N/A * @param name a <code>String</code> giving the header name 325N/A * @param value a <code>String</code> giving the value to be set 325N/A * @exception IllegalArgumentException if there was a problem with 325N/A * the specified mime header name or value 325N/A * Retrieves all the headers for this <code>SOAPPart</code> object 325N/A * as an iterator over the <code>MimeHeader</code> objects. 325N/A * @return an <code>Iterator</code> object with all of the Mime 325N/A * headers for this <code>SOAPPart</code> object 325N/A * Retrieves all <code>MimeHeader</code> objects that match a name in 325N/A * @param names a <code>String</code> array with the name(s) of the 325N/A * MIME headers to be returned 325N/A * @return all of the MIME headers that match one of the names in the 325N/A * given array, returned as an <code>Iterator</code> object 325N/A * Retrieves all <code>MimeHeader</code> objects whose name does 325N/A * not match a name in the given array. 325N/A * @param names a <code>String</code> array with the name(s) of the 325N/A * MIME headers not to be returned 325N/A * @return all of the MIME headers in this <code>SOAPPart</code> object 325N/A * except those that match one of the names in the 325N/A * given array. The nonmatching MIME headers are returned as an 325N/A * <code>Iterator</code> object. 325N/A * Sets the content of the <code>SOAPEnvelope</code> object with the data 325N/A * from the given <code>Source</code> object. This <code>Source</code> 325N/A * must contain a valid SOAP document. 325N/A * @param source the <code>javax.xml.transform.Source</code> object with the 325N/A * @exception SOAPException if there is a problem in setting the source 325N/A * Returns the content of the SOAPEnvelope as a JAXP <code>Source</code> 325N/A * @return the content as a <code>javax.xml.transform.Source</code> object 325N/A * @exception SOAPException if the implementation cannot convert 325N/A * the specified <code>Source</code> object