1 /*
2 * Copyright 2005-2011 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} element in a SOAP message. A SOAP header contains {@code SoapHeaderElement}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} that represents the contents of the header.
36 * <p/>
37 * The result can be used for marshalling.
38 *
39 * @return the {@code Result} of this element
40 */
41 Result getResult();
42
43 /**
44 * Adds a new {@code SoapHeaderElement} 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}
48 * @throws SoapHeaderException if the header cannot be created
49 */
50 SoapHeaderElement addHeaderElement(QName name) throws SoapHeaderException;
51
52 /**
53 * Removes the {@code SoapHeaderElement} 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} over all the {@code SoapHeaderElement}s that have the specified actor or
65 * role and that have a {@code MustUnderstand} attribute whose value is equivalent to {@code true}.
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}
70 * @throws SoapHeaderException if the headers cannot be returned
71 * @see SoapHeaderElement
72 */
73 Iterator<SoapHeaderElement> examineMustUnderstandHeaderElements(String actorOrRole) throws SoapHeaderException;
74
75 /**
76 * Returns an {@code Iterator} over all the {@code SoapHeaderElement}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<SoapHeaderElement> examineAllHeaderElements() throws SoapHeaderException;
83
84 /**
85 * Returns an {@code Iterator} over all the {@code SoapHeaderElement}s with the given qualified name in this header.
86 *
87 * @param name the qualified name for which to search
88 * @return an iterator over all the header elements
89 * @throws SoapHeaderException if the header cannot be returned
90 * @see SoapHeaderElement
91 * @since 2.0.3
92 */
93 Iterator<SoapHeaderElement> examineHeaderElements(QName name) throws SoapHeaderException;
94
95 }