1 /* 2 * Copyright (c) 2004, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.xml.soap; 27 28 /** 29 * An object representing the contents in the SOAP header part of the 30 * SOAP envelope. 31 * The immediate children of a <code>SOAPHeader</code> object can 32 * be represented only as <code>SOAPHeaderElement</code> objects. 33 * <P> 34 * A <code>SOAPHeaderElement</code> object can have other 35 * <code>SOAPElement</code> objects as its children. 36 */ 37 public interface SOAPHeaderElement extends SOAPElement { 38 39 /** 40 * Sets the actor associated with this <code>SOAPHeaderElement</code> 41 * object to the specified actor. The default value of an actor is: 42 * <code>SOAPConstants.URI_SOAP_ACTOR_NEXT</code> 43 * <P> 44 * If this <code>SOAPHeaderElement</code> supports SOAP 1.2 then this call is 45 * equivalent to {@link #setRole(String)} 46 * 47 * @param actorURI a <code>String</code> giving the URI of the actor 48 * to set 49 * 50 * @exception IllegalArgumentException if there is a problem in 51 * setting the actor. 52 * 53 * @see #getActor 54 */ 55 public void setActor(String actorURI); 56 57 /** 58 * Sets the <code>Role</code> associated with this <code>SOAPHeaderElement</code> 59 * object to the specified <code>Role</code>. 60 * 61 * @param uri - the URI of the <code>Role</code> 62 * 63 * @throws SOAPException if there is an error in setting the role 64 * 65 * @exception UnsupportedOperationException if this message does not 66 * support the SOAP 1.2 concept of Fault Role. 67 * 68 * @since SAAJ 1.3 69 */ 70 public void setRole(String uri) throws SOAPException; 71 72 /** 73 * Returns the uri of the <i>actor</i> attribute of this 74 * <code>SOAPHeaderElement</code>. 75 *<P> 76 * If this <code>SOAPHeaderElement</code> supports SOAP 1.2 then this call is 77 * equivalent to {@link #getRole()} 78 * @return a <code>String</code> giving the URI of the actor 79 * @see #setActor 80 */ 81 public String getActor(); 82 83 /** 84 * Returns the value of the <i>Role</i> attribute of this 85 * <code>SOAPHeaderElement</code>. 86 * 87 * @return a <code>String</code> giving the URI of the <code>Role</code> 88 * 89 * @exception UnsupportedOperationException if this message does not 90 * support the SOAP 1.2 concept of Fault Role. 91 * 92 * @since SAAJ 1.3 93 */ 94 public String getRole(); 95 96 /** 97 * Sets the mustUnderstand attribute for this <code>SOAPHeaderElement</code> 98 * object to be either true or false. 99 * <P> 100 * If the mustUnderstand attribute is on, the actor who receives the 101 * <code>SOAPHeaderElement</code> must process it correctly. This 102 * ensures, for example, that if the <code>SOAPHeaderElement</code> 103 * object modifies the message, that the message is being modified correctly. 104 * 105 * @param mustUnderstand <code>true</code> to set the mustUnderstand 106 * attribute to true; <code>false</code> to set it to false 107 * 108 * @exception IllegalArgumentException if there is a problem in 109 * setting the mustUnderstand attribute 110 * @see #getMustUnderstand 111 * @see #setRelay 112 */ 113 public void setMustUnderstand(boolean mustUnderstand); 114 115 /** 116 * Returns the boolean value of the mustUnderstand attribute for this 117 * <code>SOAPHeaderElement</code>. 118 * 119 * @return <code>true</code> if the mustUnderstand attribute of this 120 * <code>SOAPHeaderElement</code> object is turned on; <code>false</code> 121 * otherwise 122 */ 123 public boolean getMustUnderstand(); 124 125 /** 126 * Sets the <i>relay</i> attribute for this <code>SOAPHeaderElement</code> to be 127 * either true or false. 128 * <P> 129 * The SOAP relay attribute is set to true to indicate that the SOAP header 130 * block must be relayed by any node that is targeted by the header block 131 * but not actually process it. This attribute is ignored on header blocks 132 * whose mustUnderstand attribute is set to true or that are targeted at 133 * the ultimate reciever (which is the default). The default value of this 134 * attribute is <code>false</code>. 135 * 136 * @param relay the new value of the <i>relay</i> attribute 137 * 138 * @exception SOAPException if there is a problem in setting the 139 * relay attribute. 140 * @exception UnsupportedOperationException if this message does not 141 * support the SOAP 1.2 concept of Relay attribute. 142 * 143 * @see #setMustUnderstand 144 * @see #getRelay 145 * 146 * @since SAAJ 1.3 147 */ 148 public void setRelay(boolean relay) throws SOAPException; 149 150 /** 151 * Returns the boolean value of the <i>relay</i> attribute for this 152 * <code>SOAPHeaderElement</code> 153 * 154 * @return <code>true</code> if the relay attribute is turned on; 155 * <code>false</code> otherwise 156 * 157 * @exception UnsupportedOperationException if this message does not 158 * support the SOAP 1.2 concept of Relay attribute. 159 * 160 * @see #getMustUnderstand 161 * @see #setRelay 162 * 163 * @since SAAJ 1.3 164 */ 165 public boolean getRelay(); 166 }