001 /* 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, 013 * software distributed under the License is distributed on an 014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 015 * KIND, either express or implied. See the License for the 016 * specific language governing permissions and limitations 017 * under the License. 018 */ 019 020 package javax.xml.soap; 021 022 /** 023 * An exception that signals that a SOAP exception has 024 * occurred. A <CODE>SOAPException</CODE> object may contain a 025 * <CODE>String</CODE> that gives the reason for the exception, an 026 * embedded <CODE>Throwable</CODE> object, or both. This class 027 * provides methods for retrieving reason messages and for 028 * retrieving the embedded <CODE>Throwable</CODE> object.</P> 029 * 030 * <P>Typical reasons for throwing a <CODE>SOAPException</CODE> 031 * object are problems such as difficulty setting a header, not 032 * being able to send a message, and not being able to get a 033 * connection with the provider. Reasons for embedding a <CODE> 034 * Throwable</CODE> object include problems such as input/output 035 * errors or a parsing problem, such as an error in parsing a 036 * header. 037 */ 038 public class SOAPException extends Exception { 039 040 /** 041 * Constructs a <CODE>SOAPException</CODE> object with no 042 * reason or embedded <CODE>Throwable</CODE> object. 043 */ 044 public SOAPException() { 045 cause = null; 046 } 047 048 /** 049 * Constructs a <CODE>SOAPException</CODE> object with the 050 * given <CODE>String</CODE> as the reason for the exception 051 * being thrown. 052 * @param reason a description of what caused 053 * the exception 054 */ 055 public SOAPException(String reason) { 056 057 super(reason); 058 059 cause = null; 060 } 061 062 /** 063 * Constructs a <CODE>SOAPException</CODE> object with the 064 * given <CODE>String</CODE> as the reason for the exception 065 * being thrown and the given <CODE>Throwable</CODE> object as 066 * an embedded exception. 067 * @param reason a description of what caused 068 * the exception 069 * @param cause a <CODE>Throwable</CODE> object 070 * that is to be embedded in this <CODE>SOAPException</CODE> 071 * object 072 */ 073 public SOAPException(String reason, Throwable cause) { 074 075 super(reason); 076 077 initCause(cause); 078 } 079 080 /** 081 * Constructs a <CODE>SOAPException</CODE> object 082 * initialized with the given <CODE>Throwable</CODE> 083 * object. 084 * @param cause a <CODE>Throwable</CODE> object 085 * that is to be embedded in this <CODE>SOAPException</CODE> 086 * object 087 */ 088 public SOAPException(Throwable cause) { 089 090 super(cause.toString()); 091 092 initCause(cause); 093 } 094 095 /** 096 * Returns the detail message for this <CODE> 097 * SOAPException</CODE> object. 098 * 099 * <P>If there is an embedded <CODE>Throwable</CODE> object, 100 * and if the <CODE>SOAPException</CODE> object has no detail 101 * message of its own, this method will return the detail 102 * message from the embedded <CODE>Throwable</CODE> 103 * object.</P> 104 * @return the error or warning message for this <CODE> 105 * SOAPException</CODE> or, if it has none, the message of 106 * the embedded <CODE>Throwable</CODE> object, if there is 107 * one 108 */ 109 public String getMessage() { 110 111 String s = super.getMessage(); 112 113 if ((s == null) && (cause != null)) { 114 return cause.getMessage(); 115 } else { 116 return s; 117 } 118 } 119 120 /** 121 * Returns the <CODE>Throwable</CODE> object embedded in 122 * this <CODE>SOAPException</CODE> if there is one. Otherwise, 123 * this method returns <CODE>null</CODE>. 124 * @return the embedded <CODE>Throwable</CODE> object or <CODE> 125 * null</CODE> if there is none 126 */ 127 public Throwable getCause() { 128 return cause; 129 } 130 131 /** 132 * Initializes the <CODE>cause</CODE> field of this <CODE> 133 * SOAPException</CODE> object with the given <CODE> 134 * Throwable</CODE> object. 135 * 136 * <P>This method can be called at most once. It is generally 137 * called from within the constructor or immediately after the 138 * constructor has returned a new <CODE>SOAPException</CODE> 139 * object. If this <CODE>SOAPException</CODE> object was 140 * created with the constructor {@link #SOAPException(java.lang.Throwable) SOAPException(java.lang.Throwable)} 141 * or {@link #SOAPException(java.lang.String, java.lang.Throwable) SOAPException(java.lang.String, java.lang.Throwable)}, meaning 142 * that its <CODE>cause</CODE> field already has a value, this 143 * method cannot be called even once. 144 * 145 * @param cause the <CODE>Throwable</CODE> 146 * object that caused this <CODE>SOAPException</CODE> object 147 * to be thrown. The value of this parameter is saved for 148 * later retrieval by the <A href= 149 * "../../../javax/xml/soap/SOAPException.html#getCause()"> 150 * <CODE>getCause()</CODE></A> method. A <TT>null</TT> value 151 * is permitted and indicates that the cause is nonexistent 152 * or unknown. 153 * @return a reference to this <CODE>SOAPException</CODE> 154 * instance 155 * @throws java.lang.IllegalArgumentException if 156 * <CODE>cause</CODE> is this <CODE>Throwable</CODE> object. 157 * (A <CODE>Throwable</CODE> object cannot be its own 158 * cause.) 159 * @throws java.lang.IllegalStateException if this <CODE> 160 * SOAPException</CODE> object was created with {@link #SOAPException(java.lang.Throwable) SOAPException(java.lang.Throwable)} 161 * or {@link #SOAPException(java.lang.String, java.lang.Throwable) SOAPException(java.lang.String, java.lang.Throwable)}, or this 162 * method has already been called on this <CODE> 163 * SOAPException</CODE> object 164 */ 165 public synchronized Throwable initCause(Throwable cause) { 166 167 if (this.cause != null) { 168 throw new IllegalStateException("Can't override cause"); 169 } 170 171 if (cause == this) { 172 throw new IllegalArgumentException("Self-causation not permitted"); 173 } else { 174 this.cause = cause; 175 176 return this; 177 } 178 } 179 180 private Throwable cause; 181 }