001: /*
002: * $Id: SOAPHeader.java,v 1.15 2006/03/30 00:59:41 ofung Exp $
003: * $Revision: 1.15 $
004: * $Date: 2006/03/30 00:59:41 $
005: */
006:
007: /*
008: * The contents of this file are subject to the terms
009: * of the Common Development and Distribution License
010: * (the License). You may not use this file except in
011: * compliance with the License.
012: *
013: * You can obtain a copy of the license at
014: * https://glassfish.dev.java.net/public/CDDLv1.0.html.
015: * See the License for the specific language governing
016: * permissions and limitations under the License.
017: *
018: * When distributing Covered Code, include this CDDL
019: * Header Notice in each file and include the License file
020: * at https://glassfish.dev.java.net/public/CDDLv1.0.html.
021: * If applicable, add the following below the CDDL Header,
022: * with the fields enclosed by brackets [] replaced by
023: * you own identifying information:
024: * "Portions Copyrighted [year] [name of copyright owner]"
025: *
026: * Copyright 2006 Sun Microsystems Inc. All Rights Reserved
027: */
028: package javax.xml.soap;
029:
030: import java.util.Iterator;
031:
032: import javax.xml.namespace.QName;
033:
034: /**
035: * A representation of the SOAP header
036: * element. A SOAP header element consists of XML data that affects
037: * the way the application-specific content is processed by the message
038: * provider. For example, transaction semantics, authentication information,
039: * and so on, can be specified as the content of a <code>SOAPHeader</code>
040: * object.
041: * <P>
042: * A <code>SOAPEnvelope</code> object contains an empty
043: * <code>SOAPHeader</code> object by default. If the <code>SOAPHeader</code>
044: * object, which is optional, is not needed, it can be retrieved and deleted
045: * with the following line of code. The variable <i>se</i> is a
046: * <code>SOAPEnvelope</code> object.
047: * <PRE>
048: * se.getHeader().detachNode();
049: * </PRE>
050: *
051: * A <code>SOAPHeader</code> object is created with the <code>SOAPEnvelope</code>
052: * method <code>addHeader</code>. This method, which creates a new header and adds it
053: * to the envelope, may be called only after the existing header has been removed.
054: *
055: * <PRE>
056: * se.getHeader().detachNode();
057: * SOAPHeader sh = se.addHeader();
058: * </PRE>
059: * <P>
060: * A <code>SOAPHeader</code> object can have only <code>SOAPHeaderElement</code>
061: * objects as its immediate children. The method <code>addHeaderElement</code>
062: * creates a new <code>HeaderElement</code> object and adds it to the
063: * <code>SOAPHeader</code> object. In the following line of code, the
064: * argument to the method <code>addHeaderElement</code> is a <code>Name</code>
065: * object that is the name for the new <code>HeaderElement</code> object.
066: * <PRE>
067: * SOAPHeaderElement shElement = sh.addHeaderElement(name);
068: * </PRE>
069: *
070: * @see SOAPHeaderElement
071: */
072: public interface SOAPHeader extends SOAPElement {
073: /**
074: * Creates a new <code>SOAPHeaderElement</code> object initialized with the
075: * specified name and adds it to this <code>SOAPHeader</code> object.
076: *
077: * @param name a <code>Name</code> object with the name of the new
078: * <code>SOAPHeaderElement</code> object
079: * @return the new <code>SOAPHeaderElement</code> object that was
080: * inserted into this <code>SOAPHeader</code> object
081: * @exception SOAPException if a SOAP error occurs
082: * @see SOAPHeader#addHeaderElement(javax.xml.namespace.QName)
083: */
084: public SOAPHeaderElement addHeaderElement(Name name)
085: throws SOAPException;
086:
087: /**
088: * Creates a new <code>SOAPHeaderElement</code> object initialized with the
089: * specified qname and adds it to this <code>SOAPHeader</code> object.
090: *
091: * @param qname a <code>QName</code> object with the qname of the new
092: * <code>SOAPHeaderElement</code> object
093: * @return the new <code>SOAPHeaderElement</code> object that was
094: * inserted into this <code>SOAPHeader</code> object
095: * @exception SOAPException if a SOAP error occurs
096: * @see SOAPHeader#addHeaderElement(Name)
097: * @since SAAJ 1.3
098: */
099: public SOAPHeaderElement addHeaderElement(QName qname)
100: throws SOAPException;
101:
102: /**
103: * Returns an <code>Iterator</code> over all the <code>SOAPHeaderElement</code> objects
104: * in this <code>SOAPHeader</code> object
105: * that have the specified <i>actor</i> and that have a MustUnderstand attribute
106: * whose value is equivalent to <code>true</code>.
107: * <p>
108: * In SOAP 1.2 the <i>env:actor</i> attribute is replaced by the <i>env:role</i>
109: * attribute, but with essentially the same semantics.
110: *
111: * @param actor a <code>String</code> giving the URI of the <code>actor</code> / <code>role</code>
112: * for which to search
113: * @return an <code>Iterator</code> object over all the
114: * <code>SOAPHeaderElement</code> objects that contain the specified
115: * <code>actor</code> / <code>role</code> and are marked as MustUnderstand
116: * @see #examineHeaderElements
117: * @see #extractHeaderElements
118: * @see SOAPConstants#URI_SOAP_ACTOR_NEXT
119: *
120: * @since SAAJ 1.2
121: */
122: public Iterator examineMustUnderstandHeaderElements(String actor);
123:
124: /**
125: * Returns an <code>Iterator</code> over all the <code>SOAPHeaderElement</code> objects
126: * in this <code>SOAPHeader</code> object
127: * that have the specified <i>actor</i>.
128: *
129: * An <i>actor</i> is a global attribute that indicates the intermediate
130: * parties that should process a message before it reaches its ultimate
131: * receiver. An actor receives the message and processes it before sending
132: * it on to the next actor. The default actor is the ultimate intended
133: * recipient for the message, so if no actor attribute is included in a
134: * <code>SOAPHeader</code> object, it is sent to the ultimate receiver
135: * along with the message body.
136: * <p>
137: * In SOAP 1.2 the <i>env:actor</i> attribute is replaced by the <i>env:role</i>
138: * attribute, but with essentially the same semantics.
139: *
140: * @param actor a <code>String</code> giving the URI of the <code>actor</code> / <code>role</code>
141: * for which to search
142: * @return an <code>Iterator</code> object over all the
143: * <code>SOAPHeaderElement</code> objects that contain the specified
144: * <code>actor</code> / <code>role</code>
145: * @see #extractHeaderElements
146: * @see SOAPConstants#URI_SOAP_ACTOR_NEXT
147: */
148: public Iterator examineHeaderElements(String actor);
149:
150: /**
151: * Returns an <code>Iterator</code> over all the <code>SOAPHeaderElement</code> objects
152: * in this <code>SOAPHeader</code> object
153: * that have the specified <i>actor</i> and detaches them
154: * from this <code>SOAPHeader</code> object.
155: * <P>
156: * This method allows an actor to process the parts of the
157: * <code>SOAPHeader</code> object that apply to it and to remove
158: * them before passing the message on to the next actor.
159: * <p>
160: * In SOAP 1.2 the <i>env:actor</i> attribute is replaced by the <i>env:role</i>
161: * attribute, but with essentially the same semantics.
162: *
163: * @param actor a <code>String</code> giving the URI of the <code>actor</code> / <code>role</code>
164: * for which to search
165: * @return an <code>Iterator</code> object over all the
166: * <code>SOAPHeaderElement</code> objects that contain the specified
167: * <code>actor</code> / <code>role</code>
168: *
169: * @see #examineHeaderElements
170: * @see SOAPConstants#URI_SOAP_ACTOR_NEXT
171: */
172: public Iterator extractHeaderElements(String actor);
173:
174: /**
175: * Creates a new NotUnderstood <code>SOAPHeaderElement</code> object initialized
176: * with the specified name and adds it to this <code>SOAPHeader</code> object.
177: * This operation is supported only by SOAP 1.2.
178: *
179: * @param name a <code>QName</code> object with the name of the
180: * <code>SOAPHeaderElement</code> object that was not understood.
181: * @return the new <code>SOAPHeaderElement</code> object that was
182: * inserted into this <code>SOAPHeader</code> object
183: * @exception SOAPException if a SOAP error occurs.
184: * @exception UnsupportedOperationException if this is a SOAP 1.1 Header.
185: * @since SAAJ 1.3
186: */
187: public SOAPHeaderElement addNotUnderstoodHeaderElement(QName name)
188: throws SOAPException;
189:
190: /**
191: * Creates a new Upgrade <code>SOAPHeaderElement</code> object initialized
192: * with the specified List of supported SOAP URIs and adds it to this
193: * <code>SOAPHeader</code> object.
194: * This operation is supported on both SOAP 1.1 and SOAP 1.2 header.
195: *
196: * @param supportedSOAPURIs an <code>Iterator</code> object with the URIs of SOAP
197: * versions supported.
198: * @return the new <code>SOAPHeaderElement</code> object that was
199: * inserted into this <code>SOAPHeader</code> object
200: * @exception SOAPException if a SOAP error occurs.
201: * @since SAAJ 1.3
202: */
203: public SOAPHeaderElement addUpgradeHeaderElement(
204: Iterator supportedSOAPURIs) throws SOAPException;
205:
206: /**
207: * Creates a new Upgrade <code>SOAPHeaderElement</code> object initialized
208: * with the specified array of supported SOAP URIs and adds it to this
209: * <code>SOAPHeader</code> object.
210: * This operation is supported on both SOAP 1.1 and SOAP 1.2 header.
211: *
212: * @param supportedSoapUris an array of the URIs of SOAP versions supported.
213: * @return the new <code>SOAPHeaderElement</code> object that was
214: * inserted into this <code>SOAPHeader</code> object
215: * @exception SOAPException if a SOAP error occurs.
216: * @since SAAJ 1.3
217: */
218: public SOAPHeaderElement addUpgradeHeaderElement(
219: String[] supportedSoapUris) throws SOAPException;
220:
221: /**
222: * Creates a new Upgrade <code>SOAPHeaderElement</code> object initialized
223: * with the specified supported SOAP URI and adds it to this
224: * <code>SOAPHeader</code> object.
225: * This operation is supported on both SOAP 1.1 and SOAP 1.2 header.
226: *
227: * @param supportedSoapUri the URI of SOAP the version that is supported.
228: * @return the new <code>SOAPHeaderElement</code> object that was
229: * inserted into this <code>SOAPHeader</code> object
230: * @exception SOAPException if a SOAP error occurs.
231: * @since SAAJ 1.3
232: */
233: public SOAPHeaderElement addUpgradeHeaderElement(
234: String supportedSoapUri) throws SOAPException;
235:
236: /**
237: * Returns an <code>Iterator</code> over all the <code>SOAPHeaderElement</code> objects
238: * in this <code>SOAPHeader</code> object.
239: *
240: * @return an <code>Iterator</code> object over all the
241: * <code>SOAPHeaderElement</code> objects contained by this
242: * <code>SOAPHeader</code>
243: * @see #extractAllHeaderElements
244: *
245: * @since SAAJ 1.2
246: */
247: public Iterator examineAllHeaderElements();
248:
249: /**
250: * Returns an <code>Iterator</code> over all the <code>SOAPHeaderElement</code> objects
251: * in this <code>SOAPHeader</code> object and detaches them
252: * from this <code>SOAPHeader</code> object.
253: *
254: * @return an <code>Iterator</code> object over all the
255: * <code>SOAPHeaderElement</code> objects contained by this
256: * <code>SOAPHeader</code>
257: *
258: * @see #examineAllHeaderElements
259: *
260: * @since SAAJ 1.2
261: */
262: public Iterator extractAllHeaderElements();
263:
264: }
|