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 }
--- EOF ---