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 }