001: /*
002: * $Id: SOAPHeaderElement.java,v 1.10 2006/03/30 00:59:42 ofung Exp $
003: * $Revision: 1.10 $
004: * $Date: 2006/03/30 00:59:42 $
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: /**
031: * An object representing the contents in the SOAP header part of the
032: * SOAP envelope.
033: * The immediate children of a <code>SOAPHeader</code> object can
034: * be represented only as <code>SOAPHeaderElement</code> objects.
035: * <P>
036: * A <code>SOAPHeaderElement</code> object can have other
037: * <code>SOAPElement</code> objects as its children.
038: */
039: public interface SOAPHeaderElement extends SOAPElement {
040:
041: /**
042: * Sets the actor associated with this <code>SOAPHeaderElement</code>
043: * object to the specified actor. The default value of an actor is:
044: * <code>SOAPConstants.URI_SOAP_ACTOR_NEXT</code>
045: * <P>
046: * If this <code>SOAPHeaderElement</code> supports SOAP 1.2 then this call is
047: * equivalent to {@link #setRole(String)}
048: *
049: * @param actorURI a <code>String</code> giving the URI of the actor
050: * to set
051: *
052: * @exception IllegalArgumentException if there is a problem in
053: * setting the actor.
054: *
055: * @see #getActor
056: */
057: public void setActor(String actorURI);
058:
059: /**
060: * Sets the <code>Role</code> associated with this <code>SOAPHeaderElement</code>
061: * object to the specified <code>Role</code>.
062: *
063: * @param uri - the URI of the <code>Role</code>
064: *
065: * @throws SOAPException if there is an error in setting the role
066: *
067: * @exception UnsupportedOperationException if this message does not
068: * support the SOAP 1.2 concept of Fault Role.
069: *
070: * @since SAAJ 1.3
071: */
072: public void setRole(String uri) throws SOAPException;
073:
074: /**
075: * Returns the uri of the <i>actor</i> attribute of this
076: * <code>SOAPHeaderElement</code>.
077: *<P>
078: * If this <code>SOAPHeaderElement</code> supports SOAP 1.2 then this call is
079: * equivalent to {@link #getRole()}
080: * @return a <code>String</code> giving the URI of the actor
081: * @see #setActor
082: */
083: public String getActor();
084:
085: /**
086: * Returns the value of the <i>Role</i> attribute of this
087: * <code>SOAPHeaderElement</code>.
088: *
089: * @return a <code>String</code> giving the URI of the <code>Role</code>
090: *
091: * @exception UnsupportedOperationException if this message does not
092: * support the SOAP 1.2 concept of Fault Role.
093: *
094: * @since SAAJ 1.3
095: */
096: public String getRole();
097:
098: /**
099: * Sets the mustUnderstand attribute for this <code>SOAPHeaderElement</code>
100: * object to be either true or false.
101: * <P>
102: * If the mustUnderstand attribute is on, the actor who receives the
103: * <code>SOAPHeaderElement</code> must process it correctly. This
104: * ensures, for example, that if the <code>SOAPHeaderElement</code>
105: * object modifies the message, that the message is being modified correctly.
106: *
107: * @param mustUnderstand <code>true</code> to set the mustUnderstand
108: * attribute to true; <code>false</code> to set it to false
109: *
110: * @exception IllegalArgumentException if there is a problem in
111: * setting the mustUnderstand attribute
112: * @see #getMustUnderstand
113: * @see #setRelay
114: */
115: public void setMustUnderstand(boolean mustUnderstand);
116:
117: /**
118: * Returns the boolean value of the mustUnderstand attribute for this
119: * <code>SOAPHeaderElement</code>.
120: *
121: * @return <code>true</code> if the mustUnderstand attribute of this
122: * <code>SOAPHeaderElement</code> object is turned on; <code>false</code>
123: * otherwise
124: */
125: public boolean getMustUnderstand();
126:
127: /**
128: * Sets the <i>relay</i> attribute for this <code>SOAPHeaderElement</code> to be
129: * either true or false.
130: * <P>
131: * The SOAP relay attribute is set to true to indicate that the SOAP header
132: * block must be relayed by any node that is targeted by the header block
133: * but not actually process it. This attribute is ignored on header blocks
134: * whose mustUnderstand attribute is set to true or that are targeted at
135: * the ultimate reciever (which is the default). The default value of this
136: * attribute is <code>false</code>.
137: *
138: * @param relay the new value of the <i>relay</i> attribute
139: *
140: * @exception SOAPException if there is a problem in setting the
141: * relay attribute.
142: * @exception UnsupportedOperationException if this message does not
143: * support the SOAP 1.2 concept of Relay attribute.
144: *
145: * @see #setMustUnderstand
146: * @see #getRelay
147: *
148: * @since SAAJ 1.3
149: */
150: public void setRelay(boolean relay) throws SOAPException;
151:
152: /**
153: * Returns the boolean value of the <i>relay</i> attribute for this
154: * <code>SOAPHeaderElement</code>
155: *
156: * @return <code>true</code> if the relay attribute is turned on;
157: * <code>false</code> otherwise
158: *
159: * @exception UnsupportedOperationException if this message does not
160: * support the SOAP 1.2 concept of Relay attribute.
161: *
162: * @see #getMustUnderstand
163: * @see #setRelay
164: *
165: * @since SAAJ 1.3
166: */
167: public boolean getRelay();
168: }
|