1 /*
2 * Copyright 2006 the original author or authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package org.springframework.ws.soap;
18
19 import java.util.Iterator;
20 import javax.xml.namespace.QName;
21 import javax.xml.transform.Result;
22
23 /**
24 * Represents the <code>Header</code> element in a SOAP message. A SOAP header contains <code>SoapHeaderElement</code>s,
25 * which represent the individual headers.
26 *
27 * @author Arjen Poutsma
28 * @see SoapHeaderElement
29 * @see SoapEnvelope#getHeader()
30 * @since 1.0.0
31 */
32 public interface SoapHeader extends SoapElement {
33
34 /**
35 * Returns a <code>Result</code> that represents the concents of the header.
36 * <p/>
37 * The result can be used for marshalling.
38 *
39 * @return the <code>Result</code> of this element
40 */
41 Result getResult();
42
43 /**
44 * Adds a new <code>SoapHeaderElement</code> with the specified qualified name to this header.
45 *
46 * @param name the qualified name of the new header element
47 * @return the created <code>SoapHeaderElement</code>
48 * @throws SoapHeaderException if the header cannot be created
49 */
50 SoapHeaderElement addHeaderElement(QName name) throws SoapHeaderException;
51
52 /**
53 * Removes the <code>SoapHeaderElement</code> with the specified qualified name from this header.
54 * <p/>
55 * This method will only remove the first child element with the specified name. If no element is found with the
56 * specified name, this method has no effect.
57 *
58 * @param name the qualified name of the header element to be removed
59 * @throws SoapHeaderException if the header cannot be removed
60 */
61 void removeHeaderElement(QName name) throws SoapHeaderException;
62
63 /**
64 * Returns an <code>Iterator</code> over all the <code>SoapHeaderElement</code>s that have the specified actor or
65 * role and that have a <code>MustUnderstand</code> attribute whose value is equivalent to <code>true</code>.
66 *
67 * @param actorOrRole the actor (SOAP 1.1) or role (SOAP 1.2) for which to search
68 * @return an iterator over all the header elements that contain the specified actor/role and are marked as
69 * <code>MustUnderstand</code>
70 * @throws SoapHeaderException if the headers cannot be returned
71 * @see SoapHeaderElement
72 */
73 Iterator examineMustUnderstandHeaderElements(String actorOrRole) throws SoapHeaderException;
74
75 /**
76 * Returns an <code>Iterator</code> over all the <code>SoapHeaderElement</code>s in this header.
77 *
78 * @return an iterator over all the header elements
79 * @throws SoapHeaderException if the header cannot be returned
80 * @see SoapHeaderElement
81 */
82 Iterator examineAllHeaderElements() throws SoapHeaderException;
83
84 }