com.goldencode.p2j.persist.orm

Class SQLQuery

java.lang.Object

com.goldencode.p2j.persist.orm.SQLQuery

public class SQLQuery
extends java.lang.Object

A SQL query that can be cached and executed multiple times. Note: internally, the object is NOT synchronized, so the usage intervals MUST NOT overlap.

Field Summary

Fields

Modifier and Type	Field and Description
private java.lang.String	baseSql The SQL statement, possibly with placeholders.
private boolean	bindParam2SessionVar Flags that query bind parameters should be mapped to session variables
private boolean	canRaiseSqlWarning Flag indicating that the query can raise SQLWarning.
private static java.lang.String	CFG_FETCH_SIZE Directory path for fetch size override
private boolean	containsErrorHandling Flag indicating that the query contains error handling
private static int	DEFAULT_FETCH_SIZE Default JDBC fetch size (may be overridden by runtime configuration)
private static int	fetchSize JDBC fetch size (same for all databases)
private static boolean	fine Flag indicating fine logging.
private static NanoTimer	HYDRATE_RECORD Instrumentation for hydrateRecord(java.sql.ResultSet, com.goldencode.p2j.persist.orm.RowStructure, int, com.goldencode.p2j.persist.orm.Session).
private static CentralLogger	LOG Logger
private int	maxParamIndex The higher index of the parameter set.
private java.lang.Object[]	parameters The current list of positional parameters.
private int[]	parPerm The parameter permutations.
private java.util.List<FQLPreprocessor.SessionAttr>	sessionAttrs Mutable session attributes' values used in the query.
private static QueryProfilerJMX	SIMPLE_QUERY_PROFILER Profiler done for queries: cache hits, cache misses, etc.
private java.lang.String	sql The SQL statement to be executed.
private java.sql.PreparedStatement	stmt The PreparedStatement.

Constructor Summary

Constructors

Constructor and Description
SQLQuery(java.lang.String sql) Constructs a new object.
SQLQuery(java.lang.String sql, java.util.List<FQLPreprocessor.SessionAttr> sessionAttrs, int[] parPerm) Constructs a new object.

Method Summary

Modifier and Type	Method and Description
private void	activateErrorHandler(Session session) Activate error handler at the database side.
boolean	bindParam2SessionVar() Check if the query bind parameters should be mapped to session variables.
SQLQuery	bindParam2SessionVar(boolean bindParam2SessionVar) Set the flag indicating if the query can bind parameters should be mapped to session variables.
boolean	canRaiseSqlWarning() Checks if the query can raise SQLWarning.
SQLQuery	canRaiseSqlWarning(boolean canRaiseSqlWarning) Set the flag indicating if the query can raise SQLWarning.
private static void	checkClosed(java.sql.Connection conn) Test whether the connection is alive (not closed).
private void	close() Closes this object by releasing all acquired resources.
SQLQuery	containsErrorHandling(boolean value) Set the value of the flag indicating that the query contains error handling.
private void	ensureSize(int fitIndex) Makes sure the array that holds the parameters for this query is large enough to accommodate the fitIndex-th parameter.
int	executeUpdate(Session session) Execute the update SQL query.
SQLQuery	expandPlaceholders(Dialect dialect) Expand placeholder.
(package private) static java.lang.Long	getRecordPrimaryKey(java.sql.ResultSet resultSet, RowStructure rowStructure, int rsOffset) Get the primary key of a Record from a ResultSet.
(package private) static BaseRecord	hydrateRecord(java.sql.ResultSet resultSet, RowStructure rowStructure, int rsOffset, Session session) Hydrate a Record from a ResultSet, ie a new object that implements the DMO interface and having the properties set from the current row of the record set.
private static BaseRecord	hydrateRecordImpl(java.sql.ResultSet resultSet, RowStructure rowStructure, int rsOffset, Session session) Hydrate a Record from a ResultSet, ie a new object that implements the DMO interface and having the properties set from the current row of the record set.
<T> java.util.List<T>	list(Session session, java.util.ArrayList<RowStructure> rowStructures) Returns a list of rows of type <T> by executing the query against the SQL server.
<T> java.util.List<T>	list(Session session, java.util.ArrayList<RowStructure> rowStructures, boolean hydrateRecords) Returns a list of rows of type <T> by executing the query against the SQL server.
private void	reportSQLWarnings(Session session) Report SQLWarnings raised by UDFs.
void	resetErrorHandler(Session session) Reset error handler at the database side.
<T> ScrollableResults<T>	scroll(Session session, java.util.ArrayList<RowStructure> rowStructure) Returns a scrollable list of rows of type <T> by executing the query against the database server.
<T> ScrollableResults<T>	scroll(Session session, int scrollMode, java.util.ArrayList<RowStructure> rowStructure) Executes the query against the SQL server.
void	setParameter(int index, java.lang.Object arg) Sets the value of a parameter for this query.
private void	setParameter(java.sql.PreparedStatement stmt, java.util.concurrent.atomic.AtomicInteger pos, java.lang.Object val, boolean forUpdate) Sets the value for a parameter at a specified position in a statement.
private void	setParameters(java.sql.PreparedStatement stmt, boolean forUpdate) Copy the set of parameters temporarily stored in this object to the PreparedStatement.
private void	setSessionVar(java.sql.Connection conn, java.util.concurrent.atomic.AtomicInteger pos, java.lang.Object val) Sets the value for a parameter as a session variable.
private void	setSessionVars(java.sql.Connection conn) Copy the set of parameters temporarily stored in this object to the session variables.
<T> T	uniqueResult(Session session) Returns an unique row of type <T> by executing the query against the SQL server.
<T> T	uniqueResult(Session session, RowStructure rowStructure) Returns an unique row of type <T> by executing the query against the SQL server.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LOG

