Save This Page
1 /* Copyright 2004 The Apache Software Foundation
2 *
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16 package org.apache.xmlbeans.impl.soap;
17
18 import java.util.Locale;
19
20 /**
21 * An element in the <CODE>SOAPBody</CODE> object that contains
22 * error and/or status information. This information may relate to
23 * errors in the <CODE>SOAPMessage</CODE> object or to problems
24 * that are not related to the content in the message itself.
25 * Problems not related to the message itself are generally errors
26 * in processing, such as the inability to communicate with an
27 * upstream server.
28 * <P>
29 * The <CODE>SOAPFault</CODE> interface provides methods for
30 * retrieving the information contained in a <CODE>
31 * SOAPFault</CODE> object and for setting the fault code, the
32 * fault actor, and a string describing the fault. A fault code is
33 * one of the codes defined in the SOAP 1.1 specification that
34 * describe the fault. An actor is an intermediate recipient to
35 * whom a message was routed. The message path may include one or
36 * more actors, or, if no actors are specified, the message goes
37 * only to the default actor, which is the final intended
38 * recipient.
39 */
40 public interface SOAPFault extends SOAPBodyElement {
41
42 /**
43 * Sets this <CODE>SOAPFault</CODE> object with the given
44 * fault code.
45 *
46 * <P>Fault codes, which given information about the fault,
47 * are defined in the SOAP 1.1 specification.</P>
48 * @param faultCode a <CODE>String</CODE> giving
49 * the fault code to be set; must be one of the fault codes
50 * defined in the SOAP 1.1 specification
51 * @throws SOAPException if there was an error in
52 * adding the <CODE>faultCode</CODE> to the underlying XML
53 * tree.
54 * @see #getFaultCode() getFaultCode()
55 */
56 public abstract void setFaultCode(String faultCode) throws SOAPException;
57
58 /**
59 * Gets the fault code for this <CODE>SOAPFault</CODE>
60 * object.
61 * @return a <CODE>String</CODE> with the fault code
62 * @see #setFaultCode(java.lang.String) setFaultCode(java.lang.String)
63 */
64 public abstract String getFaultCode();
65
66 /**
67 * Sets this <CODE>SOAPFault</CODE> object with the given
68 * fault actor.
69 *
70 * <P>The fault actor is the recipient in the message path who
71 * caused the fault to happen.</P>
72 * @param faultActor a <CODE>String</CODE>
73 * identifying the actor that caused this <CODE>
74 * SOAPFault</CODE> object
75 * @throws SOAPException if there was an error in
76 * adding the <CODE>faultActor</CODE> to the underlying XML
77 * tree.
78 * @see #getFaultActor() getFaultActor()
79 */
80 public abstract void setFaultActor(String faultActor) throws SOAPException;
81
82 /**
83 * Gets the fault actor for this <CODE>SOAPFault</CODE>
84 * object.
85 * @return a <CODE>String</CODE> giving the actor in the message
86 * path that caused this <CODE>SOAPFault</CODE> object
87 * @see #setFaultActor(java.lang.String) setFaultActor(java.lang.String)
88 */
89 public abstract String getFaultActor();
90
91 /**
92 * Sets the fault string for this <CODE>SOAPFault</CODE>
93 * object to the given string.
94 *
95 * @param faultString a <CODE>String</CODE>
96 * giving an explanation of the fault
97 * @throws SOAPException if there was an error in
98 * adding the <CODE>faultString</CODE> to the underlying XML
99 * tree.
100 * @see #getFaultString() getFaultString()
101 */
102 public abstract void setFaultString(String faultString)
103 throws SOAPException;
104
105 /**
106 * Gets the fault string for this <CODE>SOAPFault</CODE>
107 * object.
108 * @return a <CODE>String</CODE> giving an explanation of the
109 * fault
110 */
111 public abstract String getFaultString();
112
113 /**
114 * Returns the detail element for this <CODE>SOAPFault</CODE>
115 * object.
116 *
117 * <P>A <CODE>Detail</CODE> object carries
118 * application-specific error information related to <CODE>
119 * SOAPBodyElement</CODE> objects.</P>
120 * @return a <CODE>Detail</CODE> object with
121 * application-specific error information
122 */
123 public abstract Detail getDetail();
124
125 /**
126 * Creates a <CODE>Detail</CODE> object and sets it as the
127 * <CODE>Detail</CODE> object for this <CODE>SOAPFault</CODE>
128 * object.
129 *
130 * <P>It is illegal to add a detail when the fault already
131 * contains a detail. Therefore, this method should be called
132 * only after the existing detail has been removed.</P>
133 * @return the new <CODE>Detail</CODE> object
134 * @throws SOAPException if this
135 * <CODE>SOAPFault</CODE> object already contains a valid
136 * <CODE>Detail</CODE> object
137 */
138 public abstract Detail addDetail() throws SOAPException;
139
140 /**
141 * Sets this <code>SOAPFault</code> object with the given fault code.
142 *
143 * Fault codes, which give information about the fault, are defined in the
144 * SOAP 1.1 specification. A fault code is mandatory and must be of type
145 * <code>QName</code>. This method provides a convenient way to set a fault
146 * code. For example,
147 *
148 * <pre>
149 SOAPEnvelope se = ...;
150 // Create a qualified name in the SOAP namespace with a localName
151 // of "Client". Note that prefix parameter is optional and is null
152 // here which causes the implementation to use an appropriate prefix.
153 Name qname = se.createName("Client", null,
154 SOAPConstants.URI_NS_SOAP_ENVELOPE);
155 SOAPFault fault = ...;
156 fault.setFaultCode(qname);
157 *
158 * It is preferable to use this method over setFaultCode(String).
159 *
160 * @param name a <code>Name</code> object giving the fault code to be set.
161 * It must be namespace qualified.
162 * @throws SOAPException if there was an error in adding the
163 * <code>faultcode</code> element to the underlying XML tree
164 */
165 public abstract void setFaultCode(Name name) throws SOAPException;
166
167 /**
168 * Gets the mandatory SOAP 1.1 fault code for this <code>SOAPFault</code>
169 * object as a SAAJ <code>Name</code> object. The SOAP 1.1 specification
170 * requires the value of the "faultcode" element to be of type QName. This
171 * method returns the content of the element as a QName in the form of a
172 * SAAJ <code>Name</code> object. This method should be used instead of the
173 * <code>getFaultCode()</code> method since it allows applications to easily
174 * access the namespace name without additional parsing.
175 * <p>
176 * In the future, a QName object version of this method may also be added.
177 * @return a <code>Name</code> representing the faultcode
178 */
179 public abstract Name getFaultCodeAsName();
180
181 /**
182 * Sets the fault string for this <code>SOAPFault</code> object to the given
183 * string and localized to the given locale.
184 *
185 * @param faultString a <code>String</code> giving an explanation of
186 * the fault
187 * @param locale a <code>Locale</code> object indicating the
188 * native language of the <code>faultString</code>
189 * @throws SOAPException if there was an error in adding the
190 * <code>faultString</code> to the underlying XML tree
191 */
192 public abstract void setFaultString(String faultString, Locale locale) throws SOAPException;
193
194 /**
195 * Returns the optional detail element for this <code>SOAPFault</code>
196 * object.
197 *
198 * @return a <code>Locale</code> object indicating the native language of
199 * the fault string or <code>null</code> if no locale was
200 * specified
201 */
202 public abstract Locale getFaultStringLocale();
203 }