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    }