View Javadoc

1   /*
2    * Copyright 2001-2004 The Apache Software Foundation.
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  package javax.xml.soap;
17  
18  /**
19   *     <P>An object representing the contents in the SOAP header part
20   *   of the SOAP envelope. The immediate children of a <CODE>
21   *   SOAPHeader</CODE> object can be represented only as <CODE>
22   *   SOAPHeaderElement</CODE> objects.</P>
23   *
24   *   <P>A <CODE>SOAPHeaderElement</CODE> object can have other
25   *   <CODE>SOAPElement</CODE> objects as its children.</P>
26   */
27  public interface SOAPHeaderElement extends SOAPElement {
28  
29      /**
30       * Sets the actor associated with this <CODE>
31       * SOAPHeaderElement</CODE> object to the specified actor. The
32       * default value of an actor is: <CODE>
33       * SOAPConstants.URI_SOAP_ACTOR_NEXT</CODE>
34       * @param  actorURI  a <CODE>String</CODE> giving
35       *     the URI of the actor to set
36       * @see #getActor() getActor()
37       * @throws java.lang.IllegalArgumentException if
38       *     there is a problem in setting the actor.
39       */
40      public abstract void setActor(String actorURI);
41  
42      /**
43       * Returns the uri of the actor associated with this <CODE>
44       * SOAPHeaderElement</CODE> object.
45       * @return  a <CODE>String</CODE> giving the URI of the
46       *     actor
47       * @see #setActor(java.lang.String) setActor(java.lang.String)
48       */
49      public abstract String getActor();
50  
51      /**
52       * Sets the mustUnderstand attribute for this <CODE>
53       *   SOAPHeaderElement</CODE> object to be on or off.
54       *
55       *   <P>If the mustUnderstand attribute is on, the actor who
56       *   receives the <CODE>SOAPHeaderElement</CODE> must process it
57       *   correctly. This ensures, for example, that if the <CODE>
58       *   SOAPHeaderElement</CODE> object modifies the message, that
59       *   the message is being modified correctly.</P>
60       * @param  mustUnderstand  <CODE>true</CODE> to
61       *     set the mustUnderstand attribute on; <CODE>false</CODE>
62       *     to turn if off
63       * @throws java.lang.IllegalArgumentException if
64       *     there is a problem in setting the actor.
65       * @see #getMustUnderstand() getMustUnderstand()
66       */
67      public abstract void setMustUnderstand(boolean mustUnderstand);
68  
69      /**
70       * Returns whether the mustUnderstand attribute for this
71       * <CODE>SOAPHeaderElement</CODE> object is turned on.
72       * @return  <CODE>true</CODE> if the mustUnderstand attribute of
73       *     this <CODE>SOAPHeaderElement</CODE> object is turned on;
74       *     <CODE>false</CODE> otherwise
75       */
76      public abstract boolean getMustUnderstand();
77  }