diff -r cb15fc6cc038 -r 9a2e5d103695 jaxws/src/java.xml.soap/share/classes/javax/xml/soap/SOAPHeader.java --- a/jaxws/src/java.xml.soap/share/classes/javax/xml/soap/SOAPHeader.java Thu Jan 15 11:18:14 2015 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,263 +0,0 @@ -/* - * Copyright (c) 2004, 2013, Oracle and/or its affiliates. All rights reserved. - * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. - * - * This code is free software; you can redistribute it and/or modify it - * under the terms of the GNU General Public License version 2 only, as - * published by the Free Software Foundation. Oracle designates this - * particular file as subject to the "Classpath" exception as provided - * by Oracle in the LICENSE file that accompanied this code. - * - * This code is distributed in the hope that it will be useful, but WITHOUT - * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or - * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License - * version 2 for more details (a copy is included in the LICENSE file that - * accompanied this code). - * - * You should have received a copy of the GNU General Public License version - * 2 along with this work; if not, write to the Free Software Foundation, - * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. - * - * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA - * or visit www.oracle.com if you need additional information or have any - * questions. - */ - -package javax.xml.soap; - -import java.util.Iterator; - -import javax.xml.namespace.QName; - -/** - * A representation of the SOAP header - * element. A SOAP header element consists of XML data that affects - * the way the application-specific content is processed by the message - * provider. For example, transaction semantics, authentication information, - * and so on, can be specified as the content of a SOAPHeader - * object. - *

- * A SOAPEnvelope object contains an empty - * SOAPHeader object by default. If the SOAPHeader - * object, which is optional, is not needed, it can be retrieved and deleted - * with the following line of code. The variable se is a - * SOAPEnvelope object. - *

- *      se.getHeader().detachNode();
- * 
- * - * A SOAPHeader object is created with the SOAPEnvelope - * method addHeader. This method, which creates a new header and adds it - * to the envelope, may be called only after the existing header has been removed. - * - *
- *      se.getHeader().detachNode();
- *      SOAPHeader sh = se.addHeader();
- * 
- *

- * A SOAPHeader object can have only SOAPHeaderElement - * objects as its immediate children. The method addHeaderElement - * creates a new HeaderElement object and adds it to the - * SOAPHeader object. In the following line of code, the - * argument to the method addHeaderElement is a Name - * object that is the name for the new HeaderElement object. - *

- *      SOAPHeaderElement shElement = sh.addHeaderElement(name);
- * 
- * - * @see SOAPHeaderElement - * @since 1.6 - */ -public interface SOAPHeader extends SOAPElement { - /** - * Creates a new SOAPHeaderElement object initialized with the - * specified name and adds it to this SOAPHeader object. - * - * @param name a Name object with the name of the new - * SOAPHeaderElement object - * @return the new SOAPHeaderElement object that was - * inserted into this SOAPHeader object - * @exception SOAPException if a SOAP error occurs - * @see SOAPHeader#addHeaderElement(javax.xml.namespace.QName) - */ - public SOAPHeaderElement addHeaderElement(Name name) - throws SOAPException; - - /** - * Creates a new SOAPHeaderElement object initialized with the - * specified qname and adds it to this SOAPHeader object. - * - * @param qname a QName object with the qname of the new - * SOAPHeaderElement object - * @return the new SOAPHeaderElement object that was - * inserted into this SOAPHeader object - * @exception SOAPException if a SOAP error occurs - * @see SOAPHeader#addHeaderElement(Name) - * @since 1.6, SAAJ 1.3 - */ - public SOAPHeaderElement addHeaderElement(QName qname) - throws SOAPException; - - /** - * Returns an Iterator over all the SOAPHeaderElement objects - * in this SOAPHeader object - * that have the specified actor and that have a MustUnderstand attribute - * whose value is equivalent to true. - *

- * In SOAP 1.2 the env:actor attribute is replaced by the env:role - * attribute, but with essentially the same semantics. - * - * @param actor a String giving the URI of the actor / role - * for which to search - * @return an Iterator object over all the - * SOAPHeaderElement objects that contain the specified - * actor / role and are marked as MustUnderstand - * @see #examineHeaderElements - * @see #extractHeaderElements - * @see SOAPConstants#URI_SOAP_ACTOR_NEXT - * - * @since 1.6, SAAJ 1.2 - */ - public Iterator examineMustUnderstandHeaderElements(String actor); - - /** - * Returns an Iterator over all the SOAPHeaderElement objects - * in this SOAPHeader object - * that have the specified actor. - * - * An actor is a global attribute that indicates the intermediate - * parties that should process a message before it reaches its ultimate - * receiver. An actor receives the message and processes it before sending - * it on to the next actor. The default actor is the ultimate intended - * recipient for the message, so if no actor attribute is included in a - * SOAPHeader object, it is sent to the ultimate receiver - * along with the message body. - *

- * In SOAP 1.2 the env:actor attribute is replaced by the env:role - * attribute, but with essentially the same semantics. - * - * @param actor a String giving the URI of the actor / role - * for which to search - * @return an Iterator object over all the - * SOAPHeaderElement objects that contain the specified - * actor / role - * @see #extractHeaderElements - * @see SOAPConstants#URI_SOAP_ACTOR_NEXT - */ - public Iterator examineHeaderElements(String actor); - - /** - * Returns an Iterator over all the SOAPHeaderElement objects - * in this SOAPHeader object - * that have the specified actor and detaches them - * from this SOAPHeader object. - *

- * This method allows an actor to process the parts of the - * SOAPHeader object that apply to it and to remove - * them before passing the message on to the next actor. - *

- * In SOAP 1.2 the env:actor attribute is replaced by the env:role - * attribute, but with essentially the same semantics. - * - * @param actor a String giving the URI of the actor / role - * for which to search - * @return an Iterator object over all the - * SOAPHeaderElement objects that contain the specified - * actor / role - * - * @see #examineHeaderElements - * @see SOAPConstants#URI_SOAP_ACTOR_NEXT - */ - public Iterator extractHeaderElements(String actor); - - /** - * Creates a new NotUnderstood SOAPHeaderElement object initialized - * with the specified name and adds it to this SOAPHeader object. - * This operation is supported only by SOAP 1.2. - * - * @param name a QName object with the name of the - * SOAPHeaderElement object that was not understood. - * @return the new SOAPHeaderElement object that was - * inserted into this SOAPHeader object - * @exception SOAPException if a SOAP error occurs. - * @exception UnsupportedOperationException if this is a SOAP 1.1 Header. - * @since 1.6, SAAJ 1.3 - */ - public SOAPHeaderElement addNotUnderstoodHeaderElement(QName name) - throws SOAPException; - - /** - * Creates a new Upgrade SOAPHeaderElement object initialized - * with the specified List of supported SOAP URIs and adds it to this - * SOAPHeader object. - * This operation is supported on both SOAP 1.1 and SOAP 1.2 header. - * - * @param supportedSOAPURIs an Iterator object with the URIs of SOAP - * versions supported. - * @return the new SOAPHeaderElement object that was - * inserted into this SOAPHeader object - * @exception SOAPException if a SOAP error occurs. - * @since 1.6, SAAJ 1.3 - */ - public SOAPHeaderElement addUpgradeHeaderElement(Iterator supportedSOAPURIs) - throws SOAPException; - - /** - * Creates a new Upgrade SOAPHeaderElement object initialized - * with the specified array of supported SOAP URIs and adds it to this - * SOAPHeader object. - * This operation is supported on both SOAP 1.1 and SOAP 1.2 header. - * - * @param supportedSoapUris an array of the URIs of SOAP versions supported. - * @return the new SOAPHeaderElement object that was - * inserted into this SOAPHeader object - * @exception SOAPException if a SOAP error occurs. - * @since 1.6, SAAJ 1.3 - */ - public SOAPHeaderElement addUpgradeHeaderElement(String[] supportedSoapUris) - throws SOAPException; - - /** - * Creates a new Upgrade SOAPHeaderElement object initialized - * with the specified supported SOAP URI and adds it to this - * SOAPHeader object. - * This operation is supported on both SOAP 1.1 and SOAP 1.2 header. - * - * @param supportedSoapUri the URI of SOAP the version that is supported. - * @return the new SOAPHeaderElement object that was - * inserted into this SOAPHeader object - * @exception SOAPException if a SOAP error occurs. - * @since 1.6, SAAJ 1.3 - */ - public SOAPHeaderElement addUpgradeHeaderElement(String supportedSoapUri) - throws SOAPException; - - /** - * Returns an Iterator over all the SOAPHeaderElement objects - * in this SOAPHeader object. - * - * @return an Iterator object over all the - * SOAPHeaderElement objects contained by this - * SOAPHeader - * @see #extractAllHeaderElements - * - * @since 1.6, SAAJ 1.2 - */ - public Iterator examineAllHeaderElements(); - - /** - * Returns an Iterator over all the SOAPHeaderElement objects - * in this SOAPHeader object and detaches them - * from this SOAPHeader object. - * - * @return an Iterator object over all the - * SOAPHeaderElement objects contained by this - * SOAPHeader - * - * @see #examineAllHeaderElements - * - * @since 1.6, SAAJ 1.2 - */ - public Iterator extractAllHeaderElements(); - -}