001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one
003: * or more contributor license agreements. See the NOTICE file
004: * distributed with this work for additional information
005: * regarding copyright ownership. The ASF licenses this file
006: * to you under the Apache License, Version 2.0 (the
007: * "License"); you may not use this file except in compliance
008: * with the License. You may obtain a copy of the License at
009: *
010: * http://www.apache.org/licenses/LICENSE-2.0
011: *
012: * Unless required by applicable law or agreed to in writing,
013: * software distributed under the License is distributed on an
014: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015: * KIND, either express or implied. See the License for the
016: * specific language governing permissions and limitations
017: * under the License.
018: */
019: package javax.xml.soap;
020:
021: import java.util.Iterator;
022:
023: /**
024: * <P>A representation of the SOAP header element. A SOAP header element consists of XML data that
025: * affects the way the application-specific content is processed by the message provider. For
026: * example, transaction semantics, authentication information, and so on, can be specified as the
027: * content of a <CODE>SOAPHeader</CODE> object.</P>
028: * <p/>
029: * <P>A <CODE>SOAPEnvelope</CODE> object contains an empty <CODE> SOAPHeader</CODE> object by
030: * default. If the <CODE> SOAPHeader</CODE> object, which is optional, is not needed, it can be
031: * retrieved and deleted with the following line of code. The variable <I>se</I> is a
032: * <CODE>SOAPEnvelope</CODE> object.</P> <PRE> se.getHeader().detachNode(); </PRE> A
033: * <CODE>SOAPHeader</CODE> object is created with the <CODE> SOAPEnvelope</CODE> method
034: * <CODE>addHeaderBlock</CODE>. This method, which creates a new header and adds it to the envelope,
035: * may be called only after the existing header has been removed. <PRE> se.getHeader().detachNode();
036: * SOAPHeader sh = se.addHeaderBlock(); </PRE>
037: * <p/>
038: * <P>A <CODE>SOAPHeader</CODE> object can have only <CODE> SOAPHeaderElement</CODE> objects as its
039: * immediate children. The method <CODE>addHeaderElement</CODE> creates a new <CODE>
040: * HeaderElement</CODE> object and adds it to the <CODE> SOAPHeader</CODE> object. In the following
041: * line of code, the argument to the method <CODE>addHeaderElement</CODE> is a <CODE>Name</CODE>
042: * object that is the name for the new <CODE> HeaderElement</CODE> object.</P> <PRE>
043: * SOAPHeaderElement shElement = sh.addHeaderElement(name); </PRE>
044: *
045: * @see SOAPHeaderElement SOAPHeaderElement
046: */
047: public interface SOAPHeader extends SOAPElement {
048:
049: /**
050: * Creates a new <CODE>SOAPHeaderElement</CODE> object initialized with the specified name and
051: * adds it to this <CODE>SOAPHeader</CODE> object.
052: *
053: * @param name a <CODE>Name</CODE> object with the name of the new <CODE>SOAPHeaderElement</CODE>
054: * object
055: * @return the new <CODE>SOAPHeaderElement</CODE> object that was inserted into this
056: * <CODE>SOAPHeader</CODE> object
057: * @throws SOAPException if a SOAP error occurs
058: */
059: public abstract SOAPHeaderElement addHeaderElement(Name name)
060: throws SOAPException;
061:
062: /**
063: * Returns a list of all the <CODE>SOAPHeaderElement</CODE> objects in this
064: * <CODE>SOAPHeader</CODE> object that have the the specified actor. An actor is a global
065: * attribute that indicates the intermediate parties to whom the message should be sent. An
066: * actor receives the message and then sends it to the next actor. The default actor is the
067: * ultimate intended recipient for the message, so if no actor attribute is included in a
068: * <CODE>SOAPHeader</CODE> object, the message is sent to its ultimate destination.
069: *
070: * @param actor a <CODE>String</CODE> giving the URI of the actor for which to search
071: * @return an <CODE>Iterator</CODE> object over all the <CODE> SOAPHeaderElement</CODE> objects
072: * that contain the specified actor
073: * @see #extractHeaderElements(String) extractHeaderElements(java.lang.String)
074: */
075: public abstract Iterator examineHeaderElements(String actor);
076:
077: /**
078: * Returns a list of all the <CODE>SOAPHeaderElement</CODE> objects in this
079: * <CODE>SOAPHeader</CODE> object that have the the specified actor and detaches them from this
080: * <CODE> SOAPHeader</CODE> object.
081: * <p/>
082: * <P>This method allows an actor to process only the parts of the <CODE>SOAPHeader</CODE>
083: * object that apply to it and to remove them before passing the message on to the next actor.
084: *
085: * @param actor a <CODE>String</CODE> giving the URI of the actor for which to search
086: * @return an <CODE>Iterator</CODE> object over all the <CODE> SOAPHeaderElement</CODE> objects
087: * that contain the specified actor
088: * @see #examineHeaderElements(String) examineHeaderElements(java.lang.String)
089: */
090: public abstract Iterator extractHeaderElements(String actor);
091:
092: /**
093: * Returns an <code>Iterator</code> over all the <code>SOAPHeaderElement</code> objects in this
094: * <code>SOAPHeader</code> object that have the specified actor and that have a MustUnderstand
095: * attribute whose value is equivalent to <code>true</code>.
096: *
097: * @param actor a <code>String</code> giving the URI of the actor for which to search
098: * @return an <code>Iterator</code> object over all the <code>SOAPHeaderElement</code> objects
099: * that contain the specified actor and are marked as MustUnderstand
100: */
101: public abstract Iterator examineMustUnderstandHeaderElements(
102: String actor);
103:
104: /**
105: * Returns an <code>Iterator</code> over all the <code>SOAPHeaderElement</code> objects in this
106: * <code>SOAPHeader</code> object.
107: *
108: * @return an <code>Iterator</code> object over all the <code>SOAPHeaderElement</code> objects
109: * contained by this <code>SOAPHeader</code>
110: */
111: public abstract Iterator examineAllHeaderElements();
112:
113: /**
114: * Returns an <code>Iterator</code> over all the <code>SOAPHeaderElement</code> objects in this
115: * <code>SOAPHeader </code> object and detaches them from this <code>SOAPHeader</code> object.
116: *
117: * @return an <code>Iterator</code> object over all the <code>SOAPHeaderElement</code> objects
118: * contained by this <code>SOAPHeader</code>
119: */
120: public abstract Iterator extractAllHeaderElements();
121:
122: public abstract SOAPHeaderElement addHeaderElement(
123: javax.xml.namespace.QName qname) throws SOAPException;
124:
125: public abstract SOAPHeaderElement addNotUnderstoodHeaderElement(
126: javax.xml.namespace.QName qname) throws SOAPException;
127:
128: public abstract SOAPHeaderElement addUpgradeHeaderElement(
129: java.util.Iterator iterator) throws SOAPException;
130:
131: public abstract SOAPHeaderElement addUpgradeHeaderElement(
132: java.lang.String[] as) throws SOAPException;
133:
134: public abstract SOAPHeaderElement addUpgradeHeaderElement(
135: java.lang.String s) throws SOAPException;
136: }
|