org.skife.jdbi.v2.Handle Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of jdbi Show documentation
Show all versions of jdbi Show documentation
jDBI is designed to provide convenient tabular data access in
Java(tm). It uses the Java collections framework for query
results, provides a convenient means of externalizing sql
statements, and provides named parameter support for any database
being used.
/*
* Copyright (C) 2004 - 2014 Brian McCallister
*
* 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.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 ususally is a wrapper around
* a JDBC Connection object.
*/
public interface Handle extends Closeable
{
/**
* 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();
/**
* 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
*/
Handle begin();
/**
* Commit a transaction
*/
Handle commit();
/**
* Rollback a transaction
*/
Handle rollback();
/**
* 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 {@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.
* @param sql the select sql
*/
Query> createQuery(String 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
*
* @param callableSql
* @return the Call
*/
Call createCall(String callableSql);
/**
* 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
* @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
* @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
* @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 {@link TransactionFailedException}
* will be thrown.
*
* @return value returned from the callback
* @throws TransactionFailedException if the transaction failed in the callback
*/
ReturnType inTransaction(TransactionCallback callback) throws TransactionFailedException;
/**
* Executes callback in a transaction. If the transaction succeeds, the
* result of the callback will be returned. If it fails a {@link 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.
*
* @return value returned from the callback
* @throws TransactionFailedException if the transaction failed in the callback
*/
ReturnType inTransaction(TransactionIsolationLevel level,
TransactionCallback callback) throws TransactionFailedException;
/**
* 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> select(String sql, Object... args);
/**
* 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.
*/
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)
*/
Script createScript(String name);
/**
* 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.
* @param name The name of the checkpoint
* @return The same handle
*/
Handle checkpoint(String name);
/**
* 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
* @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.
*/
void setSQLLog(SQLLog log);
/**
* 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 {@link Query#mapTo(Class)} for registered mappings.
*/
void registerMapper(ResultSetMapper mapper);
/**
* Register a result set mapper factory.
*
* Will be used with {@link Query#mapTo(Class)} for registerd mappings.
*/
void registerMapper(ResultSetMapperFactory 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.
*
* @param sqlObjectType
* @param
* @return the new sql object bound to this handle
*/
SqlObjectType attach(Class sqlObjectType);
/**
* 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
*
* @param level the isolation level to use
*/
void setTransactionIsolation(int level);
/**
* 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);
}