1 /* 2 * Copyright (c) 2004, 2015, 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 public SOAPException(Throwable cause) { 88 super(cause.toString()); 89 initCause(cause); 90 } 91 92 /** 93 * Returns the detail message for this {@code SOAPException} 94 * object. 95 * <P> 96 * If there is an embedded {@code Throwable} object, and if the 97 * {@code SOAPException} object has no detail message of its 98 * own, this method will return the detail message from the embedded 99 * {@code Throwable} object. 100 * 101 * @return the error or warning message for this 102 * {@code SOAPException} or, if it has none, the 103 * message of the embedded {@code Throwable} object, 104 * if there is one 105 */ 106 public String getMessage() { 107 String message = super.getMessage(); 108 if (message == null && cause != null) { 109 return cause.getMessage(); 110 } else { 111 return message; 112 } 113 } 114 115 /** 116 * Returns the {@code Throwable} object embedded in this 117 * {@code SOAPException} if there is one. Otherwise, this method 118 * returns {@code null}. 119 * 120 * @return the embedded {@code Throwable} object or {@code null} 121 * if there is none 122 */ 123 124 public Throwable getCause() { 125 return cause; 126 } 127 128 /** 129 * Initializes the {@code cause} field of this {@code SOAPException} 130 * object with the given {@code Throwable} object. 131 * <P> 132 * This method can be called at most once. It is generally called from 133 * within the constructor or immediately after the constructor has 134 * returned a new {@code SOAPException} object. 135 * If this {@code SOAPException} object was created with the 136 * constructor {@link #SOAPException(Throwable)} or 137 * {@link #SOAPException(String,Throwable)}, meaning that its 138 * {@code cause} field already has a value, this method cannot be 139 * called even once. 140 * 141 * @param cause the {@code Throwable} object that caused this 142 * {@code SOAPException} object to be thrown. The value of this 143 * parameter is saved for later retrieval by the 144 * {@link #getCause()} method. A {@code null} value is 145 * permitted and indicates that the cause is nonexistent or 146 * unknown. 147 * @return a reference to this {@code SOAPException} instance 148 * @throws IllegalArgumentException if {@code cause} is this 149 * {@code Throwable} object. (A {@code Throwable} object 150 * cannot be its own cause.) 151 * @throws IllegalStateException if the cause for this {@code SOAPException} object 152 * has already been initialized 153 */ 154 public synchronized Throwable initCause(Throwable cause) { 155 if (this.cause != null) { 156 throw new IllegalStateException("Can't override cause"); 157 } 158 if (cause == this) { 159 throw new IllegalArgumentException("Self-causation not permitted"); 160 } 161 this.cause = cause; 162 163 return this; 164 } 165 }