private static final CentralLogger LOG

Logger

fine

private static final boolean fine

Flag indicating fine logging.

HYDRATE_RECORD

private static final NanoTimer HYDRATE_RECORD

Instrumentation for hydrateRecord(java.sql.ResultSet, com.goldencode.p2j.persist.orm.RowStructure, int, com.goldencode.p2j.persist.orm.Session).

CFG_FETCH_SIZE

private static final java.lang.String CFG_FETCH_SIZE

Directory path for fetch size override

See Also:

Constant Field Values

DEFAULT_FETCH_SIZE

private static final int DEFAULT_FETCH_SIZE

Default JDBC fetch size (may be overridden by runtime configuration)

See Also:

Constant Field Values

fetchSize

private static final int fetchSize

JDBC fetch size (same for all databases)

SIMPLE_QUERY_PROFILER

private static final QueryProfilerJMX SIMPLE_QUERY_PROFILER

Profiler done for queries: cache hits, cache misses, etc.

baseSql

private final java.lang.String baseSql

The SQL statement, possibly with placeholders.

sql

private java.lang.String sql

The SQL statement to be executed.

parPerm

private int[] parPerm

The parameter permutations.

sessionAttrs

private final java.util.List<FQLPreprocessor.SessionAttr> sessionAttrs

Mutable session attributes' values used in the query.

containsErrorHandling

private boolean containsErrorHandling

Flag indicating that the query contains error handling

stmt

private java.sql.PreparedStatement stmt

The PreparedStatement.

parameters

private java.lang.Object[] parameters

The current list of positional parameters.

maxParamIndex

private int maxParamIndex

The higher index of the parameter set.

canRaiseSqlWarning

private boolean canRaiseSqlWarning

Flag indicating that the query can raise SQLWarning.

bindParam2SessionVar

private boolean bindParam2SessionVar

Flags that query bind parameters should be mapped to session variables

Constructor Detail

SQLQuery

public SQLQuery(java.lang.String sql,
                java.util.List<FQLPreprocessor.SessionAttr> sessionAttrs,
                int[] parPerm)

Constructs a new object.

Parameters:

sql - The statement to be executed.

sessionAttrs - Mutable session attributes' values used in the query.

parPerm - The permutation function, if any available.

SQLQuery

public SQLQuery(java.lang.String sql)

