1/*
2 * Copyright (c) 2004, 2015, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.  Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26package javax.xml.soap;
27
28/**
29 * An object representing the contents in the SOAP header part of the
30 * SOAP envelope.
31 * The immediate children of a {@code SOAPHeader} object can
32 * be represented only as {@code SOAPHeaderElement} objects.
33 * <P>
34 * A {@code SOAPHeaderElement} object can have other
35 * {@code SOAPElement} objects as its children.
36 *
37 * @since 1.6
38 */
39public interface SOAPHeaderElement extends SOAPElement {
40
41    /**
42     * Sets the actor associated with this {@code SOAPHeaderElement}
43     * object to the specified actor. The default value of an actor is:
44     *          {@code SOAPConstants.URI_SOAP_ACTOR_NEXT}
45     * <P>
46     * If this {@code SOAPHeaderElement} supports SOAP 1.2 then this call is
47     * equivalent to {@link #setRole(String)}
48     *
49     * @param  actorURI a {@code String} 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} associated with this {@code SOAPHeaderElement}
61     * object to the specified {@code Role}.
62     *
63     * @param uri - the URI of the {@code Role}
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 1.6, 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}.
77     *<P>
78     * If this {@code SOAPHeaderElement} supports SOAP 1.2 then this call is
79     * equivalent to {@link #getRole()}
80     * @return  a {@code String} 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}.
88     *
89     * @return a {@code String} giving the URI of the {@code Role}
90     *
91     * @exception UnsupportedOperationException if this message does not
92     *      support the SOAP 1.2 concept of Fault Role.
93     *
94     * @since 1.6, SAAJ 1.3
95     */
96    public String getRole();
97
98    /**
99     * Sets the mustUnderstand attribute for this {@code SOAPHeaderElement}
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} must process it correctly. This
104     * ensures, for example, that if the {@code SOAPHeaderElement}
105     * object modifies the message, that the message is being modified correctly.
106     *
107     * @param mustUnderstand {@code true} to set the mustUnderstand
108     *        attribute to true; {@code false} 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}.
120     *
121     * @return {@code true} if the mustUnderstand attribute of this
122     *        {@code SOAPHeaderElement} object is turned on; {@code false}
123     *         otherwise
124     */
125    public boolean getMustUnderstand();
126
127    /**
128     * Sets the <i>relay</i> attribute for this {@code SOAPHeaderElement} 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}.
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 1.6, 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}
155     *
156     * @return {@code true} if the relay attribute is turned on;
157     * {@code false} 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 1.6, SAAJ 1.3
166     */
167    public boolean getRelay();
168}
169