Save This Page
1 /* Copyright 2004 The Apache Software Foundation
2 *
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16 package org.apache.xmlbeans.impl.soap;
17
18 /**
19 * An exception that signals that a SOAP exception has
20 * occurred. A <CODE>SOAPException</CODE> object may contain a
21 * <CODE>String</CODE> that gives the reason for the exception, an
22 * embedded <CODE>Throwable</CODE> object, or both. This class
23 * provides methods for retrieving reason messages and for
24 * retrieving the embedded <CODE>Throwable</CODE> object.</P>
25 *
26 * <P>Typical reasons for throwing a <CODE>SOAPException</CODE>
27 * object are problems such as difficulty setting a header, not
28 * being able to send a message, and not being able to get a
29 * connection with the provider. Reasons for embedding a <CODE>
30 * Throwable</CODE> object include problems such as input/output
31 * errors or a parsing problem, such as an error in parsing a
32 * header.
33 */
34 public class SOAPException extends Exception {
35
36 /**
37 * Constructs a <CODE>SOAPException</CODE> object with no
38 * reason or embedded <CODE>Throwable</CODE> object.
39 */
40 public SOAPException() {
41 cause = null;
42 }
43
44 /**
45 * Constructs a <CODE>SOAPException</CODE> object with the
46 * given <CODE>String</CODE> as the reason for the exception
47 * being thrown.
48 * @param reason a description of what caused
49 * the exception
50 */
51 public SOAPException(String reason) {
52
53 super(reason);
54
55 cause = null;
56 }
57
58 /**
59 * Constructs a <CODE>SOAPException</CODE> object with the
60 * given <CODE>String</CODE> as the reason for the exception
61 * being thrown and the given <CODE>Throwable</CODE> object as
62 * an embedded exception.
63 * @param reason a description of what caused
64 * the exception
65 * @param cause a <CODE>Throwable</CODE> object
66 * that is to be embedded in this <CODE>SOAPException</CODE>
67 * object
68 */
69 public SOAPException(String reason, Throwable cause) {
70
71 super(reason);
72
73 initCause(cause);
74 }
75
76 /**
77 * Constructs a <CODE>SOAPException</CODE> object
78 * initialized with the given <CODE>Throwable</CODE>
79 * object.
80 * @param cause a <CODE>Throwable</CODE> object
81 * that is to be embedded in this <CODE>SOAPException</CODE>
82 * object
83 */
84 public SOAPException(Throwable cause) {
85
86 super(cause.toString());
87
88 initCause(cause);
89 }
90
91 /**
92 * Returns the detail message for this <CODE>
93 * SOAPException</CODE> object.
94 *
95 * <P>If there is an embedded <CODE>Throwable</CODE> object,
96 * and if the <CODE>SOAPException</CODE> object has no detail
97 * message of its own, this method will return the detail
98 * message from the embedded <CODE>Throwable</CODE>
99 * object.</P>
100 * @return the error or warning message for this <CODE>
101 * SOAPException</CODE> or, if it has none, the message of
102 * the embedded <CODE>Throwable</CODE> object, if there is
103 * one
104 */
105 public String getMessage() {
106
107 String s = super.getMessage();
108
109 if ((s == null) && (cause != null)) {
110 return cause.getMessage();
111 } else {
112 return s;
113 }
114 }
115
116 /**
117 * Returns the <CODE>Throwable</CODE> object embedded in
118 * this <CODE>SOAPException</CODE> if there is one. Otherwise,
119 * this method returns <CODE>null</CODE>.
120 * @return the embedded <CODE>Throwable</CODE> object or <CODE>
121 * null</CODE> if there is none
122 */
123 public Throwable getCause() {
124 return cause;
125 }
126
127 /**
128 * Initializes the <CODE>cause</CODE> field of this <CODE>
129 * SOAPException</CODE> object with the given <CODE>
130 * Throwable</CODE> object.
131 *
132 * <P>This method can be called at most once. It is generally
133 * called from within the constructor or immediately after the
134 * constructor has returned a new <CODE>SOAPException</CODE>
135 * object. If this <CODE>SOAPException</CODE> object was
136 * created with the constructor {@link #SOAPException(java.lang.Throwable) SOAPException(java.lang.Throwable)}
137 * or {@link #SOAPException(java.lang.String, java.lang.Throwable) SOAPException(java.lang.String, java.lang.Throwable)}, meaning
138 * that its <CODE>cause</CODE> field already has a value, this
139 * method cannot be called even once.
140 *
141 * @param cause the <CODE>Throwable</CODE>
142 * object that caused this <CODE>SOAPException</CODE> object
143 * to be thrown. The value of this parameter is saved for
144 * later retrieval by the <A href=
145 * "../../../javax/xml/soap/SOAPException.html#getCause()">
146 * <CODE>getCause()</CODE></A> method. A <TT>null</TT> value
147 * is permitted and indicates that the cause is nonexistent
148 * or unknown.
149 * @return a reference to this <CODE>SOAPException</CODE>
150 * instance
151 * @throws java.lang.IllegalArgumentException if
152 * <CODE>cause</CODE> is this <CODE>Throwable</CODE> object.
153 * (A <CODE>Throwable</CODE> object cannot be its own
154 * cause.)
155 * @throws java.lang.IllegalStateException if this <CODE>
156 * SOAPException</CODE> object was created with {@link #SOAPException(java.lang.Throwable) SOAPException(java.lang.Throwable)}
157 * or {@link #SOAPException(java.lang.String, java.lang.Throwable) SOAPException(java.lang.String, java.lang.Throwable)}, or this
158 * method has already been called on this <CODE>
159 * SOAPException</CODE> object
160 */
161 public synchronized Throwable initCause(Throwable cause) {
162
163 if (this.cause != null) {
164 throw new IllegalStateException("Can't override cause");
165 }
166
167 if (cause == this) {
168 throw new IllegalArgumentException("Self-causation not permitted");
169 } else {
170 this.cause = cause;
171
172 return this;
173 }
174 }
175
176 private Throwable cause;
177 }