/*
 * Licensed 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 org.skife.jdbi.v2;

import org.skife.jdbi.v2.exceptions.TransactionFailedException;
import org.skife.jdbi.v2.tweak.ArgumentFactory;
import org.skife.jdbi.v2.tweak.ContainerFactory;
import org.skife.jdbi.v2.tweak.ResultColumnMapper;
import org.skife.jdbi.v2.tweak.ResultSetMapper;
import org.skife.jdbi.v2.tweak.SQLLog;
import org.skife.jdbi.v2.tweak.StatementBuilder;
import org.skife.jdbi.v2.tweak.StatementLocator;
import org.skife.jdbi.v2.tweak.StatementRewriter;

import java.io.Closeable;
import java.sql.Connection;
import java.util.List;
import java.util.Map;

This represents a connection to the database system. It usually is a wrapper around
a JDBC Connection object.
/**
 * This represents a connection to the database system. It usually is a wrapper around
 * a JDBC Connection object.
 */
public interface Handle extends Closeable
{

    
Get the JDBC Connection this Handle uses
Returns:
the JDBC Connection this Handle uses/**
     * Get the JDBC Connection this Handle uses
     * @return the JDBC Connection this Handle uses
     */
    Connection getConnection();

    @Override
    /**
     * @throws org.skife.jdbi.v2.exceptions.UnableToCloseResourceException if any
     * resources throw exception while closing
     */
    void close();

    
Returns:
true if this handle is closed/** @return true if this handle is closed */
    boolean isClosed();

    
Define a statement attribute which will be applied to all StatementContext instances for statements created from this handle 
Params:
key – Attribute name
value – Attribute value/**
     * Define a statement attribute which will be applied to all {@link StatementContext}
     * instances for statements created from this handle
     *
     * @param key Attribute name
     * @param value Attribute value
     */
    void define(String key, Object value);

    
Start a transaction
/**
     * Start a transaction
     */
    Handle begin();

    
Commit a transaction
/**
     * Commit a transaction
     */
    Handle commit();

    
Rollback a transaction
/**
     * Rollback a transaction
     */
    Handle rollback();

    
Rollback a transaction to a named checkpoint
Params:
checkpointName – the name of the checkpoint, previously declared with checkpoint/**
     * Rollback a transaction to a named checkpoint
     * @param checkpointName the name of the checkpoint, previously declared with {@link Handle#checkpoint}
     */
    Handle rollback(String checkpointName);

    
Is the handle in a transaction? It defers to the underlying TransactionHandler /**
     * Is the handle in a transaction? It defers to the underlying {@link org.skife.jdbi.v2.tweak.TransactionHandler}
     */
    boolean isInTransaction();

    
Return a default Query instance which can be executed later, as long as this handle remains open.
Params:
sql – the select sql/**
     * Return a default Query instance which can be executed later, as long as this handle remains open.
     * @param sql the select sql
     */
    Query<Map<String, Object>> createQuery(String sql);

    
Create an Insert or Update statement which returns the number of rows modified.
Params:
sql – The statement sql/**
     * Create an Insert or Update statement which returns the number of rows modified.
     * @param sql The statement sql
     */
    Update createStatement(String sql);

    
Create a call to a stored procedure
Params:
callableSql – 
Returns:
the Call/**
     * Create a call to a stored procedure
     *
     * @param callableSql
     * @return the Call
     */
    Call createCall(String callableSql);


    
Execute a simple insert statement
Params:
sql – the insert SQL
Returns:
the number of rows inserted/**
     * Execute a simple insert statement
     * @param sql the insert SQL
     * @return the number of rows inserted
     */
    int insert(String sql, Object... args);

    
Execute a simple update statement
Params:
sql – the update SQL
args – positional arguments
Returns:
the number of updated inserted/**
     * Execute a simple update statement
     * @param sql the update SQL
     * @param args positional arguments
     * @return the number of updated inserted
     */
    int update(String sql, Object... args);

    
Prepare a batch to execute. This is for efficiently executing more than one
of the same statements with different parameters bound
Params:
sql – the batch SQL
Returns:
a batch which can have "statements" added/**
     * Prepare a batch to execute. This is for efficiently executing more than one
     * of the same statements with different parameters bound
     * @param sql the batch SQL
     * @return a batch which can have "statements" added
     */
    PreparedBatch prepareBatch(String sql);

    
Create a non-prepared (no bound parameters, but different SQL, batch statement
See Also:
prepareBatch(String)
Returns:
empty batch/**
     * Create a non-prepared (no bound parameters, but different SQL, batch statement
     * @return empty batch
     * @see Handle#prepareBatch(String)
     */
    Batch createBatch();

    
Executes callback in a transaction. If the transaction succeeds, the result of the callback will be returned. If it fails a TransactionFailedException will be thrown. 
Throws:
TransactionFailedException – if the transaction failed in the callback
Returns:
value returned from the callback/**
     * Executes <code>callback</code> in a transaction. If the transaction succeeds, the
     * result of the callback will be returned. If it fails a {@link TransactionFailedException}
     * will be thrown.
     *
     * @return value returned from the callback
     * @throws TransactionFailedException if the transaction failed in the callback
     */
    <ReturnType> ReturnType inTransaction(TransactionCallback<ReturnType> callback) throws TransactionFailedException;

    
Executes callback in a transaction. If the transaction succeeds, the result of the callback will be returned. If it fails a TransactionFailedException will be thrown. 
Throws:
TransactionFailedException – if the transaction failed in the callback/**
     * Executes <code>callback</code> in a transaction. If the transaction succeeds, the
     * result of the callback will be returned. If it fails a {@link TransactionFailedException}
     * will be thrown.
     *
     * @throws TransactionFailedException if the transaction failed in the callback
     */
    void useTransaction(TransactionConsumer callback) throws TransactionFailedException;

    
Executes callback in a transaction. If the transaction succeeds, the result of the callback will be returned. If it fails a TransactionFailedException will be thrown. 

This form accepts a transaction isolation level which will be applied to the connection
for the scope of this transaction, after which the original isolation level will be restored.

Throws:
TransactionFailedException – if the transaction failed in the callback
Returns:
value returned from the callback/**
     * Executes <code>callback</code> in a transaction. If the transaction succeeds, the
     * result of the callback will be returned. If it fails a {@link TransactionFailedException}
     * will be thrown.
     * <p>
     * This form accepts a transaction isolation level which will be applied to the connection
     * for the scope of this transaction, after which the original isolation level will be restored.
     * </p>
     * @return value returned from the callback
     * @throws TransactionFailedException if the transaction failed in the callback
     */
    <ReturnType> ReturnType inTransaction(TransactionIsolationLevel level,
                                          TransactionCallback<ReturnType> callback) throws TransactionFailedException;

    
Executes callback in a transaction. If the transaction succeeds, the result of the callback will be returned. If it fails a TransactionFailedException will be thrown. 

This form accepts a transaction isolation level which will be applied to the connection
for the scope of this transaction, after which the original isolation level will be restored.

Throws:
TransactionFailedException – if the transaction failed in the callback
Returns:
value returned from the callback/**
     * Executes <code>callback</code> in a transaction. If the transaction succeeds, the
     * result of the callback will be returned. If it fails a {@link TransactionFailedException}
     * will be thrown.
     * <p>
     * This form accepts a transaction isolation level which will be applied to the connection
     * for the scope of this transaction, after which the original isolation level will be restored.
     * </p>
     * @return value returned from the callback
     * @throws TransactionFailedException if the transaction failed in the callback
     */
    void useTransaction(TransactionIsolationLevel level, TransactionConsumer callback) throws TransactionFailedException;

    
Convenience method which executes a select with purely positional arguments
Params:
sql – SQL or named statement
args – arguments to bind positionally
Returns:
results of the query/**
     * Convenience method which executes a select with purely positional arguments
     * @param sql SQL or named statement
     * @param args arguments to bind positionally
     * @return results of the query
     */
    List<Map<String, Object>> select(String sql, Object... args);

    
Allows for overiding the default statement locator. The default searches the
classpath for named statements
/**
     * Allows for overiding the default statement locator. The default searches the
     * classpath for named statements
     */
    void setStatementLocator(StatementLocator locator);

    
Allows for overiding the default statement rewriter. The default handles
named parameter interpolation.
/**
     * Allows for overiding the default statement rewriter. The default handles
     * named parameter interpolation.
     */
    void setStatementRewriter(StatementRewriter rewriter);

    
Creates an SQL script, looking for the source of the script using the
current statement locator (which defaults to searching the classpath)
/**
     * Creates an SQL script, looking for the source of the script using the
     * current statement locator (which defaults to searching the classpath)
     */
    Script createScript(String name);

    
Execute some SQL with no return value
Params:
sql – the sql to execute
args – arguments to bind to the sql/**
     * Execute some SQL with no return value
     * @param sql the sql to execute
     * @param args arguments to bind to the sql
     */
    void execute(String sql, Object... args);

    
Create a transaction checkpoint (savepoint in JDBC terminology) with the name provided.
Params:
name – The name of the checkpoint
Returns:
The same handle/**
     * Create a transaction checkpoint (savepoint in JDBC terminology) with the name provided.
     * @param name The name of the checkpoint
     * @return The same handle
     */
    Handle checkpoint(String name);

    
Release a previously created checkpoint
Params:
checkpointName – the name of the checkpoint to release/**
     * Release a previously created checkpoint
     *
     * @param checkpointName the name of the checkpoint to release
     */
    Handle release(String checkpointName);

    
Specify the statement builder to use for this handle
Params:
builder – StatementBuilder to be used/**
     * Specify the statement builder to use for this handle
     * @param builder StatementBuilder to be used
     */
    void setStatementBuilder(StatementBuilder builder);

    
Specify the class used to log sql statements. The default is inherited from the DBI used
to create this Handle.
/**
     * Specify the class used to log sql statements. The default is inherited from the DBI used
     * to create this Handle.
     */
    void setSQLLog(SQLLog log);

    
Specify the class used to collect timing information. The default is inherited from the DBI used
to create this Handle.
/**
     * Specify the class used to collect timing information. The default is inherited from the DBI used
     * to create this Handle.
     */
    void setTimingCollector(TimingCollector timingCollector);

    
Register a result set mapper which will have its parameterized type inspected to determine what it maps to Will be used with Query.mapTo(Class) for registered mappings. /**
     * Register a result set mapper which will have its parameterized type inspected to determine what it maps to
     *
     * Will be used with {@link Query#mapTo(Class)} for registered mappings.
     */
    void registerMapper(ResultSetMapper mapper);

    
Register a result set mapper factory. Will be used with Query.mapTo(Class) for registerd mappings. /**
     * Register a result set mapper factory.
     *
     * Will be used with {@link Query#mapTo(Class)} for registerd mappings.
     */
    void registerMapper(ResultSetMapperFactory factory);

    
Register a result column mapper which will have its parameterized type inspected to determine what it maps to Column mappers may be reused by ResultSetMapper to map individual columns. /**
     * Register a result column mapper which will have its parameterized type inspected to determine what it maps to
     *
     * Column mappers may be reused by {@link ResultSetMapper} to map individual columns.
     */
    void registerColumnMapper(ResultColumnMapper mapper);

    
Register a result column mapper factory. Column mappers may be reused by ResultSetMapper to map individual columns. /**
     * Register a result column mapper factory.
     *
     * Column mappers may be reused by {@link ResultSetMapper} to map individual columns.
     */
    void registerColumnMapper(ResultColumnMapperFactory factory);

    
Create a a sql object of the specified type bound to this handle. Any state changes to the handle, or the
sql object, such as transaction status, closing it, etc, will apply to both the object and the handle.
Params:
sqlObjectType – 
Type parameters:
<SqlObjectType> – 
Returns:
the new sql object bound to this handle/**
     * Create a a sql object of the specified type bound to this handle. Any state changes to the handle, or the
     * sql object, such as transaction status, closing it, etc, will apply to both the object and the handle.
     *
     * @param sqlObjectType
     * @param <SqlObjectType>
     * @return the new sql object bound to this handle
     */
    <SqlObjectType> SqlObjectType attach(Class<SqlObjectType> sqlObjectType);

    
Set the transaction isolation level on the underlying connection
Params:
level – the isolation level to use/**
     * Set the transaction isolation level on the underlying connection
     *
     * @param level the isolation level to use
     */
    void setTransactionIsolation(TransactionIsolationLevel level);

    
Set the transaction isolation level on the underlying connection
Params:
level – the isolation level to use/**
     * Set the transaction isolation level on the underlying connection
     *
     * @param level the isolation level to use
     */
    void setTransactionIsolation(int level);

    
Obtain the current transaction isolation level
Returns:
the current isolation level on the underlying connection/**
     * Obtain the current transaction isolation level
     *
     * @return the current isolation level on the underlying connection
     */
    TransactionIsolationLevel getTransactionIsolationLevel();

    void registerArgumentFactory(ArgumentFactory argumentFactory);

    void registerContainerFactory(ContainerFactory<?> factory);

    void setSqlObjectContext(SqlObjectContext context);

    SqlObjectContext getSqlObjectContext();
}