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