com.feedzai.commons.sql.abstraction.engine

Interface DatabaseEngine

All Known Implementing Classes:

AbstractDatabaseEngine, DB2Engine, H2Engine, MySqlEngine, OracleEngine, PostgreSqlEngine, SqlServerEngine

public interface DatabaseEngine

Interface with the specific database implementation.

Provides methods to query and manipulate database objects.

Since:

2.0.0

Author:

Rui Vilao (rui.vilao@feedzai.com)

Method Summary

Methods

Modifier and Type	Method and Description
void	addBatch(String name, EntityEntry entry) Adds an entry to the batch.
void	addEntity(DbEntity entity) Adds an entity to the engine.
void	beginTransaction() Starts a transaction.
boolean	checkConnection() Checks if the connection is alive.
boolean	checkConnection(boolean forceReconnect) Checks if the connection is alive.
void	clearParameters(String name) Clears the prepared statement parameters.
void	close() Closes the connection to the database.
String	commentCharacter()
void	commit() Commits the current transaction.
boolean	containsEntity(String name) Returns if the current engine contains the entity.
AbstractBatch	createBatch(int batchSize, long batchTimeout) Creates a new batch that periodically flushes a batch.
AbstractBatch	createBatch(int batchSize, long batchTimeout, String batchName) Creates a new batch that periodically flushes a batch.
void	createPreparedStatement(String name, Expression query) Creates a prepared statement.
void	createPreparedStatement(String name, Expression query, int timeout) Creates a prepared statement.
void	createPreparedStatement(String name, String query) Creates a prepared statement.
void	createPreparedStatement(String name, String query, int timeout) Creates a prepared statement.
void	dropEntity(String entity) Drops an entity.
DatabaseEngine	duplicate(Properties mergeProperties, boolean copyEntities) Duplicates a connection.
String	escapeCharacter()
void	executePS(String name) Executes the specified prepared statement.
Integer	executePSUpdate(String name) Executes update on the specified prepared statement.
int	executeUpdate(Expression query) Executes the given update.
int	executeUpdate(String query) Executes a native query.
void	flush() Flushes the batches for all the registered entities.
Connection	getConnection() Checks if the connection is available and returns it.
Dialect	getDialect() Gets the dialect being used.
Map<String,DbEntityType>	getEntities() Gets the database entities.
Map<String,DbColumnType>	getMetadata(String name) Gets the table metadata.
PdbProperties	getProperties() Gets the properties in use.
ResultIterator	getPSIterator(String name) Creates an iterator for the PreparedStatement bound to the given name.
List<Map<String,ResultColumn>>	getPSResultSet(String name) Gets the result set of the specified prepared statement.
Map<String,DbColumnType>	getQueryMetadata(Expression query) Gets the query metadata.
Map<String,DbColumnType>	getQueryMetadata(String query) Gets the query metadata.
boolean	isTransactionActive() Checks if a transaction is active.
ResultIterator	iterator(Expression query) Creates an iterator for the given SQL expression.
ResultIterator	iterator(String query) Creates an iterator for the given SQL sentence.
Long	persist(String name, EntityEntry entry) Persists a given entry.
Long	persist(String name, EntityEntry entry, boolean useAutoInc) Persists a given entry.
boolean	preparedStatementExists(String name) Checks if there's a prepared statement with the given name.
List<Map<String,ResultColumn>>	query(Expression query) Executes the given query.
List<Map<String,ResultColumn>>	query(String query) Executes the given native query.
DbEntity	removeEntity(String name) Removes the entity given the name.
void	removePreparedStatement(String name) Removes the given prepared statement.
void	rollback() Rolls back a transaction.
void	setExceptionHandler(ExceptionHandler eh) Sets the given exception handler in the engine.
void	setParameter(String name, int index, Object param) Sets the parameter on the specified index.
void	setParameters(String name, Object... params) Sets the parameters on the specified prepared statement.
String	translate(Expression query) Translates the given expression to the current dialect.
void	updateEntity(DbEntity entity) Updates an entity in the engine.

Method Detail

close

void close()

Closes the connection to the database.

beginTransaction

void beginTransaction()
                      throws DatabaseEngineRuntimeException

Starts a transaction. Doing this will set auto commit to false (Connection.getAutoCommit()).

Throws:

DatabaseEngineException - If something goes wrong while persisting data.

DatabaseEngineRuntimeException

addEntity

void addEntity(DbEntity entity)
               throws DatabaseEngineException

