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