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 import java.util.Locale;
023
024 /**
025 * An element in the <CODE>SOAPBody</CODE> object that contains
026 * error and/or status information. This information may relate to
027 * errors in the <CODE>SOAPMessage</CODE> object or to problems
028 * that are not related to the content in the message itself.
029 * Problems not related to the message itself are generally errors
030 * in processing, such as the inability to communicate with an
031 * upstream server.
032 * <P>
033 * The <CODE>SOAPFault</CODE> interface provides methods for
034 * retrieving the information contained in a <CODE>
035 * SOAPFault</CODE> object and for setting the fault code, the
036 * fault actor, and a string describing the fault. A fault code is
037 * one of the codes defined in the SOAP 1.1 specification that
038 * describe the fault. An actor is an intermediate recipient to
039 * whom a message was routed. The message path may include one or
040 * more actors, or, if no actors are specified, the message goes
041 * only to the default actor, which is the final intended
042 * recipient.
043 */
044 public interface SOAPFault extends SOAPBodyElement {
045
046 /**
047 * Sets this <CODE>SOAPFault</CODE> object with the given
048 * fault code.
049 *
050 * <P>Fault codes, which given information about the fault,
051 * are defined in the SOAP 1.1 specification.</P>
052 * @param faultCode a <CODE>String</CODE> giving
053 * the fault code to be set; must be one of the fault codes
054 * defined in the SOAP 1.1 specification
055 * @throws SOAPException if there was an error in
056 * adding the <CODE>faultCode</CODE> to the underlying XML
057 * tree.
058 * @see #getFaultCode() getFaultCode()
059 */
060 public abstract void setFaultCode(String faultCode) throws SOAPException;
061
062 /**
063 * Gets the fault code for this <CODE>SOAPFault</CODE>
064 * object.
065 * @return a <CODE>String</CODE> with the fault code
066 * @see #setFaultCode(java.lang.String) setFaultCode(java.lang.String)
067 */
068 public abstract String getFaultCode();
069
070 /**
071 * Sets this <CODE>SOAPFault</CODE> object with the given
072 * fault actor.
073 *
074 * <P>The fault actor is the recipient in the message path who
075 * caused the fault to happen.</P>
076 * @param faultActor a <CODE>String</CODE>
077 * identifying the actor that caused this <CODE>
078 * SOAPFault</CODE> object
079 * @throws SOAPException if there was an error in
080 * adding the <CODE>faultActor</CODE> to the underlying XML
081 * tree.
082 * @see #getFaultActor() getFaultActor()
083 */
084 public abstract void setFaultActor(String faultActor) throws SOAPException;
085
086 /**
087 * Gets the fault actor for this <CODE>SOAPFault</CODE>
088 * object.
089 * @return a <CODE>String</CODE> giving the actor in the message
090 * path that caused this <CODE>SOAPFault</CODE> object
091 * @see #setFaultActor(java.lang.String) setFaultActor(java.lang.String)
092 */
093 public abstract String getFaultActor();
094
095 /**
096 * Sets the fault string for this <CODE>SOAPFault</CODE>
097 * object to the given string.
098 *
099 * @param faultString a <CODE>String</CODE>
100 * giving an explanation of the fault
101 * @throws SOAPException if there was an error in
102 * adding the <CODE>faultString</CODE> to the underlying XML
103 * tree.
104 * @see #getFaultString() getFaultString()
105 */
106 public abstract void setFaultString(String faultString)
107 throws SOAPException;
108
109 /**
110 * Gets the fault string for this <CODE>SOAPFault</CODE>
111 * object.
112 * @return a <CODE>String</CODE> giving an explanation of the
113 * fault
114 */
115 public abstract String getFaultString();
116
117 /**
118 * Returns the detail element for this <CODE>SOAPFault</CODE>
119 * object.
120 *
121 * <P>A <CODE>Detail</CODE> object carries
122 * application-specific error information related to <CODE>
123 * SOAPBodyElement</CODE> objects.</P>
124 * @return a <CODE>Detail</CODE> object with
125 * application-specific error information
126 */
127 public abstract Detail getDetail();
128
129 /**
130 * Creates a <CODE>Detail</CODE> object and sets it as the
131 * <CODE>Detail</CODE> object for this <CODE>SOAPFault</CODE>
132 * object.
133 *
134 * <P>It is illegal to add a detail when the fault already
135 * contains a detail. Therefore, this method should be called
136 * only after the existing detail has been removed.</P>
137 * @return the new <CODE>Detail</CODE> object
138 * @throws SOAPException if this
139 * <CODE>SOAPFault</CODE> object already contains a valid
140 * <CODE>Detail</CODE> object
141 */
142 public abstract Detail addDetail() throws SOAPException;
143
144 /**
145 * Sets this <code>SOAPFault</code> object with the given fault code.
146 *
147 * Fault codes, which give information about the fault, are defined in the
148 * SOAP 1.1 specification. A fault code is mandatory and must be of type
149 * <code>QName</code>. This method provides a convenient way to set a fault
150 * code. For example,
151 *
152 * <pre>
153 SOAPEnvelope se = ...;
154 // Create a qualified name in the SOAP namespace with a localName
155 // of "Client". Note that prefix parameter is optional and is null
156 // here which causes the implementation to use an appropriate prefix.
157 Name qname = se.createName("Client", null,
158 SOAPConstants.URI_NS_SOAP_ENVELOPE);
159 SOAPFault fault = ...;
160 fault.setFaultCode(qname);
161 *
162 * It is preferable to use this method over setFaultCode(String).
163 *
164 * @param name a <code>Name</code> object giving the fault code to be set.
165 * It must be namespace qualified.
166 * @throws SOAPException if there was an error in adding the
167 * <code>faultcode</code> element to the underlying XML tree
168 */
169 public abstract void setFaultCode(Name name) throws SOAPException;
170
171 /**
172 * Gets the mandatory SOAP 1.1 fault code for this <code>SOAPFault</code>
173 * object as a SAAJ <code>Name</code> object. The SOAP 1.1 specification
174 * requires the value of the "faultcode" element to be of type QName. This
175 * method returns the content of the element as a QName in the form of a
176 * SAAJ <code>Name</code> object. This method should be used instead of the
177 * <code>getFaultCode()</code> method since it allows applications to easily
178 * access the namespace name without additional parsing.
179 * <p>
180 * In the future, a QName object version of this method may also be added.
181 * @return a <code>Name</code> representing the faultcode
182 */
183 public abstract Name getFaultCodeAsName();
184
185 /**
186 * Sets the fault string for this <code>SOAPFault</code> object to the given
187 * string and localized to the given locale.
188 *
189 * @param faultString a <code>String</code> giving an explanation of
190 * the fault
191 * @param locale a <code>Locale</code> object indicating the
192 * native language of the <code>faultString</code>
193 * @throws SOAPException if there was an error in adding the
194 * <code>faultString</code> to the underlying XML tree
195 */
196 public abstract void setFaultString(String faultString, Locale locale) throws SOAPException;
197
198 /**
199 * Returns the optional detail element for this <code>SOAPFault</code>
200 * object.
201 *
202 * @return a <code>Locale</code> object indicating the native language of
203 * the fault string or <code>null</code> if no locale was
204 * specified
205 */
206 public abstract Locale getFaultStringLocale();
207 }