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 <tt>null</tt> 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 }