Constructs a new object.

Parameters:

sql - The statement to be executed.

Method Detail

containsErrorHandling

public SQLQuery containsErrorHandling(boolean value)

Set the value of the flag indicating that the query contains error handling.

Parameters:

value - The new value of the flag;

Returns:

this

canRaiseSqlWarning

public boolean canRaiseSqlWarning()

Checks if the query can raise SQLWarning.

Returns:

true if the query can raise SQLWarning.

canRaiseSqlWarning

public SQLQuery canRaiseSqlWarning(boolean canRaiseSqlWarning)

Set the flag indicating if the query can raise SQLWarning.

Parameters:

canRaiseSqlWarning - The value of the flag

Returns:

this

bindParam2SessionVar

public boolean bindParam2SessionVar()

Check if the query bind parameters should be mapped to session variables.

Returns:

true if the query parameters should be mapped to session variabales.

bindParam2SessionVar

public SQLQuery bindParam2SessionVar(boolean bindParam2SessionVar)

Set the flag indicating if the query can bind parameters should be mapped to session variables.

Parameters:

bindParam2SessionVar - The value of the flag

Returns:

this

expandPlaceholders

public SQLQuery expandPlaceholders(Dialect dialect)

Expand placeholder.

Parameters:

dialect - Database dialect

Returns:

Current SQLQuery instance;

setParameter

public void setParameter(int index,
                         java.lang.Object arg)

Sets the value of a parameter for this query. The parameters are accumulated and the index is preserved so a parameter can be overwrite at any moment. Once the query is executed the parameters are set, for the eventual missing ones null value will be used. At that time, the index of parameters will be shifted to 1-based JDBC standard.

Parameters:

index - The index of the parameter to be set (0-base).

arg - The parameter value.

scroll

public <T> ScrollableResults<T> scroll(Session session,
                                       int scrollMode,
                                       java.util.ArrayList<RowStructure> rowStructure)
                                throws PersistenceException

Executes the query against the SQL server.

Type Parameters:

T - The type of the rows returned in the list.

Parameters:

session - The Session to be used.

scrollMode - The scroll mode.

rowStructure - The expected structure of a query, as generated by the FqlToSqlConverter.

Returns:

A scrollable list of rows of type <T> from the database server, as specified by the sql query.

Throws:

PersistenceException - when an error occurred while performing the requested operations.

scroll

public <T> ScrollableResults<T> scroll(Session session,
                                       java.util.ArrayList<RowStructure> rowStructure)
                                throws PersistenceException

Returns a scrollable list of rows of type <T> by executing the query against the database server.

Type Parameters:

T - The type of the rows returned in the list.

Parameters:

session - The Session to be used.

rowStructure - The expected structure of a query, as generated by the FqlToSqlConverter.

Returns:

A scrollable list of rows of type <T> from SQL server, as specified by the sql query.

Throws:

PersistenceException - when an error occurred while performing the requested operations.

uniqueResult

public <T> T uniqueResult(Session session)
                   throws PersistenceException

Returns an unique row of type <T> by executing the query against the SQL server. The result may be either a scalar value, but also can be a full Record object.

Type Parameters:

T - The type of the row to be returned.

Parameters:

session - The Session to be used.

Returns:

An object of type <T> from SQL server, as specified by the sql query.

Throws:

PersistenceException - when an error occurred while performing the requested operations.

uniqueResult

public <T> T uniqueResult(Session session,
                          RowStructure rowStructure)
                   throws PersistenceException

Returns an unique row of type <T> by executing the query against the SQL server. The result may be either a scalar value, but also can be a full Record object.

Type Parameters:

T - The type of the row to be returned.

Parameters:

session - The Session to be used.

rowStructure - The holder for dmo type and row size of the query. The row size of the query, as generated by the FqlToSqlConverter is usually 1 if a single/plain result is expected, but it can be larger if a full Record object is expected to be returned. The dmo Class of the expected object is used hydration of row.

Returns:

An object of type <T> from SQL server, as specified by the sql query.

Throws:

