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 }