1 /*
2 * Copyright (c) 2004, 2017, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javax.xml.soap;
27
28 /**
29 * An exception that signals that a SOAP exception has occurred. A
30 * {@code SOAPException} object may contain a {@code String}
31 * that gives the reason for the exception, an embedded
32 * {@code Throwable} object, or both. This class provides methods
33 * for retrieving reason messages and for retrieving the embedded
34 * {@code Throwable} object.
35 *
36 * <P> Typical reasons for throwing a {@code SOAPException}
37 * object are problems such as difficulty setting a header, not being
38 * able to send a message, and not being able to get a connection with
39 * the provider. Reasons for embedding a {@code Throwable}
40 * object include problems such as input/output errors or a parsing
41 * problem, such as an error in parsing a header.
42 *
43 * @since 1.6
44 */
45 public class SOAPException extends Exception {
46 private Throwable cause;
47
48 /**
49 * Constructs a {@code SOAPException} object with no
50 * reason or embedded {@code Throwable} object.
51 */
52 public SOAPException() {
53 super();
54 this.cause = null;
55 }
56
57 /**
58 * Constructs a {@code SOAPException} object with the given
59 * {@code String} as the reason for the exception being thrown.
60 *
61 * @param reason a description of what caused the exception
62 */
63 public SOAPException(String reason) {
64 super(reason);
65 this.cause = null;
66 }
67
68 /**
69 * Constructs a {@code SOAPException} object with the given
70 * {@code String} as the reason for the exception being thrown
71 * and the given {@code Throwable} object as an embedded
72 * exception.
73 *
74 * @param reason a description of what caused the exception
75 * @param cause a {@code Throwable} object that is to
76 * be embedded in this {@code SOAPException} object
77 */
78 public SOAPException(String reason, Throwable cause) {
79 super(reason);
80 initCause(cause);
81 }
82
83 /**
84 * Constructs a {@code SOAPException} object initialized
85 * with the given {@code Throwable} object.
86 *
87 * @param cause a {@code Throwable} object that is to
88 * be embedded in this {@code SOAPException} object
89 */
90 public SOAPException(Throwable cause) {
91 super(cause.toString());
92 initCause(cause);
93 }
94
95 /**
96 * Returns the detail message for this {@code SOAPException}
97 * object.
98 * <P>
99 * If there is an embedded {@code Throwable} object, and if the
100 * {@code SOAPException} object has no detail message of its
101 * own, this method will return the detail message from the embedded
102 * {@code Throwable} object.
103 *
104 * @return the error or warning message for this
105 * {@code SOAPException} or, if it has none, the
106 * message of the embedded {@code Throwable} object,
107 * if there is one
108 */
109 @Override
110 public String getMessage() {
111 String message = super.getMessage();
112 if (message == null && cause != null) {
113 return cause.getMessage();
114 } else {
115 return message;
116 }
117 }
118
119 /**
120 * Returns the {@code Throwable} object embedded in this
121 * {@code SOAPException} if there is one. Otherwise, this method
122 * returns {@code null}.
123 *
124 * @return the embedded {@code Throwable} object or {@code null}
125 * if there is none
126 */
127
128 @Override
129 public Throwable getCause() {
130 return cause;
131 }
132
133 /**
134 * Initializes the {@code cause} field of this {@code SOAPException}
135 * object with the given {@code Throwable} object.
136 * <P>
137 * This method can be called at most once. It is generally called from
138 * within the constructor or immediately after the constructor has
139 * returned a new {@code SOAPException} object.
140 * If this {@code SOAPException} object was created with the
141 * constructor {@link #SOAPException(Throwable)} or
142 * {@link #SOAPException(String,Throwable)}, meaning that its
143 * {@code cause} field already has a value, this method cannot be
144 * called even once.
145 *
146 * @param cause the {@code Throwable} object that caused this
147 * {@code SOAPException} object to be thrown. The value of this
148 * parameter is saved for later retrieval by the
149 * {@link #getCause()} method. A {@code null} value is
150 * permitted and indicates that the cause is nonexistent or
151 * unknown.
152 * @return a reference to this {@code SOAPException} instance
153 * @throws IllegalArgumentException if {@code cause} is this
154 * {@code Throwable} object. (A {@code Throwable} object
155 * cannot be its own cause.)
156 * @throws IllegalStateException if the cause for this {@code SOAPException} object
157 * has already been initialized
158 */
159 @Override
160 public synchronized Throwable initCause(Throwable cause) {
161 if (this.cause != null) {
162 throw new IllegalStateException("Can't override cause");
163 }
164 if (cause == this) {
165 throw new IllegalArgumentException("Self-causation not permitted");
166 }
167 this.cause = cause;
168
169 return this;
170 }
171 }