Adds an entity to the engine. It will create tables and everything necessary so persistence can work.

Parameters:

entity - The entity to add.

Throws:

DatabaseEngineException - If something goes wrong while creating the structures.

updateEntity

void updateEntity(DbEntity entity)
                  throws DatabaseEngineException

Updates an entity in the engine.

If the entity does not exists in the instance, the method addEntity(com.feedzai.commons.sql.abstraction.ddl.DbEntity) will be invoked.

The engine will compare the entity with the getMetadata(String) information and update the schema of the table.

ATTENTION: This method will only add new columns or drop removed columns in the database table. Primary Keys, Foreign Keys, Indexes and column types changes will not be updated.

Parameters:

entity - The entity to update.

Throws:

DatabaseEngineException

Since:

12.1.0

removeEntity

DbEntity removeEntity(String name)

Removes the entity given the name. If the schema is drop-create then the entity will be dropped.

Parameters:

name - The name of the entity to remove.

Returns:

The entity removed or null if there's no entity with the given name.

containsEntity

boolean containsEntity(String name)

Returns if the current engine contains the entity.

Parameters:

name - The entity name.

Returns:

True if the engine has the entity, false otherwise.

dropEntity

void dropEntity(String entity)
                throws DatabaseEngineException

Drops an entity.

Parameters:

entity - The entity name.

Throws:

DatabaseEngineException

persist

Long persist(String name,
           EntityEntry entry)
             throws DatabaseEngineException

Persists a given entry. Persisting a query implies executing the statement.

If you are inside of an explicit transaction, changes will only be visible upon explicit commit, otherwise a commit will immediately take place.

Parameters:

name - The entity name.

entry - The entry to persist.

Returns:

The ID of the auto generated value, null if there's no auto generated value.

Throws:

DatabaseEngineException - If something goes wrong while persisting data.

persist

Long persist(String name,
           EntityEntry entry,
           boolean useAutoInc)
             throws DatabaseEngineException

Persists a given entry. Persisting a query implies executing the statement. If define useAutoInc as false, PDB will disable the auto increments for the current insert and advance the sequences if needed.

If you are inside of an explicit transaction, changes will only be visible upon explicit commit, otherwise a commit will immediately take place.

Parameters:

name - The entity name.

entry - The entry to persist.

useAutoInc - Use or not the autoinc.

Returns:

The ID of the auto generated value, null if there's no auto generated value.

Throws:

DatabaseEngineException - If something goes wrong while persisting data.

flush

void flush()
           throws DatabaseEngineException

Flushes the batches for all the registered entities.

Throws:

DatabaseEngineException - If something goes wrong while persisting data.

commit

void commit()
            throws DatabaseEngineRuntimeException

Commits the current transaction. You should only call this method if you've previously called beginTransaction().

Throws:

DatabaseEngineException - If something goes wrong while persisting data.

DatabaseEngineRuntimeException

rollback

void rollback()
              throws DatabaseEngineRuntimeException

Rolls back a transaction. You should only call this method if you've previously called beginTransaction().

Throws:

DatabaseEngineRuntimeException - If the rollback fails.

isTransactionActive

boolean isTransactionActive()
                            throws DatabaseEngineRuntimeException

Checks if a transaction is active.

Returns:

true if the transaction is active, false otherwise.

Throws:

DatabaseEngineRuntimeException - If the access to the database fails.

executeUpdate

int executeUpdate(String query)
                  throws DatabaseEngineException

Executes a native query.

Parameters:

query - The query to execute.

Returns:

The number of rows updated.

Throws:

DatabaseEngineException - If something goes wrong executing the native query.

executeUpdate

int executeUpdate(Expression query)
                  throws DatabaseEngineException

Executes the given update.

Parameters:

query - The update to execute.

Throws:

DatabaseEngineException - If something goes wrong executing the update.

translate

String translate(Expression query)

Translates the given expression to the current dialect.

Parameters:

query - The query to translate.

Returns:

The translation result.

getDialect

Dialect getDialect()

Gets the dialect being used.

Returns:

The dialect being used.

createBatch

AbstractBatch createBatch(int batchSize,
                        long batchTimeout)

Creates a new batch that periodically flushes a batch. A flush will also occur when the maximum number of statements in the batch is reached.

Please be sure to call AbstractBatch.destroy() before closing the session with the database.

Parameters:

batchSize - The batch size.

batchTimeout - If inserts do not occur after the specified time, a flush will be performed.

Returns:

