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