SOAPException object may contain a String
aoqi@0: * that gives the reason for the exception, an embedded
aoqi@0: * Throwable object, or both. This class provides methods
aoqi@0: * for retrieving reason messages and for retrieving the embedded
aoqi@0: * Throwable object.
aoqi@0: *
aoqi@0: * Typical reasons for throwing a SOAPException
aoqi@0: * object are problems such as difficulty setting a header, not being
aoqi@0: * able to send a message, and not being able to get a connection with
aoqi@0: * the provider. Reasons for embedding a Throwable
aoqi@0: * object include problems such as input/output errors or a parsing
aoqi@0: * problem, such as an error in parsing a header.
aoqi@0: */
aoqi@0: public class SOAPException extends Exception {
aoqi@0: private Throwable cause;
aoqi@0:
aoqi@0: /**
aoqi@0: * Constructs a SOAPException object with no
aoqi@0: * reason or embedded Throwable object.
aoqi@0: */
aoqi@0: public SOAPException() {
aoqi@0: super();
aoqi@0: this.cause = null;
aoqi@0: }
aoqi@0:
aoqi@0: /**
aoqi@0: * Constructs a SOAPException object with the given
aoqi@0: * String as the reason for the exception being thrown.
aoqi@0: *
aoqi@0: * @param reason a description of what caused the exception
aoqi@0: */
aoqi@0: public SOAPException(String reason) {
aoqi@0: super(reason);
aoqi@0: this.cause = null;
aoqi@0: }
aoqi@0:
aoqi@0: /**
aoqi@0: * Constructs a SOAPException object with the given
aoqi@0: * String as the reason for the exception being thrown
aoqi@0: * and the given Throwable object as an embedded
aoqi@0: * exception.
aoqi@0: *
aoqi@0: * @param reason a description of what caused the exception
aoqi@0: * @param cause a Throwable object that is to
aoqi@0: * be embedded in this SOAPException object
aoqi@0: */
aoqi@0: public SOAPException(String reason, Throwable cause) {
aoqi@0: super(reason);
aoqi@0: initCause(cause);
aoqi@0: }
aoqi@0:
aoqi@0: /**
aoqi@0: * Constructs a SOAPException object initialized
aoqi@0: * with the given Throwable object.
aoqi@0: */
aoqi@0: public SOAPException(Throwable cause) {
aoqi@0: super(cause.toString());
aoqi@0: initCause(cause);
aoqi@0: }
aoqi@0:
aoqi@0: /**
aoqi@0: * Returns the detail message for this SOAPException
aoqi@0: * object.
aoqi@0: *
aoqi@0: * If there is an embedded Throwable object, and if the
aoqi@0: * SOAPException object has no detail message of its
aoqi@0: * own, this method will return the detail message from the embedded
aoqi@0: * Throwable object.
aoqi@0: *
aoqi@0: * @return the error or warning message for this
aoqi@0: * SOAPException or, if it has none, the
aoqi@0: * message of the embedded Throwable object,
aoqi@0: * if there is one
aoqi@0: */
aoqi@0: public String getMessage() {
aoqi@0: String message = super.getMessage();
aoqi@0: if (message == null && cause != null) {
aoqi@0: return cause.getMessage();
aoqi@0: } else {
aoqi@0: return message;
aoqi@0: }
aoqi@0: }
aoqi@0:
aoqi@0: /**
aoqi@0: * Returns the Throwable object embedded in this
aoqi@0: * SOAPException if there is one. Otherwise, this method
aoqi@0: * returns null.
aoqi@0: *
aoqi@0: * @return the embedded Throwable object or null
aoqi@0: * if there is none
aoqi@0: */
aoqi@0:
aoqi@0: public Throwable getCause() {
aoqi@0: return cause;
aoqi@0: }
aoqi@0:
aoqi@0: /**
aoqi@0: * Initializes the cause field of this SOAPException
aoqi@0: * object with the given Throwable object.
aoqi@0: *
aoqi@0: * This method can be called at most once. It is generally called from
aoqi@0: * within the constructor or immediately after the constructor has
aoqi@0: * returned a new SOAPException object.
aoqi@0: * If this SOAPException object was created with the
aoqi@0: * constructor {@link #SOAPException(Throwable)} or
aoqi@0: * {@link #SOAPException(String,Throwable)}, meaning that its
aoqi@0: * cause field already has a value, this method cannot be
aoqi@0: * called even once.
aoqi@0: *
aoqi@0: * @param cause the Throwable object that caused this
aoqi@0: * SOAPException object to be thrown. The value of this
aoqi@0: * parameter is saved for later retrieval by the
aoqi@0: * {@link #getCause()} method. A null value is
aoqi@0: * permitted and indicates that the cause is nonexistent or
aoqi@0: * unknown.
aoqi@0: * @return a reference to this SOAPException instance
aoqi@0: * @throws IllegalArgumentException if cause is this
aoqi@0: * Throwable object. (A Throwable object
aoqi@0: * cannot be its own cause.)
aoqi@0: * @throws IllegalStateException if the cause for this SOAPException object
aoqi@0: * has already been initialized
aoqi@0: */
aoqi@0: public synchronized Throwable initCause(Throwable cause) {
aoqi@0: if (this.cause != null) {
aoqi@0: throw new IllegalStateException("Can't override cause");
aoqi@0: }
aoqi@0: if (cause == this) {
aoqi@0: throw new IllegalArgumentException("Self-causation not permitted");
aoqi@0: }
aoqi@0: this.cause = cause;
aoqi@0:
aoqi@0: return this;
aoqi@0: }
aoqi@0: }