The batch.

createBatch

AbstractBatch createBatch(int batchSize,
                        long batchTimeout,
                        String batchName)

Creates a new batch that periodically flushes a batch. A flush will also occur when the maximum number of statements in the batch is reached.

Please be sure to call AbstractBatch.destroy() before closing the session with the database.

Parameters:

batchSize - The batch size.

batchTimeout - If inserts do not occur after the specified time, a flush will be performed.

batchName - The batch name.

Returns:

The batch.

checkConnection

boolean checkConnection(boolean forceReconnect)

Checks if the connection is alive.

Parameters:

forceReconnect - true to force the connection in case of failure, false otherwise.

Returns:

true if the connection is valid, false otherwise.

checkConnection

boolean checkConnection()

Checks if the connection is alive.

Returns:

true if the connection is valid, false otherwise.

addBatch

void addBatch(String name,
            EntityEntry entry)
              throws DatabaseEngineException

Adds an entry to the batch.

Parameters:

name - The entity name.

entry - The entry to persist.

Throws:

DatabaseEngineException - If something goes wrong while persisting data.

query

List<Map<String,ResultColumn>> query(Expression query)
                                     throws DatabaseEngineException

Executes the given query.

Parameters:

query - The query to execute.

Throws:

DatabaseEngineException - If something goes wrong executing the query.

query

List<Map<String,ResultColumn>> query(String query)
                                     throws DatabaseEngineException

Executes the given native query.

Parameters:

query - The query to execute.

Throws:

DatabaseEngineException - If something goes wrong executing the query.

getEntities

Map<String,DbEntityType> getEntities()
                                     throws DatabaseEngineException

Gets the database entities.

Returns:

The list of database entities and types (tables, views, and so on).

Throws:

DatabaseEngineException - If something occurs getting the existing tables.

getMetadata

Map<String,DbColumnType> getMetadata(String name)
                                     throws DatabaseEngineException

Gets the table metadata.

Returns:

A representation of the table columns and types.

Throws:

DatabaseEngineException - If something occurs getting the metadata.

getQueryMetadata

Map<String,DbColumnType> getQueryMetadata(Expression query)
                                          throws DatabaseEngineException

Gets the query metadata.

Parameters:

query - The query to retrieve the metadata from.

Returns:

A representation of the table columns and types.

Throws:

DatabaseEngineException - If something occurs getting the metadata.

getQueryMetadata

Map<String,DbColumnType> getQueryMetadata(String query)
                                          throws DatabaseEngineException

Gets the query metadata.

Parameters:

query - The query to retrieve the metadata from.

Returns:

A representation of the table columns and types.

Throws:

DatabaseEngineException - If something occurs getting the metadata.

duplicate

DatabaseEngine duplicate(Properties mergeProperties,
                       boolean copyEntities)
                         throws DuplicateEngineException

Duplicates a connection.

Parameters:

mergeProperties - Merge properties with the ones already existing.

copyEntities - true to include the entities in the new connection, false otherwise.

Returns:

The new connection.

Throws:

DuplicateEngineException - If policy is set to other than 'create' or 'none' or duplication fails for some reason.

getProperties

PdbProperties getProperties()

Gets the properties in use.

Returns:

A clone of the properties in use.

createPreparedStatement

void createPreparedStatement(String name,
                           Expression query)
                             throws NameAlreadyExistsException,
                                    DatabaseEngineException

Creates a prepared statement.

Parameters:

name - The prepared statement name.

query - The query.

Throws:

NameAlreadyExistsException - If the name already exists.

DatabaseEngineException - If something goes wrong creating the statement.

createPreparedStatement

void createPreparedStatement(String name,
                           String query)
                             throws NameAlreadyExistsException,
                                    DatabaseEngineException

Creates a prepared statement.

Parameters:

name - The prepared statement name.

query - The query.

Throws:

NameAlreadyExistsException - If the name already exists.

DatabaseEngineException - If something goes wrong creating the statement.

createPreparedStatement

void createPreparedStatement(String name,
                           Expression query,
                           int timeout)
                             throws NameAlreadyExistsException,
                                    DatabaseEngineException

Creates a prepared statement.

Parameters:

name - The prepared statement name.

query - The query.

timeout - The timeout (in seconds) for the query to execute.

Throws:

NameAlreadyExistsException - If the name already exists.

DatabaseEngineException - If something goes wrong creating the statement.

createPreparedStatement

