001    /*
002     * Copyright 2001-2004 The Apache Software Foundation.
003     * 
004     * Licensed under the Apache License, Version 2.0 (the "License");
005     * you may not use this file except in compliance with the License.
006     * You may obtain a copy of the License at
007     * 
008     *      http://www.apache.org/licenses/LICENSE-2.0
009     * 
010     * Unless required by applicable law or agreed to in writing, software
011     * distributed under the License is distributed on an "AS IS" BASIS,
012     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013     * See the License for the specific language governing permissions and
014     * limitations under the License.
015     */
016    package javax.xml.soap;
017    
018    /**
019     *     <P>An object representing the contents in the SOAP header part
020     *   of the SOAP envelope. The immediate children of a <CODE>
021     *   SOAPHeader</CODE> object can be represented only as <CODE>
022     *   SOAPHeaderElement</CODE> objects.</P>
023     *
024     *   <P>A <CODE>SOAPHeaderElement</CODE> object can have other
025     *   <CODE>SOAPElement</CODE> objects as its children.</P>
026     */
027    public interface SOAPHeaderElement extends SOAPElement {
028    
029        /**
030         * Sets the actor associated with this <CODE>
031         * SOAPHeaderElement</CODE> object to the specified actor. The
032         * default value of an actor is: <CODE>
033         * SOAPConstants.URI_SOAP_ACTOR_NEXT</CODE>
034         * @param  actorURI  a <CODE>String</CODE> giving
035         *     the URI of the actor to set
036         * @see #getActor() getActor()
037         * @throws java.lang.IllegalArgumentException if
038         *     there is a problem in setting the actor.
039         */
040        public abstract void setActor(String actorURI);
041    
042        /**
043         * Returns the uri of the actor associated with this <CODE>
044         * SOAPHeaderElement</CODE> object.
045         * @return  a <CODE>String</CODE> giving the URI of the
046         *     actor
047         * @see #setActor(java.lang.String) setActor(java.lang.String)
048         */
049        public abstract String getActor();
050    
051        /**
052         * Sets the mustUnderstand attribute for this <CODE>
053         *   SOAPHeaderElement</CODE> object to be on or off.
054         *
055         *   <P>If the mustUnderstand attribute is on, the actor who
056         *   receives the <CODE>SOAPHeaderElement</CODE> must process it
057         *   correctly. This ensures, for example, that if the <CODE>
058         *   SOAPHeaderElement</CODE> object modifies the message, that
059         *   the message is being modified correctly.</P>
060         * @param  mustUnderstand  <CODE>true</CODE> to
061         *     set the mustUnderstand attribute on; <CODE>false</CODE>
062         *     to turn if off
063         * @throws java.lang.IllegalArgumentException if
064         *     there is a problem in setting the actor.
065         * @see #getMustUnderstand() getMustUnderstand()
066         */
067        public abstract void setMustUnderstand(boolean mustUnderstand);
068    
069        /**
070         * Returns whether the mustUnderstand attribute for this
071         * <CODE>SOAPHeaderElement</CODE> object is turned on.
072         * @return  <CODE>true</CODE> if the mustUnderstand attribute of
073         *     this <CODE>SOAPHeaderElement</CODE> object is turned on;
074         *     <CODE>false</CODE> otherwise
075         */
076        public abstract boolean getMustUnderstand();
077    }