View Javadoc
1   /*
2    * Copyright (c) 2004, 2012, 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</code> object may contain a <code>String</code>
31   * that gives the reason for the exception, an embedded
32   * <code>Throwable</code> object, or both. This class provides methods
33   * for retrieving reason messages and for retrieving the embedded
34   * <code>Throwable</code> object.
35   *
36   * <P> Typical reasons for throwing a <code>SOAPException</code>
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</code>
40   * object include problems such as input/output errors or a parsing
41   * problem, such as an error in parsing a header.
42   */
43  public class SOAPException extends Exception {
44      private Throwable cause;
45  
46      /**
47       * Constructs a <code>SOAPException</code> object with no
48       * reason or embedded <code>Throwable</code> object.
49       */
50      public SOAPException() {
51          super();
52          this.cause = null;
53      }
54  
55      /**
56       * Constructs a <code>SOAPException</code> object with the given
57       * <code>String</code> as the reason for the exception being thrown.
58       *
59       * @param reason a description of what caused the exception
60       */
61      public SOAPException(String reason) {
62          super(reason);
63          this.cause = null;
64      }
65  
66      /**
67       * Constructs a <code>SOAPException</code> object with the given
68       * <code>String</code> as the reason for the exception being thrown
69       * and the given <code>Throwable</code> object as an embedded
70       * exception.
71       *
72       * @param reason a description of what caused the exception
73       * @param cause a <code>Throwable</code> object that is to
74       *        be embedded in this <code>SOAPException</code> object
75       */
76      public SOAPException(String reason, Throwable cause) {
77          super(reason);
78          initCause(cause);
79      }
80  
81      /**
82       * Constructs a <code>SOAPException</code> object initialized
83       * with the given <code>Throwable</code> object.
84       */
85      public SOAPException(Throwable cause) {
86          super(cause.toString());
87          initCause(cause);
88      }
89  
90      /**
91       * Returns the detail message for this <code>SOAPException</code>
92       * object.
93       * <P>
94       * If there is an embedded <code>Throwable</code> object, and if the
95       * <code>SOAPException</code> object has no detail message of its
96       * own, this method will return the detail message from the embedded
97       * <code>Throwable</code> object.
98       *
99       * @return the error or warning message for this
100      *         <code>SOAPException</code> or, if it has none, the
101      *         message of the embedded <code>Throwable</code> object,
102      *         if there is one
103      */
104     public String getMessage() {
105         String message = super.getMessage();
106         if (message == null && cause != null) {
107             return cause.getMessage();
108         } else {
109             return message;
110         }
111     }
112 
113     /**
114      * Returns the <code>Throwable</code> object embedded in this
115      * <code>SOAPException</code> if there is one. Otherwise, this method
116      * returns <code>null</code>.
117      *
118      * @return the embedded <code>Throwable</code> object or <code>null</code>
119      *         if there is none
120      */
121 
122     public Throwable getCause() {
123         return cause;
124     }
125 
126     /**
127      * Initializes the <code>cause</code> field of this <code>SOAPException</code>
128      * object with the given <code>Throwable</code> object.
129      * <P>
130      * This method can be called at most once.  It is generally called from
131      * within the constructor or immediately after the constructor has
132      * returned a new <code>SOAPException</code> object.
133      * If this <code>SOAPException</code> object was created with the
134      * constructor {@link #SOAPException(Throwable)} or
135      * {@link #SOAPException(String,Throwable)}, meaning that its
136      * <code>cause</code> field already has a value, this method cannot be
137      * called even once.
138      *
139      * @param  cause the <code>Throwable</code> object that caused this
140      *         <code>SOAPException</code> object to be thrown.  The value of this
141      *         parameter is saved for later retrieval by the
142      *         {@link #getCause()} method.  A <tt>null</tt> value is
143      *         permitted and indicates that the cause is nonexistent or
144      *         unknown.
145      * @return  a reference to this <code>SOAPException</code> instance
146      * @throws IllegalArgumentException if <code>cause</code> is this
147      *         <code>Throwable</code> object.  (A <code>Throwable</code> object
148      *         cannot be its own cause.)
149      * @throws IllegalStateException if the cause for this <code>SOAPException</code> object
150      *         has already been initialized
151      */
152     public synchronized Throwable initCause(Throwable cause) {
153         if (this.cause != null) {
154             throw new IllegalStateException("Can't override cause");
155         }
156         if (cause == this) {
157             throw new IllegalArgumentException("Self-causation not permitted");
158         }
159         this.cause = cause;
160 
161         return this;
162     }
163 }