void createPreparedStatement(String name,
                           String query,
                           int timeout)
                             throws NameAlreadyExistsException,
                                    DatabaseEngineException

Creates a prepared statement.

Parameters:

name - The prepared statement name.

query - The query.

timeout - The timeout (in seconds) for the query to execute.

Throws:

NameAlreadyExistsException - If the name already exists.

DatabaseEngineException - If something goes wrong creating the statement.

removePreparedStatement

void removePreparedStatement(String name)

Removes the given prepared statement.

Parameters:

name - The prepared statement name.

getPSResultSet

List<Map<String,ResultColumn>> getPSResultSet(String name)
                                              throws DatabaseEngineException

Gets the result set of the specified prepared statement.

Parameters:

name - The prepared statement name.

Returns:

The result.

Throws:

DatabaseEngineException - If something occurs getting the result.

setParameters

void setParameters(String name,
                 Object... params)
                   throws DatabaseEngineException,
                          ConnectionResetException

Sets the parameters on the specified prepared statement.

Parameters:

name - The prepared statement name.

params - The parameters to set.

Throws:

DatabaseEngineException - If something occurs setting the parameters.

ConnectionResetException - If the connection was reset while trying to set parameters.

setParameter

void setParameter(String name,
                int index,
                Object param)
                  throws DatabaseEngineException,
                         ConnectionResetException

Sets the parameter on the specified index.

Parameters:

name - The prepared statement name.

index - The index to set.

param - The parameter to set.

Throws:

DatabaseEngineException - If something occurs setting the parameters.

ConnectionResetException - If the connection was reset while trying to set the parameter.

executePS

void executePS(String name)
               throws DatabaseEngineException,
                      ConnectionResetException

Executes the specified prepared statement.

Parameters:

name - The prepared statement name.

Throws:

DatabaseEngineException - If something goes wrong while executing.

ConnectionResetException - If the connection is down and reestablishment occurs. If this happens, the user must reset the parameters and re-execute the query.

clearParameters

void clearParameters(String name)
                     throws DatabaseEngineException,
                            ConnectionResetException

Clears the prepared statement parameters.

Parameters:

name - The prepared statement name.

Throws:

DatabaseEngineException - If something occurs while clearing the parameters.

ConnectionResetException - If the connection was reset.

preparedStatementExists

boolean preparedStatementExists(String name)

Checks if there's a prepared statement with the given name.

Parameters:

name - The name to test.

Returns:

true if it exists, false otherwise.

executePSUpdate

Integer executePSUpdate(String name)
                        throws DatabaseEngineException,
                               ConnectionResetException

Executes update on the specified prepared statement.

Parameters:

name - The prepared statement name.

Throws:

DatabaseEngineException - If the prepared statement does not exist or something goes wrong while executing.

ConnectionResetException - If the connection is down and reestablishment occurs. If this happens, the user must reset the parameters and re-execute the query.

commentCharacter

String commentCharacter()

Returns:

The comment character of this engine implementation.

escapeCharacter

String escapeCharacter()

Returns:

The escape character of this engine implementation.

getConnection

Connection getConnection()
                         throws RetryLimitExceededException,
                                InterruptedException,
                                RecoveryException

Checks if the connection is available and returns it. If the connection is not available, it tries to reconnect (the number of times defined in the properties with the delay there specified).

Returns:

The connection.

Throws:

RetryLimitExceededException - If the retry limit is exceeded.

InterruptedException - If the thread is interrupted during reconnection.

RecoveryException

iterator

ResultIterator iterator(String query)
                        throws DatabaseEngineException

Creates an iterator for the given SQL sentence.

Parameters:

query - The query.

Returns:

An iterator for the results of the given SQL query.

Throws:

DatabaseEngineException - If a database access error occurs.

iterator

ResultIterator iterator(Expression query)
                        throws DatabaseEngineException

Creates an iterator for the given SQL expression.

Parameters:

query - The expression that represents the query.

Returns:

An iterator for the results of the given SQL expression.

Throws:

DatabaseEngineException - If a database access error occurs.

getPSIterator

ResultIterator getPSIterator(String name)
                             throws DatabaseEngineException

Creates an iterator for the PreparedStatement bound to the given name.

Parameters:

name - The name of the prepared statement.

Returns:

An iterator for the results of the prepared statement of the given name.

Throws:

DatabaseEngineException

setExceptionHandler

void setExceptionHandler(ExceptionHandler eh)

Sets the given exception handler in the engine.

Parameters:

eh - The reference for exception callbacks.