//
// $Id: DatabaseLiaison.java,v 1.2 2001/09/20 02:09:09 mdb Exp $
//
// samskivert library - useful routines for java programs
// Copyright (C) 2001 Michael Bayne
// 
// This library is free software; you can redistribute it and/or modify it
// under the terms of the GNU Lesser General Public License as published
// by the Free Software Foundation; either version 2.1 of the License, or
// (at your option) any later version.
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

package com.samskivert.jdbc;

import java.sql.Connection;
import java.sql.SQLException;

/**
 * Despite good intentions, JDBC and SQL do not provide a unified
 * interface to all databases. There remain idiosyncrasies that must be
 * worked around when making code interact with different database
 * servers. The database liaison encapsulates the code needed to
 * straighten out the curves and curve out the straights.
 */
public interface DatabaseLiaison
{
    /**
     * Indicates whether or not this database liaison is the proper
     * liaison for the specified database URL.
     *
     * @return true if we should use this liaison for connections created
     * with the supplied URL, false if we should not.
     */
    public boolean matchesURL (String url);

    /**
     * Determines whether or not the supplied SQL exception was caused by
     * a duplicate row being inserted into a table with a unique key.
     *
     * @return true if the exception was caused by the insertion of a
     * duplicate row, false if not.
     */
    public boolean isDuplicateRowException (SQLException sqe);

    /**
     * Determines whether or not the supplied SQL exception is a transient
     * failure, meaning one that is not related to the SQL being executed,
     * but instead to the environment at the time of execution, like the
     * connection to the database having been lost.
     *
     * @return true if the exception was thrown due to a transient
     * failure, false if not.
     */
    public boolean isTransientException (SQLException sqe);

    /**
     * Returns the value of an <code>AUTO_INCREMENT</code> column for the
     * last row insertion. This is MySQL specific, but exists here for now
     * until we sort out a general purpose mechanism for assigning unique
     * ids.
     *
     * @return the most recent ID generated by an insert into an
     * <code>AUTO_INCREMENT</code> table or -1 if it could not be
     * obtained.
     */
    public int lastInsertedId (Connection conn) throws SQLException;
}
