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