org.apache.xmlbeans.impl.soap.SOAPHeader Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of commons-xmlbeans Show documentation
The Apache Commons Codec package contains simple encoder and decoders for various formats such as Base64 and Hexadecimal. In addition to these widely used encoders and decoders, the codec package also maintains a collection of phonetic encoding utilities.
The newest version!
/*   Copyright 2004 The Apache Software Foundation
 *
 *   Licensed under the Apache License, Version 2.0 (the "License");
 *   you may not use this file except in compliance with the License.
 *   You may obtain a copy of the License at
 *
 *       http://www.apache.org/licenses/LICENSE-2.0
 *
 *   Unless required by applicable law or agreed to in writing, software
 *   distributed under the License is distributed on an "AS IS" BASIS,
 *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *   See the License for the specific language governing permissions and
 *  limitations under the License.
 */

package org.apache.xmlbeans.impl.soap;

import java.util.Iterator;

/**
 * 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 SOAPHeaderElement
 */
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
     * @throws  SOAPException if a SOAP error occurs
     */
    public abstract SOAPHeaderElement addHeaderElement(Name name)
        throws SOAPException;

    /**
     * Returns a list of all the SOAPHeaderElement
     * objects in this SOAPHeader object that have the
     * the specified actor. An actor is a global attribute that
     * indicates the intermediate parties to whom the message should
     * be sent. An actor receives the message and then sends it 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, the message is
     * sent to its ultimate destination.
     * @param   actor  a String giving the
     *     URI of the actor for which to search
     * @return an Iterator object over all the 
     *     SOAPHeaderElement objects that contain the
     *     specified actor
     * @see #extractHeaderElements(java.lang.String) extractHeaderElements(java.lang.String)
     */
    public abstract Iterator examineHeaderElements(String actor);

    /**
     * Returns a list of all the SOAPHeaderElement
     *   objects in this SOAPHeader object that have
     *   the the specified actor and detaches them from this 
     *   SOAPHeader object.
     *
     *   This method allows an actor to process only the parts of
     *   the SOAPHeader object that apply to it and to
     *   remove them before passing the message on to the next
     *   actor.
     * @param   actor  a String giving the
     *     URI of the actor for which to search
     * @return an Iterator object over all the 
     *     SOAPHeaderElement objects that contain the
     *     specified actor
     * @see #examineHeaderElements(java.lang.String) examineHeaderElements(java.lang.String)
     */
    public abstract Iterator extractHeaderElements(String actor);

    /**
     * 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.
     *
     * @param actor a String giving the URI of the actor for which
     *              to search
     * @return an Iterator object over all the
     *              SOAPHeaderElement objects that contain the
     *              specified actor and are marked as MustUnderstand
     */
    public abstract Iterator examineMustUnderstandHeaderElements(String actor);

    /**
     * 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
     */
    public abstract 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
     */
    public abstract Iterator extractAllHeaderElements();
}