/*
* 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 java.sql;
import java.io.Serializable;
import java.util.Iterator;
import java.util.NoSuchElementException;
/**
* An exception that indicates a failed JDBC operation.
* It provides the following information about problems encountered with
* database access:
* <ul>
* <li>A message string.</li>
* <li>A {@code SQLState} error description string following either
* <a href="http://en.wikipedia.org/wiki/SQL:1999">SQL 99</a> or X/OPEN {@code SQLState}
* conventions. {@link DatabaseMetaData#getSQLStateType} exposes the specific convention in
* use.</li>
* <li>A database-specific error code.</li>
* <li>The next exception in the chain.</li>
* </ul>
*
* @see DatabaseMetaData
*/
public class SQLException extends Exception implements Serializable, Iterable<Throwable> {
private static final long serialVersionUID = 2135244094396331484L;
private String SQLState = null;
private int vendorCode = 0;
private SQLException next = null;
/**
* Creates an {@code SQLException} object. The reason string is set to
* {@code null}, the {@code SQLState} string is set to {@code null} and the
* error code is set to 0.
*/
public SQLException() {
}
/**
* Creates an {@code SQLException} object. The reason string is set to the given
* reason string, the {@code SQLState} string is set to {@code null} and the error code is
* set to 0.
*
* @param theReason
* the string to use as the Reason string
*/
public SQLException(String theReason) {
this(theReason, null, 0);
}
/**
* Creates an {@code SQLException} object. The reason string is set to the
* given reason string, the {@code SQLState} string is set to the given
* {@code SQLState} string and the error code is set to 0.
*
* @param theReason
* the string to use as the reason string.
* @param theSQLState
* the string to use as the {@code SQLState} string.
*/
public SQLException(String theReason, String theSQLState) {
this(theReason, theSQLState, 0);
}
/**
* Creates an {@code SQLException} object. The reason string is set to the
* given reason string, the {@code SQLState} string is set to the given
* {@code SQLState} string and the error code is set to the given error code
* value.
*
* @param theReason
* the string to use as the reason string.
* @param theSQLState
* the string to use as the {@code SQLState} string.
* @param theErrorCode
* the integer value for the error code.
*/
public SQLException(String theReason, String theSQLState, int theErrorCode) {
super(theReason);
SQLState = theSQLState;
vendorCode = theErrorCode;
}
/**
* Creates an SQLException object. The Reason string is set to the null if
* cause == null or cause.toString() if cause!=null,and the cause Throwable
* object is set to the given cause Throwable object.
*
* @param theCause
* the Throwable object for the underlying reason this
* SQLException
*
* @since 1.6
*/
public SQLException(Throwable theCause) {
this(theCause == null ? null : theCause.toString(), null, 0, theCause);
}
/**
* Creates an SQLException object. The Reason string is set to the given and
* the cause Throwable object is set to the given cause Throwable object.
*
* @param theReason
* the string to use as the Reason string
* @param theCause
* the Throwable object for the underlying reason this
* SQLException
*
* @since 1.6
*/
public SQLException(String theReason, Throwable theCause) {
super(theReason, theCause);
}
/**
* Creates an SQLException object. The Reason string is set to the given
* reason string, the SQLState string is set to the given SQLState string
* and the cause Throwable object is set to the given cause Throwable
* object.
*
* @param theReason
* the string to use as the Reason string
* @param theSQLState
* the string to use as the SQLState string
* @param theCause
* the Throwable object for the underlying reason this
* SQLException
* @since 1.6
*/
public SQLException(String theReason, String theSQLState, Throwable theCause) {
super(theReason, theCause);
SQLState = theSQLState;
}
/**
* Creates an SQLException object. The Reason string is set to the given
* reason string, the SQLState string is set to the given SQLState string ,
* the Error Code is set to the given error code value, and the cause
* Throwable object is set to the given cause Throwable object.
*
* @param theReason
* the string to use as the Reason string
* @param theSQLState
* the string to use as the SQLState string
* @param theErrorCode
* the integer value for the error code
* @param theCause
* the Throwable object for the underlying reason this
* SQLException
* @since 1.6
*/
public SQLException(String theReason, String theSQLState, int theErrorCode,
Throwable theCause) {
this(theReason, theSQLState, theCause);
vendorCode = theErrorCode;
}
/**
* Returns the integer error code for this {@code SQLException}.
*
* @return The integer error code for this {@code SQLException}. The meaning
* of the code is specific to the vendor of the database.
*/
public int getErrorCode() {
return vendorCode;
}
/**
* Retrieves the {@code SQLException} chained to this {@code SQLException},
* if any.
*
* @return The {@code SQLException} chained to this {@code SQLException}.
* {@code null} if there is no {@code SQLException} chained to this
* {@code SQLException}.
*/
public SQLException getNextException() {
return next;
}
/**
* Retrieves the {@code SQLState} description string for this {@code
* SQLException} object.
*
* @return The {@code SQLState} string for this {@code SQLException} object.
* This is an error description string which follows either the SQL
* 99 conventions or the X/OPEN {@code SQLstate} conventions. The
* potential values of the {@code SQLState} string are described in
* each of the specifications. Which of the conventions is being
* used by the {@code SQLState} string can be discovered by using
* the {@code getSQLStateType} method of the {@code
* DatabaseMetaData} interface.
*/
public String getSQLState() {
return SQLState;
}
/**
* Obsolete. Appends {@code ex} to the end of this chain.
*/
public void setNextException(SQLException ex) {
if (next != null) {
next.setNextException(ex);
} else {
next = ex;
}
}
/**
* Obsolete. {@link #getCause()} should be used instead of this iterator. Returns an iterator
* over the exceptions added with {@link #setNextException}.
*/
public Iterator<Throwable> iterator() {
return new InternalIterator(this);
}
private static class InternalIterator implements Iterator<Throwable> {
private SQLException current;
InternalIterator(SQLException e) {
current = e;
}
public boolean hasNext() {
return current != null;
}
public Throwable next() {
if (current == null) {
throw new NoSuchElementException();
}
SQLException ret = current;
current = current.next;
return ret;
}
public void remove() {
throw new UnsupportedOperationException();
}
}
}