001: /*
002: * $Id: SOAPException.java,v 1.7 2006/03/30 00:59:41 ofung Exp $
003: * $Revision: 1.7 $
004: * $Date: 2006/03/30 00:59:41 $
005: */
006:
007: /*
008: * The contents of this file are subject to the terms
009: * of the Common Development and Distribution License
010: * (the License). You may not use this file except in
011: * compliance with the License.
012: *
013: * You can obtain a copy of the license at
014: * https://glassfish.dev.java.net/public/CDDLv1.0.html.
015: * See the License for the specific language governing
016: * permissions and limitations under the License.
017: *
018: * When distributing Covered Code, include this CDDL
019: * Header Notice in each file and include the License file
020: * at https://glassfish.dev.java.net/public/CDDLv1.0.html.
021: * If applicable, add the following below the CDDL Header,
022: * with the fields enclosed by brackets [] replaced by
023: * you own identifying information:
024: * "Portions Copyrighted [year] [name of copyright owner]"
025: *
026: * Copyright 2006 Sun Microsystems Inc. All Rights Reserved
027: */
028: package javax.xml.soap;
029:
030: /**
031: * An exception that signals that a SOAP exception has occurred. A
032: * <code>SOAPException</code> object may contain a <code>String</code>
033: * that gives the reason for the exception, an embedded
034: * <code>Throwable</code> object, or both. This class provides methods
035: * for retrieving reason messages and for retrieving the embedded
036: * <code>Throwable</code> object.
037: *
038: * <P> Typical reasons for throwing a <code>SOAPException</code>
039: * object are problems such as difficulty setting a header, not being
040: * able to send a message, and not being able to get a connection with
041: * the provider. Reasons for embedding a <code>Throwable</code>
042: * object include problems such as input/output errors or a parsing
043: * problem, such as an error in parsing a header.
044: */
045: public class SOAPException extends Exception {
046: private Throwable cause;
047:
048: /**
049: * Constructs a <code>SOAPException</code> object with no
050: * reason or embedded <code>Throwable</code> object.
051: */
052: public SOAPException() {
053: super ();
054: this .cause = null;
055: }
056:
057: /**
058: * Constructs a <code>SOAPException</code> object with the given
059: * <code>String</code> as the reason for the exception being thrown.
060: *
061: * @param reason a description of what caused the exception
062: */
063: public SOAPException(String reason) {
064: super (reason);
065: this .cause = null;
066: }
067:
068: /**
069: * Constructs a <code>SOAPException</code> object with the given
070: * <code>String</code> as the reason for the exception being thrown
071: * and the given <code>Throwable</code> object as an embedded
072: * exception.
073: *
074: * @param reason a description of what caused the exception
075: * @param cause a <code>Throwable</code> object that is to
076: * be embedded in this <code>SOAPException</code> object
077: */
078: public SOAPException(String reason, Throwable cause) {
079: super (reason);
080: initCause(cause);
081: }
082:
083: /**
084: * Constructs a <code>SOAPException</code> object initialized
085: * with the given <code>Throwable</code> object.
086: */
087: public SOAPException(Throwable cause) {
088: super (cause.toString());
089: initCause(cause);
090: }
091:
092: /**
093: * Returns the detail message for this <code>SOAPException</code>
094: * object.
095: * <P>
096: * If there is an embedded <code>Throwable</code> object, and if the
097: * <code>SOAPException</code> object has no detail message of its
098: * own, this method will return the detail message from the embedded
099: * <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 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</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 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 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(
160: "Self-causation not permitted");
161: }
162: this.cause = cause;
163:
164: return this;
165: }
166: }
|