SOAPHeaderElement


1   /*
2    * $Id: SOAPHeaderElement.java,v 1.9 2005/04/05 22:46:27 mk125090 Exp $
3    * $Revision: 1.9 $
4    * $Date: 2005/04/05 22:46:27 $
5    */
6   
7   /*
8    * The contents of this file are subject to the terms
9    * of the Common Development and Distribution License
10   * (the License).  You may not use this file except in
11   * compliance with the License.
12   * 
13   * You can obtain a copy of the license at
14   * https://glassfish.dev.java.net/public/CDDLv1.0.html.
15   * See the License for the specific language governing
16   * permissions and limitations under the License.
17   * 
18   * When distributing Covered Code, include this CDDL
19   * Header Notice in each file and include the License file
20   * at https://glassfish.dev.java.net/public/CDDLv1.0.html.
21   * If applicable, add the following below the CDDL Header,
22   * with the fields enclosed by brackets [] replaced by
23   * you own identifying information:
24   * "Portions Copyrighted [year] [name of copyright owner]"
25   * 
26   * Copyright 2006 Sun Microsystems Inc. All Rights Reserved
27   */
28  package javax.xml.soap;
29  
30  /**
31   * An object representing the contents in the SOAP header part of the
32   * SOAP envelope.
33   * The immediate children of a <code>SOAPHeader</code> object can
34   * be represented only as <code>SOAPHeaderElement</code> objects.
35   * <P>
36   * A <code>SOAPHeaderElement</code> object can have other
37   * <code>SOAPElement</code> objects as its children.
38   */
39  public interface SOAPHeaderElement extends SOAPElement   {
40  
41      /**
42       * Sets the actor associated with this <code>SOAPHeaderElement</code>
43       * object to the specified actor. The default value of an actor is:
44       *          <code>SOAPConstants.URI_SOAP_ACTOR_NEXT</code>
45       * <P>
46       * If this <code>SOAPHeaderElement</code> supports SOAP 1.2 then this call is
47       * equivalent to {@link #setRole(String)}
48       * 
49       * @param  actorURI a <code>String</code> giving the URI of the actor
50       *           to set
51       *
52       * @exception IllegalArgumentException if there is a problem in
53       * setting the actor.
54       *
55       * @see #getActor
56       */
57      public void setActor(String   actorURI);
58  
59      /**
60       * Sets the <code>Role</code> associated with this <code>SOAPHeaderElement</code>
61       * object to the specified <code>Role</code>.
62       *
63       * @param uri - the URI of the <code>Role</code>
64       * 
65       * @throws SOAPException if there is an error in setting the role
66       * 
67       * @exception UnsupportedOperationException if this message does not 
68       *      support the SOAP 1.2 concept of Fault Role. 
69       * 
70       * @since SAAJ 1.3
71       */
72      public void setRole(String   uri) throws SOAPException  ;
73  
74      /**
75       * Returns the uri of the <i>actor</i> attribute of this
76       * <code>SOAPHeaderElement</code>.
77       *<P>
78       * If this <code>SOAPHeaderElement</code> supports SOAP 1.2 then this call is
79       * equivalent to {@link #getRole()}
80       * @return  a <code>String</code> giving the URI of the actor
81       * @see #setActor
82       */
83      public String   getActor();
84  
85      /**
86       * Returns the value of the <i>Role</i> attribute of this
87       * <code>SOAPHeaderElement</code>.
88       *
89       * @return a <code>String</code> giving the URI of the <code>Role</code>
90       * 
91       * @exception UnsupportedOperationException if this message does not 
92       *      support the SOAP 1.2 concept of Fault Role. 
93       * 
94       * @since SAAJ 1.3
95       */
96      public String   getRole();
97  
98      /**
99       * 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 }
169
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags