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 26package 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 */ 45public 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} 172