PersistenceException - when an error occurred while performing the requested operations.

executeUpdate

public int executeUpdate(Session session)
                  throws PersistenceException

Execute the update SQL query. When finished with success returns the number of affected columns.

Parameters:

session - The Session whose database Connection to be used.

Returns:

The number of affected rows by the statement.

Throws:

PersistenceException - when an error occurred while performing the requested operations.

list

public <T> java.util.List<T> list(Session session,
                                  java.util.ArrayList<RowStructure> rowStructures)
                           throws PersistenceException

Returns a list of rows of type <T> by executing the query against the SQL server. The method will always attempt to return a list containing a set of hydrated Record objects, if possible. In the case of projections, the list will contain only the PKs (recid/id) of the records, being the responsibility of teh caller to hydrate with subsequent queries only the desired records (aka fetch the full Record using the Loader of the Persistence).

Type Parameters:

T - The type of the rows returned in the list.

Parameters:

session - The Session to be used.

rowStructures - The expected structure of a query, as generated by the FqlToSqlConverter.

Returns:

A list of rows of type <T> from SQL server, as specified by the sql query.

Throws:

PersistenceException - when an error occurred while performing the requested operations.

list

public <T> java.util.List<T> list(Session session,
                                  java.util.ArrayList<RowStructure> rowStructures,
                                  boolean hydrateRecords)
                           throws PersistenceException

Returns a list of rows of type <T> by executing the query against the SQL server. Depending on the value of teh last parameter, the returned list is composed either from Record / PKs (recid/id) as described in the overloaded method above (when hydrateRecords is true), or plain Java wrappers (driver specific, which includes: Integer, String, BigDecimal, etc.), otherwise.

Type Parameters:

T - The type of the rows returned in the list.

Parameters:

session - The Session to be used.

rowStructures - The expected structure of a query, as generated by the FqlToSqlConverter.

hydrateRecords - If true the result is interpreted as legacy records and will be hydrated. Otherwise, the returned List contains an array for each row.

Returns:

A list of rows of type <T> from SQL server, as specified by the sql query.

Throws:

PersistenceException - when an error occurred while performing the requested operations.

reportSQLWarnings

private void reportSQLWarnings(Session session)
                        throws java.sql.SQLException

Report SQLWarnings raised by UDFs.

Parameters:

session - database session.

Throws:

java.sql.SQLException - on error in the database layer.

hydrateRecord

static BaseRecord hydrateRecord(java.sql.ResultSet resultSet,
                                RowStructure rowStructure,
                                int rsOffset,
                                Session session)
                         throws PersistenceException

Hydrate a Record from a ResultSet, ie a new object that implements the DMO interface and having the properties set from the current row of the record set. The method takes care of all the DMO properties, record identifier, and including the special properties of the temp-tables (_multiplex, before table flags).

Parameters:

resultSet - The data source. Contain the result of a query with the "main" properties. The extent properties are queried and hydrated before the record object is returned.

rowStructure - The holder for the DMO of the object to be returned and the expected number of properties of this object, as the select query was constructed. This governs the order and the types of the fields and the number of columns used for each one.

rsOffset - The offset in the ResultSet's row where the hydration process begins (in case when multiple objects are queried at once).

session - The Session to be used.

Returns:

The re-hydrated object.

Throws:

PersistenceException - When an issue was encountered in the process.

getRecordPrimaryKey

static java.lang.Long getRecordPrimaryKey(java.sql.ResultSet resultSet,
                                          RowStructure rowStructure,
                                          int rsOffset)
                                   throws PersistenceException

Get the primary key of a Record from a ResultSet.

Parameters:

resultSet - The data source. Contain the result of a query with the "main" properties.

rowStructure - The holder for the DMO of the object to be returned and the expected number of properties of this object, as the select query was constructed. This governs the order and the types of the fields and the number of columns used for each one.

rsOffset - The offset in the ResultSet's row where the primary key should begin (in case when multiple objects are queried at once).

Returns:

The objects primary key.

Throws:

PersistenceException - When an issue was encountered in the process.

hydrateRecordImpl

