java/sql/BatchUpdateException.java

/*
 * 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;

/**
 * This exception is thrown if a problem occurs during a batch update operation.
 * <p>
 * A {@code BatchUpdateException} provides additional information about the
 * problem that occurred, compared with a standard {@code SQLException}. It
 * supplies update counts for successful commands which were executed before the
 * exception was encountered.
 * <p>
 * The element order in the array of update counts matches the order that the
 * commands were added to the batch operation.
 * <p>
 * Once a batch update command fails and a {@code BatchUpdateException} is
 * thrown, the JDBC driver may continue processing the remaining commands in the
 * batch. If the driver does process more commands after the problem occurs, the
 * array returned by {@code BatchUpdateException.getUpdateCounts} has an element
 * for every command in the batch, not only those that executed successfully. In
 * this case, the array element for any command which encountered a problem is
 * set to {@code Statement.EXECUTE_FAILED}.
 */
public class BatchUpdateException extends SQLException implements Serializable {

    private static final long serialVersionUID = 5977529877145521757L;

    private int[] updateCounts = null;

    /**
     * Creates a default {@code BatchUpdateException} with the parameters
     * <i>reason</i>, <i>SQLState</i>, and <i>update counts</i> set to {@code
     * null} and the <i>vendor code</i> set to 0.
     */
    public BatchUpdateException() {
    }

    /**
     * Creates an BatchUpdateException object. The reason is set to
     * null if cause == null otherwise to cause.toString(), and the cause
     * Throwable object is set to the given cause Throwable object.
     *
     * @param cause the Throwable object for the underlying reason this SQLException
     *
     * @since 1.6
     */
    public BatchUpdateException(Throwable cause) {
        this(null, cause);
    }

    /**
     * Creates an BatchUpdateException object. The Reason string is set to the
     * null if cause == null otherwise to cause.toString(), and the cause
     * Throwable object is set to the given cause Throwable object. SQLState is
     * initialized to null while vendorCode is zero.
     *
     * @param cause the Throwable object for the underlying reason this SQLException
     *
     * @since 1.6
     */
    public BatchUpdateException(int[] updateCounts, Throwable cause) {
        super(cause);
        this.updateCounts = updateCounts;
    }

    /**
     * Creates an BatchUpdateException object. The cause Throwable object is set
     * to the given cause Throwable object. SQLState is initialized to null
     * while vendorCode is zero.
     *
     * @param cause the Throwable object for the underlying reason this SQLException
     *
     * @since 1.6
     */
    public BatchUpdateException(String reason, int[] updateCounts,
            Throwable cause) {
        super(reason, cause);
        this.updateCounts = updateCounts;
    }

    /**
     * Creates an BatchUpdateException object. The cause Throwable object is set
     * to the given cause Throwable object and the updateCounts array set to the
     * int array parameter. SQLState is initialized to null while vendorCode is
     * zero.
     *
     * @param cause the Throwable object for the underlying reason this SQLException
     *
     * @since 1.6
     */
    public BatchUpdateException(String reason, String SQLState,
            int[] updateCounts, Throwable cause) {
        super(reason, SQLState, cause);
        this.updateCounts = updateCounts;
    }

    /**
     * Creates an BatchUpdateException object. The cause Throwable object is set
     * to the given cause Throwable object and the updateCounts array set to the
     * int array parameter. VendorCode is set to the given vendorCode. SQLState
     * is initialized to null while vendorCode is zero.
     *
     * @param cause the Throwable object for the underlying reason this SQLException
     *
     * @since 1.6
     */
    public BatchUpdateException(String reason, String SQLState, int vendorCode,
            int[] updateCounts, Throwable cause) {
        super(reason, SQLState, vendorCode, cause);
        this.updateCounts = updateCounts;
    }

    /**
     * Creates a {@code BatchUpdateException} with the {@code updateCounts} set
     * to the supplied value. All other fields are set to their
     * default values.
     *
     * @param updateCounts
     *            the array of {@code updateCounts} giving the number of
     *            successful updates (or another status code) for each command
     *            in the batch that was attempted.
     */
    public BatchUpdateException(int[] updateCounts) {
        this.updateCounts = updateCounts;
    }

    /**
     * Creates a {@code BatchUpdateException} with the {@code updateCounts} and
     * {@code reason} set to the supplied values. All other fields are set to their
     * default values.
     *
     * @param reason
     *            the message providing information about the source of this
     *            exception.
     * @param updateCounts
     *            the array of {@code updateCounts} giving the number of
     *            successful updates (or another status code) for each command
     *            in the batch that was attempted.
     */
    public BatchUpdateException(String reason, int[] updateCounts) {
        super(reason);
        this.updateCounts = updateCounts;
    }

    /**
     * Creates a {@code BatchUpdateException} with the {@code reason}, {@code
     * SQLState} and {@code updateCounts} set to the supplied values. All other
     * fields are set to their default values.
     *
     * @param reason
     *            the message providing information about the source of this
     *            exception.
     * @param SQLState
     *            the X/OPEN value to use for the {@code SQLState}
     * @param updateCounts
     *            the array of {@code updateCounts} giving the number of
     *            successful updates (or another status code) for each command
     *            in the batch that was attempted.
     */
    public BatchUpdateException(String reason, String SQLState,
            int[] updateCounts) {
        super(reason, SQLState);
        this.updateCounts = updateCounts;
    }

    /**
     * Creates a {@code BatchUpdateException} for the case where all relevant
     * information is provided.
     *
     * @param reason
     *            the message providing information about the source of this
     *            exception.
     * @param SQLState
     *            the X/OPEN value to use for the {@code SQLState}.
     * @param vendorCode
     *            the value to use for the vendor error code.
     * @param updateCounts
     *            the array of {@code updateCounts} giving the number of
     *            successful updates (or another status code) for each command
     *            in the batch that was attempted.
     */
    public BatchUpdateException(String reason, String SQLState, int vendorCode,
            int[] updateCounts) {
        super(reason, SQLState, vendorCode);
        this.updateCounts = updateCounts;
    }

    /**
     * Gets the <i>update count</i> array giving status information for every
     * command that was attempted in the batch.
     * <p>
     * If a batch update command fails and a {@code BatchUpdateException} is
     * thrown, the JDBC driver may continue processing the remaining commands in
     * the batch. If the driver does so, the array returned by {@code
     * BatchUpdateException.getUpdateCounts} has an element for every command in
     * the batch, not only those that executed successfully. In this case, the
     * array element for any command which encountered a problem is set to
     * {@code Statement.EXECUTE_FAILED}.
     *
     * @return an array that contains the successful update counts, before this
     *         exception was thrown. Alternatively, if the driver continues to
     *         process commands following an error, for each successive command
     *         there is a corresponding element in the array giving one of the
     *         following status values:
     *         <ol>
     *         <li>the number of successful updates</li> <li>{@code
     *         Statement.SUCCESS_NO_INFO} indicating that the command completed
     *         successfully, but the amount of altered rows is unknown.</li>
     *         <li>{@code Statement.EXECUTE_FAILED} indicating that the command
     *         was unsuccessful.</li>
     *         </ol>
     */
    public int[] getUpdateCounts() {
        return updateCounts;
    }
}