Thu, 31 Aug 2017 15:18:52 +0800
merge
aoqi@0 | 1 | /* |
aoqi@0 | 2 | * Copyright (c) 2004, 2012, Oracle and/or its affiliates. All rights reserved. |
aoqi@0 | 3 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
aoqi@0 | 4 | * |
aoqi@0 | 5 | * This code is free software; you can redistribute it and/or modify it |
aoqi@0 | 6 | * under the terms of the GNU General Public License version 2 only, as |
aoqi@0 | 7 | * published by the Free Software Foundation. Oracle designates this |
aoqi@0 | 8 | * particular file as subject to the "Classpath" exception as provided |
aoqi@0 | 9 | * by Oracle in the LICENSE file that accompanied this code. |
aoqi@0 | 10 | * |
aoqi@0 | 11 | * This code is distributed in the hope that it will be useful, but WITHOUT |
aoqi@0 | 12 | * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
aoqi@0 | 13 | * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
aoqi@0 | 14 | * version 2 for more details (a copy is included in the LICENSE file that |
aoqi@0 | 15 | * accompanied this code). |
aoqi@0 | 16 | * |
aoqi@0 | 17 | * You should have received a copy of the GNU General Public License version |
aoqi@0 | 18 | * 2 along with this work; if not, write to the Free Software Foundation, |
aoqi@0 | 19 | * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
aoqi@0 | 20 | * |
aoqi@0 | 21 | * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
aoqi@0 | 22 | * or visit www.oracle.com if you need additional information or have any |
aoqi@0 | 23 | * questions. |
aoqi@0 | 24 | */ |
aoqi@0 | 25 | |
aoqi@0 | 26 | package javax.xml.soap; |
aoqi@0 | 27 | |
aoqi@0 | 28 | import java.util.Iterator; |
aoqi@0 | 29 | import java.util.Locale; |
aoqi@0 | 30 | |
aoqi@0 | 31 | import javax.xml.namespace.QName; |
aoqi@0 | 32 | |
aoqi@0 | 33 | /** |
aoqi@0 | 34 | * An element in the <code>SOAPBody</code> object that contains |
aoqi@0 | 35 | * error and/or status information. This information may relate to |
aoqi@0 | 36 | * errors in the <code>SOAPMessage</code> object or to problems |
aoqi@0 | 37 | * that are not related to the content in the message itself. Problems |
aoqi@0 | 38 | * not related to the message itself are generally errors in |
aoqi@0 | 39 | * processing, such as the inability to communicate with an upstream |
aoqi@0 | 40 | * server. |
aoqi@0 | 41 | * <P> |
aoqi@0 | 42 | * Depending on the <code>protocol</code> specified while creating the |
aoqi@0 | 43 | * <code>MessageFactory</code> instance, a <code>SOAPFault</code> has |
aoqi@0 | 44 | * sub-elements as defined in the SOAP 1.1/SOAP 1.2 specification. |
aoqi@0 | 45 | */ |
aoqi@0 | 46 | public interface SOAPFault extends SOAPBodyElement { |
aoqi@0 | 47 | |
aoqi@0 | 48 | /** |
aoqi@0 | 49 | * Sets this <code>SOAPFault</code> object with the given fault code. |
aoqi@0 | 50 | * |
aoqi@0 | 51 | * <P> Fault codes, which give information about the fault, are defined |
aoqi@0 | 52 | * in the SOAP 1.1 specification. A fault code is mandatory and must |
aoqi@0 | 53 | * be of type <code>Name</code>. This method provides a convenient |
aoqi@0 | 54 | * way to set a fault code. For example, |
aoqi@0 | 55 | * |
aoqi@0 | 56 | * <PRE> |
aoqi@0 | 57 | * SOAPEnvelope se = ...; |
aoqi@0 | 58 | * // Create a qualified name in the SOAP namespace with a localName |
aoqi@0 | 59 | * // of "Client". Note that prefix parameter is optional and is null |
aoqi@0 | 60 | * // here which causes the implementation to use an appropriate prefix. |
aoqi@0 | 61 | * Name qname = se.createName("Client", null, |
aoqi@0 | 62 | * SOAPConstants.URI_NS_SOAP_ENVELOPE); |
aoqi@0 | 63 | * SOAPFault fault = ...; |
aoqi@0 | 64 | * fault.setFaultCode(qname); |
aoqi@0 | 65 | * </PRE> |
aoqi@0 | 66 | * It is preferable to use this method over {@link #setFaultCode(String)}. |
aoqi@0 | 67 | * |
aoqi@0 | 68 | * @param faultCodeQName a <code>Name</code> object giving the fault |
aoqi@0 | 69 | * code to be set. It must be namespace qualified. |
aoqi@0 | 70 | * @see #getFaultCodeAsName |
aoqi@0 | 71 | * |
aoqi@0 | 72 | * @exception SOAPException if there was an error in adding the |
aoqi@0 | 73 | * <i>faultcode</i> element to the underlying XML tree. |
aoqi@0 | 74 | * |
aoqi@0 | 75 | * @since SAAJ 1.2 |
aoqi@0 | 76 | */ |
aoqi@0 | 77 | public void setFaultCode(Name faultCodeQName) throws SOAPException; |
aoqi@0 | 78 | |
aoqi@0 | 79 | /** |
aoqi@0 | 80 | * Sets this <code>SOAPFault</code> object with the given fault code. |
aoqi@0 | 81 | * |
aoqi@0 | 82 | * It is preferable to use this method over {@link #setFaultCode(Name)}. |
aoqi@0 | 83 | * |
aoqi@0 | 84 | * @param faultCodeQName a <code>QName</code> object giving the fault |
aoqi@0 | 85 | * code to be set. It must be namespace qualified. |
aoqi@0 | 86 | * @see #getFaultCodeAsQName |
aoqi@0 | 87 | * |
aoqi@0 | 88 | * @exception SOAPException if there was an error in adding the |
aoqi@0 | 89 | * <code>faultcode</code> element to the underlying XML tree. |
aoqi@0 | 90 | * |
aoqi@0 | 91 | * @see #setFaultCode(Name) |
aoqi@0 | 92 | * @see #getFaultCodeAsQName() |
aoqi@0 | 93 | * |
aoqi@0 | 94 | * @since SAAJ 1.3 |
aoqi@0 | 95 | */ |
aoqi@0 | 96 | public void setFaultCode(QName faultCodeQName) throws SOAPException; |
aoqi@0 | 97 | |
aoqi@0 | 98 | /** |
aoqi@0 | 99 | * Sets this <code>SOAPFault</code> object with the give fault code. |
aoqi@0 | 100 | * <P> |
aoqi@0 | 101 | * Fault codes, which given information about the fault, are defined in |
aoqi@0 | 102 | * the SOAP 1.1 specification. This element is mandatory in SOAP 1.1. |
aoqi@0 | 103 | * Because the fault code is required to be a QName it is preferable to |
aoqi@0 | 104 | * use the {@link #setFaultCode(Name)} form of this method. |
aoqi@0 | 105 | * |
aoqi@0 | 106 | * @param faultCode a <code>String</code> giving the fault code to be set. |
aoqi@0 | 107 | * It must be of the form "prefix:localName" where the prefix has |
aoqi@0 | 108 | * been defined in a namespace declaration. |
aoqi@0 | 109 | * @see #setFaultCode(Name) |
aoqi@0 | 110 | * @see #getFaultCode |
aoqi@0 | 111 | * @see SOAPElement#addNamespaceDeclaration |
aoqi@0 | 112 | * |
aoqi@0 | 113 | * @exception SOAPException if there was an error in adding the |
aoqi@0 | 114 | * <code>faultCode</code> to the underlying XML tree. |
aoqi@0 | 115 | */ |
aoqi@0 | 116 | public void setFaultCode(String faultCode) throws SOAPException; |
aoqi@0 | 117 | |
aoqi@0 | 118 | /** |
aoqi@0 | 119 | * Gets the mandatory SOAP 1.1 fault code for this |
aoqi@0 | 120 | * <code>SOAPFault</code> object as a SAAJ <code>Name</code> object. |
aoqi@0 | 121 | * The SOAP 1.1 specification requires the value of the "faultcode" |
aoqi@0 | 122 | * element to be of type QName. This method returns the content of the |
aoqi@0 | 123 | * element as a QName in the form of a SAAJ Name object. This method |
aoqi@0 | 124 | * should be used instead of the <code>getFaultCode</code> method since |
aoqi@0 | 125 | * it allows applications to easily access the namespace name without |
aoqi@0 | 126 | * additional parsing. |
aoqi@0 | 127 | * |
aoqi@0 | 128 | * @return a <code>Name</code> representing the faultcode |
aoqi@0 | 129 | * @see #setFaultCode(Name) |
aoqi@0 | 130 | * |
aoqi@0 | 131 | * @since SAAJ 1.2 |
aoqi@0 | 132 | */ |
aoqi@0 | 133 | public Name getFaultCodeAsName(); |
aoqi@0 | 134 | |
aoqi@0 | 135 | |
aoqi@0 | 136 | /** |
aoqi@0 | 137 | * Gets the fault code for this |
aoqi@0 | 138 | * <code>SOAPFault</code> object as a <code>QName</code> object. |
aoqi@0 | 139 | * |
aoqi@0 | 140 | * @return a <code>QName</code> representing the faultcode |
aoqi@0 | 141 | * |
aoqi@0 | 142 | * @see #setFaultCode(QName) |
aoqi@0 | 143 | * |
aoqi@0 | 144 | * @since SAAJ 1.3 |
aoqi@0 | 145 | */ |
aoqi@0 | 146 | public QName getFaultCodeAsQName(); |
aoqi@0 | 147 | |
aoqi@0 | 148 | /** |
aoqi@0 | 149 | * Gets the Subcodes for this <code>SOAPFault</code> as an iterator over |
aoqi@0 | 150 | * <code>QNames</code>. |
aoqi@0 | 151 | * |
aoqi@0 | 152 | * @return an <code>Iterator</code> that accesses a sequence of |
aoqi@0 | 153 | * <code>QNames</code>. This <code>Iterator</code> should not support |
aoqi@0 | 154 | * the optional <code>remove</code> method. The order in which the |
aoqi@0 | 155 | * Subcodes are returned reflects the hierarchy of Subcodes present |
aoqi@0 | 156 | * in the fault from top to bottom. |
aoqi@0 | 157 | * |
aoqi@0 | 158 | * @exception UnsupportedOperationException if this message does not |
aoqi@0 | 159 | * support the SOAP 1.2 concept of Subcode. |
aoqi@0 | 160 | * |
aoqi@0 | 161 | * @since SAAJ 1.3 |
aoqi@0 | 162 | */ |
aoqi@0 | 163 | public Iterator getFaultSubcodes(); |
aoqi@0 | 164 | |
aoqi@0 | 165 | /** |
aoqi@0 | 166 | * Removes any Subcodes that may be contained by this |
aoqi@0 | 167 | * <code>SOAPFault</code>. Subsequent calls to |
aoqi@0 | 168 | * <code>getFaultSubcodes</code> will return an empty iterator until a call |
aoqi@0 | 169 | * to <code>appendFaultSubcode</code> is made. |
aoqi@0 | 170 | * |
aoqi@0 | 171 | * @exception UnsupportedOperationException if this message does not |
aoqi@0 | 172 | * support the SOAP 1.2 concept of Subcode. |
aoqi@0 | 173 | * |
aoqi@0 | 174 | * @since SAAJ 1.3 |
aoqi@0 | 175 | */ |
aoqi@0 | 176 | public void removeAllFaultSubcodes(); |
aoqi@0 | 177 | |
aoqi@0 | 178 | /** |
aoqi@0 | 179 | * Adds a Subcode to the end of the sequence of Subcodes contained by this |
aoqi@0 | 180 | * <code>SOAPFault</code>. Subcodes, which were introduced in SOAP 1.2, are |
aoqi@0 | 181 | * represented by a recursive sequence of subelements rooted in the |
aoqi@0 | 182 | * mandatory Code subelement of a SOAP Fault. |
aoqi@0 | 183 | * |
aoqi@0 | 184 | * @param subcode a QName containing the Value of the Subcode. |
aoqi@0 | 185 | * |
aoqi@0 | 186 | * @exception SOAPException if there was an error in setting the Subcode |
aoqi@0 | 187 | * @exception UnsupportedOperationException if this message does not |
aoqi@0 | 188 | * support the SOAP 1.2 concept of Subcode. |
aoqi@0 | 189 | * |
aoqi@0 | 190 | * @since SAAJ 1.3 |
aoqi@0 | 191 | */ |
aoqi@0 | 192 | public void appendFaultSubcode(QName subcode) throws SOAPException; |
aoqi@0 | 193 | |
aoqi@0 | 194 | /** |
aoqi@0 | 195 | * Gets the fault code for this <code>SOAPFault</code> object. |
aoqi@0 | 196 | * |
aoqi@0 | 197 | * @return a <code>String</code> with the fault code |
aoqi@0 | 198 | * @see #getFaultCodeAsName |
aoqi@0 | 199 | * @see #setFaultCode |
aoqi@0 | 200 | */ |
aoqi@0 | 201 | public String getFaultCode(); |
aoqi@0 | 202 | |
aoqi@0 | 203 | /** |
aoqi@0 | 204 | * Sets this <code>SOAPFault</code> object with the given fault actor. |
aoqi@0 | 205 | * <P> |
aoqi@0 | 206 | * The fault actor is the recipient in the message path who caused the |
aoqi@0 | 207 | * fault to happen. |
aoqi@0 | 208 | * <P> |
aoqi@0 | 209 | * If this <code>SOAPFault</code> supports SOAP 1.2 then this call is |
aoqi@0 | 210 | * equivalent to {@link #setFaultRole(String)} |
aoqi@0 | 211 | * |
aoqi@0 | 212 | * @param faultActor a <code>String</code> identifying the actor that |
aoqi@0 | 213 | * caused this <code>SOAPFault</code> object |
aoqi@0 | 214 | * @see #getFaultActor |
aoqi@0 | 215 | * |
aoqi@0 | 216 | * @exception SOAPException if there was an error in adding the |
aoqi@0 | 217 | * <code>faultActor</code> to the underlying XML tree. |
aoqi@0 | 218 | */ |
aoqi@0 | 219 | public void setFaultActor(String faultActor) throws SOAPException; |
aoqi@0 | 220 | |
aoqi@0 | 221 | /** |
aoqi@0 | 222 | * Gets the fault actor for this <code>SOAPFault</code> object. |
aoqi@0 | 223 | * <P> |
aoqi@0 | 224 | * If this <code>SOAPFault</code> supports SOAP 1.2 then this call is |
aoqi@0 | 225 | * equivalent to {@link #getFaultRole()} |
aoqi@0 | 226 | * |
aoqi@0 | 227 | * @return a <code>String</code> giving the actor in the message path |
aoqi@0 | 228 | * that caused this <code>SOAPFault</code> object |
aoqi@0 | 229 | * @see #setFaultActor |
aoqi@0 | 230 | */ |
aoqi@0 | 231 | public String getFaultActor(); |
aoqi@0 | 232 | |
aoqi@0 | 233 | /** |
aoqi@0 | 234 | * Sets the fault string for this <code>SOAPFault</code> object |
aoqi@0 | 235 | * to the given string. |
aoqi@0 | 236 | * <P> |
aoqi@0 | 237 | * If this |
aoqi@0 | 238 | * <code>SOAPFault</code> is part of a message that supports SOAP 1.2 then |
aoqi@0 | 239 | * this call is equivalent to: |
aoqi@0 | 240 | * <pre> |
aoqi@0 | 241 | * addFaultReasonText(faultString, Locale.getDefault()); |
aoqi@0 | 242 | * </pre> |
aoqi@0 | 243 | * |
aoqi@0 | 244 | * @param faultString a <code>String</code> giving an explanation of |
aoqi@0 | 245 | * the fault |
aoqi@0 | 246 | * @see #getFaultString |
aoqi@0 | 247 | * |
aoqi@0 | 248 | * @exception SOAPException if there was an error in adding the |
aoqi@0 | 249 | * <code>faultString</code> to the underlying XML tree. |
aoqi@0 | 250 | */ |
aoqi@0 | 251 | public void setFaultString(String faultString) throws SOAPException; |
aoqi@0 | 252 | |
aoqi@0 | 253 | /** |
aoqi@0 | 254 | * Sets the fault string for this <code>SOAPFault</code> object |
aoqi@0 | 255 | * to the given string and localized to the given locale. |
aoqi@0 | 256 | * <P> |
aoqi@0 | 257 | * If this |
aoqi@0 | 258 | * <code>SOAPFault</code> is part of a message that supports SOAP 1.2 then |
aoqi@0 | 259 | * this call is equivalent to: |
aoqi@0 | 260 | * <pre> |
aoqi@0 | 261 | * addFaultReasonText(faultString, locale); |
aoqi@0 | 262 | * </pre> |
aoqi@0 | 263 | * |
aoqi@0 | 264 | * @param faultString a <code>String</code> giving an explanation of |
aoqi@0 | 265 | * the fault |
aoqi@0 | 266 | * @param locale a {@link java.util.Locale Locale} object indicating |
aoqi@0 | 267 | * the native language of the <code>faultString</code> |
aoqi@0 | 268 | * @see #getFaultString |
aoqi@0 | 269 | * |
aoqi@0 | 270 | * @exception SOAPException if there was an error in adding the |
aoqi@0 | 271 | * <code>faultString</code> to the underlying XML tree. |
aoqi@0 | 272 | * |
aoqi@0 | 273 | * @since SAAJ 1.2 |
aoqi@0 | 274 | */ |
aoqi@0 | 275 | public void setFaultString(String faultString, Locale locale) |
aoqi@0 | 276 | throws SOAPException; |
aoqi@0 | 277 | |
aoqi@0 | 278 | /** |
aoqi@0 | 279 | * Gets the fault string for this <code>SOAPFault</code> object. |
aoqi@0 | 280 | * <P> |
aoqi@0 | 281 | * If this |
aoqi@0 | 282 | * <code>SOAPFault</code> is part of a message that supports SOAP 1.2 then |
aoqi@0 | 283 | * this call is equivalent to: |
aoqi@0 | 284 | * <pre> |
aoqi@0 | 285 | * String reason = null; |
aoqi@0 | 286 | * try { |
aoqi@0 | 287 | * reason = (String) getFaultReasonTexts().next(); |
aoqi@0 | 288 | * } catch (SOAPException e) {} |
aoqi@0 | 289 | * return reason; |
aoqi@0 | 290 | * </pre> |
aoqi@0 | 291 | * |
aoqi@0 | 292 | * @return a <code>String</code> giving an explanation of |
aoqi@0 | 293 | * the fault |
aoqi@0 | 294 | * @see #setFaultString(String) |
aoqi@0 | 295 | * @see #setFaultString(String, Locale) |
aoqi@0 | 296 | */ |
aoqi@0 | 297 | public String getFaultString(); |
aoqi@0 | 298 | |
aoqi@0 | 299 | /** |
aoqi@0 | 300 | * Gets the locale of the fault string for this <code>SOAPFault</code> |
aoqi@0 | 301 | * object. |
aoqi@0 | 302 | * <P> |
aoqi@0 | 303 | * If this |
aoqi@0 | 304 | * <code>SOAPFault</code> is part of a message that supports SOAP 1.2 then |
aoqi@0 | 305 | * this call is equivalent to: |
aoqi@0 | 306 | * <pre> |
aoqi@0 | 307 | * Locale locale = null; |
aoqi@0 | 308 | * try { |
aoqi@0 | 309 | * locale = (Locale) getFaultReasonLocales().next(); |
aoqi@0 | 310 | * } catch (SOAPException e) {} |
aoqi@0 | 311 | * return locale; |
aoqi@0 | 312 | * </pre> |
aoqi@0 | 313 | * |
aoqi@0 | 314 | * @return a <code>Locale</code> object indicating the native language of |
aoqi@0 | 315 | * the fault string or <code>null</code> if no locale was specified |
aoqi@0 | 316 | * @see #setFaultString(String, Locale) |
aoqi@0 | 317 | * |
aoqi@0 | 318 | * @since SAAJ 1.2 |
aoqi@0 | 319 | */ |
aoqi@0 | 320 | public Locale getFaultStringLocale(); |
aoqi@0 | 321 | |
aoqi@0 | 322 | /** |
aoqi@0 | 323 | * Returns true if this <code>SOAPFault</code> has a <code>Detail</code> |
aoqi@0 | 324 | * subelement and false otherwise. Equivalent to |
aoqi@0 | 325 | * <code>(getDetail()!=null)</code>. |
aoqi@0 | 326 | * |
aoqi@0 | 327 | * @return true if this <code>SOAPFault</code> has a <code>Detail</code> |
aoqi@0 | 328 | * subelement and false otherwise. |
aoqi@0 | 329 | * |
aoqi@0 | 330 | * @since SAAJ 1.3 |
aoqi@0 | 331 | */ |
aoqi@0 | 332 | public boolean hasDetail(); |
aoqi@0 | 333 | |
aoqi@0 | 334 | /** |
aoqi@0 | 335 | * Returns the optional detail element for this <code>SOAPFault</code> |
aoqi@0 | 336 | * object. |
aoqi@0 | 337 | * <P> |
aoqi@0 | 338 | * A <code>Detail</code> object carries application-specific error |
aoqi@0 | 339 | * information, the scope of the error information is restricted to |
aoqi@0 | 340 | * faults in the <code>SOAPBodyElement</code> objects if this is a |
aoqi@0 | 341 | * SOAP 1.1 Fault. |
aoqi@0 | 342 | * |
aoqi@0 | 343 | * @return a <code>Detail</code> object with application-specific |
aoqi@0 | 344 | * error information if present, null otherwise |
aoqi@0 | 345 | */ |
aoqi@0 | 346 | public Detail getDetail(); |
aoqi@0 | 347 | |
aoqi@0 | 348 | /** |
aoqi@0 | 349 | * Creates an optional <code>Detail</code> object and sets it as the |
aoqi@0 | 350 | * <code>Detail</code> object for this <code>SOAPFault</code> |
aoqi@0 | 351 | * object. |
aoqi@0 | 352 | * <P> |
aoqi@0 | 353 | * It is illegal to add a detail when the fault already |
aoqi@0 | 354 | * contains a detail. Therefore, this method should be called |
aoqi@0 | 355 | * only after the existing detail has been removed. |
aoqi@0 | 356 | * |
aoqi@0 | 357 | * @return the new <code>Detail</code> object |
aoqi@0 | 358 | * |
aoqi@0 | 359 | * @exception SOAPException if this |
aoqi@0 | 360 | * <code>SOAPFault</code> object already contains a |
aoqi@0 | 361 | * valid <code>Detail</code> object |
aoqi@0 | 362 | */ |
aoqi@0 | 363 | public Detail addDetail() throws SOAPException; |
aoqi@0 | 364 | |
aoqi@0 | 365 | /** |
aoqi@0 | 366 | * Returns an <code>Iterator</code> over a distinct sequence of |
aoqi@0 | 367 | * <code>Locale</code>s for which there are associated Reason Text items. |
aoqi@0 | 368 | * Any of these <code>Locale</code>s can be used in a call to |
aoqi@0 | 369 | * <code>getFaultReasonText</code> in order to obtain a localized version |
aoqi@0 | 370 | * of the Reason Text string. |
aoqi@0 | 371 | * |
aoqi@0 | 372 | * @return an <code>Iterator</code> over a sequence of <code>Locale</code> |
aoqi@0 | 373 | * objects for which there are associated Reason Text items. |
aoqi@0 | 374 | * |
aoqi@0 | 375 | * @exception SOAPException if there was an error in retrieving |
aoqi@0 | 376 | * the fault Reason locales. |
aoqi@0 | 377 | * @exception UnsupportedOperationException if this message does not |
aoqi@0 | 378 | * support the SOAP 1.2 concept of Fault Reason. |
aoqi@0 | 379 | * |
aoqi@0 | 380 | * @since SAAJ 1.3 |
aoqi@0 | 381 | */ |
aoqi@0 | 382 | public Iterator getFaultReasonLocales() throws SOAPException; |
aoqi@0 | 383 | |
aoqi@0 | 384 | /** |
aoqi@0 | 385 | * Returns an <code>Iterator</code> over a sequence of |
aoqi@0 | 386 | * <code>String</code> objects containing all of the Reason Text items for |
aoqi@0 | 387 | * this <code>SOAPFault</code>. |
aoqi@0 | 388 | * |
aoqi@0 | 389 | * @return an <code>Iterator</code> over env:Fault/env:Reason/env:Text items. |
aoqi@0 | 390 | * |
aoqi@0 | 391 | * @exception SOAPException if there was an error in retrieving |
aoqi@0 | 392 | * the fault Reason texts. |
aoqi@0 | 393 | * @exception UnsupportedOperationException if this message does not |
aoqi@0 | 394 | * support the SOAP 1.2 concept of Fault Reason. |
aoqi@0 | 395 | * |
aoqi@0 | 396 | * @since SAAJ 1.3 |
aoqi@0 | 397 | */ |
aoqi@0 | 398 | public Iterator getFaultReasonTexts() throws SOAPException; |
aoqi@0 | 399 | |
aoqi@0 | 400 | /** |
aoqi@0 | 401 | * Returns the Reason Text associated with the given <code>Locale</code>. |
aoqi@0 | 402 | * If more than one such Reason Text exists the first matching Text is |
aoqi@0 | 403 | * returned |
aoqi@0 | 404 | * |
aoqi@0 | 405 | * @param locale -- the <code>Locale</code> for which a localized |
aoqi@0 | 406 | * Reason Text is desired |
aoqi@0 | 407 | * |
aoqi@0 | 408 | * @return the Reason Text associated with <code>locale</code> |
aoqi@0 | 409 | * |
aoqi@0 | 410 | * @see #getFaultString |
aoqi@0 | 411 | * |
aoqi@0 | 412 | * @exception SOAPException if there was an error in retrieving |
aoqi@0 | 413 | * the fault Reason text for the specified locale . |
aoqi@0 | 414 | * @exception UnsupportedOperationException if this message does not |
aoqi@0 | 415 | * support the SOAP 1.2 concept of Fault Reason. |
aoqi@0 | 416 | * |
aoqi@0 | 417 | * @since SAAJ 1.3 |
aoqi@0 | 418 | */ |
aoqi@0 | 419 | public String getFaultReasonText(Locale locale) throws SOAPException; |
aoqi@0 | 420 | |
aoqi@0 | 421 | /** |
aoqi@0 | 422 | * Appends or replaces a Reason Text item containing the specified |
aoqi@0 | 423 | * text message and an <i>xml:lang</i> derived from |
aoqi@0 | 424 | * <code>locale</code>. If a Reason Text item with this |
aoqi@0 | 425 | * <i>xml:lang</i> already exists its text value will be replaced |
aoqi@0 | 426 | * with <code>text</code>. |
aoqi@0 | 427 | * The <code>locale</code> parameter should not be <code>null</code> |
aoqi@0 | 428 | * <P> |
aoqi@0 | 429 | * Code sample: |
aoqi@0 | 430 | * |
aoqi@0 | 431 | * <PRE> |
aoqi@0 | 432 | * SOAPFault fault = ...; |
aoqi@0 | 433 | * fault.addFaultReasonText("Version Mismatch", Locale.ENGLISH); |
aoqi@0 | 434 | * </PRE> |
aoqi@0 | 435 | * |
aoqi@0 | 436 | * @param text -- reason message string |
aoqi@0 | 437 | * @param locale -- Locale object representing the locale of the message |
aoqi@0 | 438 | * |
aoqi@0 | 439 | * @exception SOAPException if there was an error in adding the Reason text |
aoqi@0 | 440 | * or the <code>locale</code> passed was <code>null</code>. |
aoqi@0 | 441 | * @exception UnsupportedOperationException if this message does not |
aoqi@0 | 442 | * support the SOAP 1.2 concept of Fault Reason. |
aoqi@0 | 443 | * |
aoqi@0 | 444 | * @since SAAJ 1.3 |
aoqi@0 | 445 | */ |
aoqi@0 | 446 | public void addFaultReasonText(String text, java.util.Locale locale) |
aoqi@0 | 447 | throws SOAPException; |
aoqi@0 | 448 | |
aoqi@0 | 449 | /** |
aoqi@0 | 450 | * Returns the optional Node element value for this |
aoqi@0 | 451 | * <code>SOAPFault</code> object. The Node element is |
aoqi@0 | 452 | * optional in SOAP 1.2. |
aoqi@0 | 453 | * |
aoqi@0 | 454 | * @return Content of the env:Fault/env:Node element as a String |
aoqi@0 | 455 | * or <code>null</code> if none |
aoqi@0 | 456 | * |
aoqi@0 | 457 | * @exception UnsupportedOperationException if this message does not |
aoqi@0 | 458 | * support the SOAP 1.2 concept of Fault Node. |
aoqi@0 | 459 | * |
aoqi@0 | 460 | * @since SAAJ 1.3 |
aoqi@0 | 461 | */ |
aoqi@0 | 462 | public String getFaultNode(); |
aoqi@0 | 463 | |
aoqi@0 | 464 | /** |
aoqi@0 | 465 | * Creates or replaces any existing Node element value for |
aoqi@0 | 466 | * this <code>SOAPFault</code> object. The Node element |
aoqi@0 | 467 | * is optional in SOAP 1.2. |
aoqi@0 | 468 | * |
aoqi@0 | 469 | * @exception SOAPException if there was an error in setting the |
aoqi@0 | 470 | * Node for this <code>SOAPFault</code> object. |
aoqi@0 | 471 | * @exception UnsupportedOperationException if this message does not |
aoqi@0 | 472 | * support the SOAP 1.2 concept of Fault Node. |
aoqi@0 | 473 | * |
aoqi@0 | 474 | * |
aoqi@0 | 475 | * @since SAAJ 1.3 |
aoqi@0 | 476 | */ |
aoqi@0 | 477 | public void setFaultNode(String uri) throws SOAPException; |
aoqi@0 | 478 | |
aoqi@0 | 479 | /** |
aoqi@0 | 480 | * Returns the optional Role element value for this |
aoqi@0 | 481 | * <code>SOAPFault</code> object. The Role element is |
aoqi@0 | 482 | * optional in SOAP 1.2. |
aoqi@0 | 483 | * |
aoqi@0 | 484 | * @return Content of the env:Fault/env:Role element as a String |
aoqi@0 | 485 | * or <code>null</code> if none |
aoqi@0 | 486 | * |
aoqi@0 | 487 | * @exception UnsupportedOperationException if this message does not |
aoqi@0 | 488 | * support the SOAP 1.2 concept of Fault Role. |
aoqi@0 | 489 | * |
aoqi@0 | 490 | * @since SAAJ 1.3 |
aoqi@0 | 491 | */ |
aoqi@0 | 492 | public String getFaultRole(); |
aoqi@0 | 493 | |
aoqi@0 | 494 | /** |
aoqi@0 | 495 | * Creates or replaces any existing Role element value for |
aoqi@0 | 496 | * this <code>SOAPFault</code> object. The Role element |
aoqi@0 | 497 | * is optional in SOAP 1.2. |
aoqi@0 | 498 | * |
aoqi@0 | 499 | * @param uri - the URI of the Role |
aoqi@0 | 500 | * |
aoqi@0 | 501 | * @exception SOAPException if there was an error in setting the |
aoqi@0 | 502 | * Role for this <code>SOAPFault</code> object. |
aoqi@0 | 503 | * |
aoqi@0 | 504 | * @exception UnsupportedOperationException if this message does not |
aoqi@0 | 505 | * support the SOAP 1.2 concept of Fault Role. |
aoqi@0 | 506 | * |
aoqi@0 | 507 | * @since SAAJ 1.3 |
aoqi@0 | 508 | */ |
aoqi@0 | 509 | public void setFaultRole(String uri) throws SOAPException; |
aoqi@0 | 510 | |
aoqi@0 | 511 | } |