private static BaseRecord hydrateRecordImpl(java.sql.ResultSet resultSet,
                                            RowStructure rowStructure,
                                            int rsOffset,
                                            Session session)
                                     throws PersistenceException

Hydrate a Record from a ResultSet, ie a new object that implements the DMO interface and having the properties set from the current row of the record set. The method takes care of all the DMO properties, record identifier, and including the special properties of the temp-tables (_multiplex, before table flags).

Parameters:

resultSet - The data source. Contain the result of a query with the "main" properties. The extent properties are queried and hydrated before the record object is returned.

rowStructure - The holder for the DMO of the object to be returned and the expected number of properties of this object, as the select query was constructed. This governs the order and the types of the fields and the number of columns used for each one.

rsOffset - The offset in the ResultSet's row where the hydration process begins (in case when multiple objects are queried at once).

session - The Session to be used.

Returns:

The re-hydrated object.

Throws:

PersistenceException - When an issue was encountered in the process.

close

private void close()

Closes this object by releasing all acquired resources.

ensureSize

private void ensureSize(int fitIndex)

Makes sure the array that holds the parameters for this query is large enough to accommodate the fitIndex-th parameter. If the index fits the current size nothing is performed. Otherwise, the array is reallocated and the existing parameters are copied to their fixed positions. To improve performance, more space may be allocated so that this operation will not happen at each method call.

Parameters:

fitIndex - The index of the latest added parameter.

setParameters

private void setParameters(java.sql.PreparedStatement stmt,
                           boolean forUpdate)
                    throws java.sql.SQLException

Copy the set of parameters temporarily stored in this object to the PreparedStatement.

Parameters:

stmt - The statement to be processed.

forUpdate - true if the parameter in the statement is used to update a field and false if it is used as part of the where predicate.

Throws:

java.sql.SQLException - If an error occurred in the process.

setSessionVars

private void setSessionVars(java.sql.Connection conn)
                     throws java.sql.SQLException

Copy the set of parameters temporarily stored in this object to the session variables.

Parameters:

conn - The database connection.

Throws:

java.sql.SQLException - If an error occurred in the process.

activateErrorHandler

private void activateErrorHandler(Session session)
                           throws java.sql.SQLException,
                                  PersistenceException

Activate error handler at the database side.

Parameters:

session - Database session

Throws:

java.sql.SQLException - on error.

PersistenceException - on error.

resetErrorHandler

public void resetErrorHandler(Session session)
                       throws PersistenceException

Reset error handler at the database side.

Parameters:

session - Database session

Throws:

java.sql.SQLException - on error.

PersistenceException - on error.

setParameter

private void setParameter(java.sql.PreparedStatement stmt,
                          java.util.concurrent.atomic.AtomicInteger pos,
                          java.lang.Object val,
                          boolean forUpdate)
                   throws java.sql.SQLException

Sets the value for a parameter at a specified position in a statement. The process is done in recursive manner for arrays and Lists. The pos is incremented automatically for each scalar parameter configured.

Parameters:

stmt - The statement.

pos - The start position.

val - The value

forUpdate - true if the parameter in the statement is used to update a field and false if it is used as part of the where predicate.

Throws:

java.sql.SQLException - If an error occurred in the process.

setSessionVar

private void setSessionVar(java.sql.Connection conn,
                           java.util.concurrent.atomic.AtomicInteger pos,
                           java.lang.Object val)
                    throws java.sql.SQLException

Sets the value for a parameter as a session variable. The process is done in recursive manner for arrays and Lists. The pos is incremented automatically for each scalar parameter configured.

Parameters:

conn - Database connection.

pos - The start position.

val - The value

Throws:

java.sql.SQLException - If an error occurred in the process.

checkClosed

private static void checkClosed(java.sql.Connection conn)
                         throws PersistenceException

Test whether the connection is alive (not closed). If the connection is usable the method returns without any side-effects. If the session is not usable, PersistenceException is thrown.

Parameters:

conn - The database Connection to be used.

Throws:

PersistenceException - when the connection is not usable because it was closed.