javax.xml.soap.SOAPException Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package javax.xml.soap;
/**
* An exception that signals that a SOAP exception has occurred. A 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 {
private static final long serialVersionUID = 5083961510786058130L;
/**
* 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.
*
* @return the error or warning message for this 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 IllegalArgumentException
* if cause is this Throwable object. (A
* Throwable object cannot be its own cause.)
* @throws 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;
}