KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > xml > soap > SOAPException


1 /*
2  * $Id: SOAPException.java,v 1.6 2005/04/05 21:03:23 mk125090 Exp $
3  * $Revision: 1.6 $
4  * $Date: 2005/04/05 21:03:23 $
5  */
6
7 /*
8  * The contents of this file are subject to the terms
9  * of the Common Development and Distribution License
10  * (the License). You may not use this file except in
11  * compliance with the License.
12  *
13  * You can obtain a copy of the license at
14  * https://glassfish.dev.java.net/public/CDDLv1.0.html.
15  * See the License for the specific language governing
16  * permissions and limitations under the License.
17  *
18  * When distributing Covered Code, include this CDDL
19  * Header Notice in each file and include the License file
20  * at https://glassfish.dev.java.net/public/CDDLv1.0.html.
21  * If applicable, add the following below the CDDL Header,
22  * with the fields enclosed by brackets [] replaced by
23  * you own identifying information:
24  * "Portions Copyrighted [year] [name of copyright owner]"
25  *
26  * Copyright 2006 Sun Microsystems Inc. All Rights Reserved
27  */
28 package javax.xml.soap;
29
30 /**
31  * An exception that signals that a SOAP exception has occurred. A
32  * <code>SOAPException</code> object may contain a <code>String</code>
33  * that gives the reason for the exception, an embedded
34  * <code>Throwable</code> object, or both. This class provides methods
35  * for retrieving reason messages and for retrieving the embedded
36  * <code>Throwable</code> object.
37  *
38  * <P> Typical reasons for throwing a <code>SOAPException</code>
39  * object are problems such as difficulty setting a header, not being
40  * able to send a message, and not being able to get a connection with
41  * the provider. Reasons for embedding a <code>Throwable</code>
42  * object include problems such as input/output errors or a parsing
43  * problem, such as an error in parsing a header.
44  */
45 public class SOAPException extends Exception JavaDoc {
46     private Throwable JavaDoc cause;
47
48     /**
49      * Constructs a <code>SOAPException</code> object with no
50      * reason or embedded <code>Throwable</code> object.
51      */
52     public SOAPException() {
53         super();
54         this.cause = null;
55     }
56
57     /**
58      * Constructs a <code>SOAPException</code> object with the given
59      * <code>String</code> as the reason for the exception being thrown.
60      *
61      * @param reason a description of what caused the exception
62      */
63     public SOAPException(String JavaDoc reason) {
64         super(reason);
65         this.cause = null;
66     }
67
68     /**
69      * Constructs a <code>SOAPException</code> object with the given
70      * <code>String</code> as the reason for the exception being thrown
71      * and the given <code>Throwable</code> object as an embedded
72      * exception.
73      *
74      * @param reason a description of what caused the exception
75      * @param cause a <code>Throwable</code> object that is to
76      * be embedded in this <code>SOAPException</code> object
77      */
78     public SOAPException(String JavaDoc reason, Throwable JavaDoc cause) {
79         super(reason);
80         initCause(cause);
81     }
82
83     /**
84      * Constructs a <code>SOAPException</code> object initialized
85      * with the given <code>Throwable</code> object.
86      */
87     public SOAPException(Throwable JavaDoc cause) {
88         super(cause.toString());
89         initCause(cause);
90     }
91
92     /**
93      * Returns the detail message for this <code>SOAPException</code>
94      * object.
95      * <P>
96      * If there is an embedded <code>Throwable</code> object, and if the
97      * <code>SOAPException</code> object has no detail message of its
98      * own, this method will return the detail message from the embedded
99      * <code>Throwable</code> object.
100      *
101      * @return the error or warning message for this
102      * <code>SOAPException</code> or, if it has none, the
103      * message of the embedded <code>Throwable</code> object,
104      * if there is one
105      */
106     public String JavaDoc getMessage() {
107         String JavaDoc 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</code> object embedded in this
117      * <code>SOAPException</code> if there is one. Otherwise, this method
118      * returns <code>null</code>.
119      *
120      * @return the embedded <code>Throwable</code> object or <code>null</code>
121      * if there is none
122      */
123
124     public Throwable JavaDoc getCause() {
125         return cause;
126     }
127
128     /**
129      * Initializes the <code>cause</code> field of this <code>SOAPException</code>
130      * object with the given <code>Throwable</code> 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</code> object.
135      * If this <code>SOAPException</code> object was created with the
136      * constructor {@link #SOAPException(Throwable)} or
137      * {@link #SOAPException(String,Throwable)}, meaning that its
138      * <code>cause</code> field already has a value, this method cannot be
139      * called even once.
140      *
141      * @param cause the <code>Throwable</code> object that caused this
142      * <code>SOAPException</code> 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</code> instance
148      * @throws IllegalArgumentException if <code>cause</code> is this
149      * <code>Throwable</code> object. (A <code>Throwable</code> object
150      * cannot be its own cause.)
151      * @throws IllegalStateException if the cause for this <code>SOAPException</code> object
152      * has already been initialized
153      */
154     public synchronized Throwable JavaDoc initCause(Throwable JavaDoc cause) {
155         if (this.cause != null) {
156             throw new IllegalStateException JavaDoc("Can't override cause");
157         }
158         if (cause == this) {
159             throw new IllegalArgumentException JavaDoc("Self-causation not permitted");
160         }
161         this.cause = cause;
162
163         return this;
164     }
165 }
166
Popular Tags