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

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

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

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

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

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

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

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

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