org.sqlproc.engine
Class SqlQueryEngine

java.lang.Object
  org.sqlproc.engine.SqlEngine
      org.sqlproc.engine.SqlQueryEngine

public class SqlQueryEngine
extends SqlEngine

The primary SQL Processor class for the META SQL query execution.

Instance of this class holds one META SQL query and one optional Mapping rule.

For example there's a table PERSON with two columns - ID and NAME.
In queries.properties there's the next definition:

 QRY_ALL_PEOPLE= \
   select p.ID @id, p.NAME @name \
   from PERSON p \
   {= where \
    {& id=:id} \
    {& UPPER(name)=:+name} \
   } \
   {#1 order by ID} \
   {#2 order by NAME}
 

In the case of SQL Processor initialization

 SqlPropertiesLoader loader = new SqlPropertiesLoader("queries.properties", this.getClass());
 SqlEngineLoader sqlLoader = new SqlEngineLoader(loader.getProperties());
 SqlQueryEngine sqlEngine = sqlLoader.getQueryEngine("ALL_PEOPLE");
 

there's created an instance of SqlQueryEngine with the name ALL_PEOPLE.

Next the query can be executed with one of the queryXXX methods. For example there's a Java bean class Person with attributes id and name. The invocation

 List<Person> list = sqlEngine.query(session, Person.class, null, SqlQueryEngine.ASC_ORDER);
 

produces the next SQL execution

 select p.ID id, p.NAME name from PERSON p order by ID ASC
 

Next there's an instance person of the class Person with the value Jan for the attribute name. The invocation

 List<Person> list = sqlEngine.query(session, Person.class, person, SqlOrder.getDescOrder(2));
 

produces the next SQL execution

 select p.ID id, p.NAME name from PERSON p where UPPER(name)=? order by NAME DESC
 

For more info please see the Reference Guide or tutorials.

Author:

Vladimir Hudec

Field Summary

static SqlOrder	ASC_ORDER The ordering directive list with one asscending ordering rule.
static SqlOrder	DESC_ORDER the ordering directive list with one descending ordering rule.
static SqlOrder	NO_ORDER The ordering directive list with no ordering rule.

Fields inherited from class org.sqlproc.engine.SqlEngine

classToTypeMap, features, logger, mapping, monitor, name, statement

Constructor Summary

SqlQueryEngine(java.lang.String name, SqlMetaStatement statement, SqlMappingRule mapping)
Creates a new instance of SqlQueryEngine from one META SQL statement and one SQL Mapping rule instance.

SqlQueryEngine(java.lang.String name, SqlMetaStatement statement, SqlMappingRule mapping, SqlMonitor monitor, java.util.Map<java.lang.String,java.lang.Object> features, java.util.Map<java.lang.Class<?>,SqlMetaType> classToTypeMap)
Creates a new instance of SqlQueryEngine from one META SQL statement and one SQL Mapping rule instance.

SqlQueryEngine(java.lang.String name, java.lang.String statement, java.lang.String mapping)
Creates a new instance of SqlQueryEngine from one META SQL statement string and one SQL Mapping rule string.

SqlQueryEngine(java.lang.String name, java.lang.String statement, java.lang.String mapping, SqlMonitor monitor, java.util.Map<java.lang.String,java.lang.Object> features, java.util.Map<java.lang.Class<?>,SqlMetaType> classToTypeMap)
Creates a new instance of SqlQueryEngine from one META SQL statement string and one SQL Mapping rule string.

Method Summary

private java.lang.String	countSql(SqlProcessResult processResult)
SqlMonitor	getMonitor() Returns the SQL Monitor instance for the runtime statistics gathering.
java.lang.String	getName() Returns the name of this META SQL, which uniquely identifies the instance.
java.lang.String	getSql(java.lang.Object dynamicInputValues, java.lang.Object staticInputValues, SqlOrder order) Because the SQL Processor is Data Driven Query engine, every input parameters can produce in fact different SQL query command.
<E> java.util.List<E>	query(org.hibernate.Session session, java.lang.Class<E> resultClass) Runs META SQL query statement obtain a list of database rows.
<E> java.util.List<E>	query(org.hibernate.Session session, java.lang.Class<E> resultClass, java.lang.Object dynamicInputValues) Runs META SQL query statement obtain a list of database rows.
<E> java.util.List<E>	query(org.hibernate.Session session, java.lang.Class<E> resultClass, java.lang.Object dynamicInputValues, int firstResult, int maxResults) Runs META SQL query statement obtain a list of database rows.
<E> java.util.List<E>	query(org.hibernate.Session session, java.lang.Class<E> resultClass, java.lang.Object dynamicInputValues, java.lang.Object staticInputValues) Runs META SQL query statement obtain a list of database rows.
<E> java.util.List<E>	query(org.hibernate.Session session, java.lang.Class<E> resultClass, java.lang.Object dynamicInputValues, java.lang.Object staticInputValues, int firstResult, int maxResults) Runs META SQL query statement obtain a list of database rows.
<E> java.util.List<E>	query(org.hibernate.Session session, java.lang.Class<E> resultClass, java.lang.Object dynamicInputValues, java.lang.Object staticInputValues, java.util.Map<java.lang.String,java.lang.Class<?>> moreResultClasses) Runs META SQL query statement obtain a list of database rows.
<E> java.util.List<E>	query(org.hibernate.Session session, java.lang.Class<E> resultClass, java.lang.Object dynamicInputValues, java.lang.Object staticInputValues, SqlOrder order) Runs META SQL query statement obtain a list of database rows.
<E> java.util.List<E>	query(org.hibernate.Session session, java.lang.Class<E> resultClass, java.lang.Object dynamicInputValues, java.lang.Object staticInputValues, SqlOrder order, int maxTimeout, int maxResults, int firstResult) Runs META SQL query statement obtain a list of database rows.
<E> java.util.List<E>	query(org.hibernate.Session session, java.lang.Class<E> resultClass, java.lang.Object dynamicInputValues, java.lang.Object staticInputValues, SqlOrder order, int maxTimeout, int maxResults, int firstResult, java.util.Map<java.lang.String,java.lang.Class<?>> moreResultClasses) Runs META SQL query statement obtain a list of database rows.
<E> java.util.List<E>	query(org.hibernate.Session session, java.lang.Class<E> resultClass, java.lang.Object dynamicInputValues, java.lang.Object staticInputValues, SqlOrder order, java.util.Map<java.lang.String,java.lang.Class<?>> moreResultClasses) Runs META SQL query statement obtain a list of database rows.
<E> java.util.List<E>	query(org.hibernate.Session session, java.lang.Class<E> resultClass, java.lang.Object dynamicInputValues, SqlOrder order) Runs META SQL query statement obtain a list of database rows.
int	queryCount(org.hibernate.Session session) Runs META SQL query statement obtain the number of database rows.
int	queryCount(org.hibernate.Session session, java.lang.Object dynamicInputValues) Runs META SQL query statement obtain the number of database rows.
int	queryCount(org.hibernate.Session session, java.lang.Object dynamicInputValues, java.lang.Object staticInputValues) Runs META SQL query statement obtain the number of database rows.
int	queryCount(org.hibernate.Session session, java.lang.Object dynamicInputValues, java.lang.Object staticInputValues, SqlOrder order, int maxTimeout) Runs META SQL query statement obtain the number of database rows.

Methods inherited from class java.lang.Object

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

Field Detail

NO_ORDER

public static final SqlOrder NO_ORDER

The ordering directive list with no ordering rule.

ASC_ORDER

public static final SqlOrder ASC_ORDER

The ordering directive list with one asscending ordering rule.

DESC_ORDER

public static final SqlOrder DESC_ORDER

the ordering directive list with one descending ordering rule.

Constructor Detail

SqlQueryEngine

public SqlQueryEngine(java.lang.String name,
                      java.lang.String statement,
                      java.lang.String mapping)
               throws SqlEngineException

Creates a new instance of SqlQueryEngine from one META SQL statement string and one SQL Mapping rule string. Constructor will call the internal ANTLR parsers for the statement and the mapping instances construction. This constructor is devoted to manual META SQL statements and Mapping rules construction. More obvious is to put these definitions into queries.properties file and engage SqlEngineLoader for the SqlQueryEngine instances construction.

Parameters:

name - the name if this SQL Engine instance

statement - the META SQL query statement, extension of ANSI SQL

mapping - the SQL Mapping rule, SQL result to Java output classes mapping

Throws:

SqlEngineException - mainly in the case the provided statements are not compliant with the ANTLR grammar

SqlQueryEngine

public SqlQueryEngine(java.lang.String name,
                      java.lang.String statement,
                      java.lang.String mapping,
                      SqlMonitor monitor,
                      java.util.Map<java.lang.String,java.lang.Object> features,
                      java.util.Map<java.lang.Class<?>,SqlMetaType> classToTypeMap)
               throws SqlEngineException

Creates a new instance of SqlQueryEngine from one META SQL statement string and one SQL Mapping rule string. Constructor will call the internal ANTLR parsers for the statement and the mapping instances construction. Compared to the previous constructor, external SQL Monitor for the runtime statistics gathering is engaged. This constructor is devoted to manual META SQL statements and Mapping rules construction. More obvious is to put these statements into queries.properties file and engage SqlEngineLoader for instances construction.

Parameters:

name - the name if this SQL Engine instance

statement - the META SQL query statement, extension of ANSI SQL

mapping - the SQL Mapping rule, SQL result to Java output classes mapping

monitor - the SQL Monitor for the runtime statistics gathering

features - the optional SQL Processor features

classToTypeMap - the map between a Java class type and an internal type

Throws:

SqlEngineException - mainly in the case the provided statements are not compliant with the ANTLR grammar

SqlQueryEngine

public SqlQueryEngine(java.lang.String name,
                      SqlMetaStatement statement,
                      SqlMappingRule mapping)

Creates a new instance of SqlQueryEngine from one META SQL statement and one SQL Mapping rule instance. Both parameters are already precompiled instances using the ANTLR parsers. This is the recommended usage for the runtime performance optimization. This constructor is devoted to be used from the SqlEngineLoader, which is able to read all definitions from an external queries.properties and create the named instances.

Parameters:

name - the name if this SQL Engine instance

statement - the precompiled META SQL query statement, extension of ANSI SQL

mapping - the precompiled SQL Mapping rule, SQL result to Java output classes mapping

SqlQueryEngine

public SqlQueryEngine(java.lang.String name,
                      SqlMetaStatement statement,
                      SqlMappingRule mapping,
                      SqlMonitor monitor,
                      java.util.Map<java.lang.String,java.lang.Object> features,
                      java.util.Map<java.lang.Class<?>,SqlMetaType> classToTypeMap)

Creates a new instance of SqlQueryEngine from one META SQL statement and one SQL Mapping rule instance. Both parameters are already precompiled instances using the ANTLR parsers. This is the recommended usage for the runtime performance optimization. This constructor is devoted to be used from the SqlEngineLoader, which is able to read all definitions from an external queries.properties and create the named instances. Compared to the previous constructor, external SQL Monitor for the runtime statistics gathering is engaged.

Parameters:

name - the name if this SQL Engine instance

statement - the precompiled META SQL query statement, extension of ANSI SQL

mapping - the precompiled SQL Mapping rule, SQL result to Java output classes mapping

monitor - the SQL Monitor for the runtime statistics gathering

features - the optional SQL Processor features

classToTypeMap - the map between a Java class type and an internal type

Method Detail

query

public <E> java.util.List<E> query(org.hibernate.Session session,
                                   java.lang.Class<E> resultClass)
                        throws org.hibernate.HibernateException,
                               SqlRuntimeException

Runs META SQL query statement obtain a list of database rows. This is one of the overriden methods. For the parameters description please see the most complex execution method query(Session, Class, Object, Object, SqlOrder, int, int, int, Map) .

Throws:

org.hibernate.HibernateException

SqlRuntimeException

query

public <E> java.util.List<E> query(org.hibernate.Session session,
                                   java.lang.Class<E> resultClass,
                                   java.lang.Object dynamicInputValues)
                        throws org.hibernate.HibernateException,
                               SqlRuntimeException

Runs META SQL query statement obtain a list of database rows. This is one of the overriden methods. For the parameters description please see the most complex execution method query(Session, Class, Object, Object, SqlOrder, int, int, int, Map) .

Throws:

org.hibernate.HibernateException

SqlRuntimeException

query

public <E> java.util.List<E> query(org.hibernate.Session session,
                                   java.lang.Class<E> resultClass,
                                   java.lang.Object dynamicInputValues,
                                   SqlOrder order)
                        throws org.hibernate.HibernateException,
                               SqlRuntimeException

Runs META SQL query statement obtain a list of database rows. This is one of the overriden methods. For the parameters description please see the most complex execution method query(Session, Class, Object, Object, SqlOrder, int, int, int, Map) .

Throws:

org.hibernate.HibernateException

SqlRuntimeException

query

public <E> java.util.List<E> query(org.hibernate.Session session,
                                   java.lang.Class<E> resultClass,
                                   java.lang.Object dynamicInputValues,
                                   java.lang.Object staticInputValues)
                        throws org.hibernate.HibernateException,
                               SqlRuntimeException

Runs META SQL query statement obtain a list of database rows. This is one of the overriden methods. For the parameters description please see the most complex execution method query(Session, Class, Object, Object, SqlOrder, int, int, int, Map) .

Throws:

org.hibernate.HibernateException

SqlRuntimeException

query

public <E> java.util.List<E> query(org.hibernate.Session session,
                                   java.lang.Class<E> resultClass,
                                   java.lang.Object dynamicInputValues,
                                   java.lang.Object staticInputValues,
                                   java.util.Map<java.lang.String,java.lang.Class<?>> moreResultClasses)
                        throws org.hibernate.HibernateException,
                               SqlRuntimeException

Runs META SQL query statement obtain a list of database rows. This is one of the overriden methods. For the parameters description please see the most complex execution method query(Session, Class, Object, Object, SqlOrder, int, int, int, Map) .

Throws:

org.hibernate.HibernateException

SqlRuntimeException

query

public <E> java.util.List<E> query(org.hibernate.Session session,
                                   java.lang.Class<E> resultClass,
                                   java.lang.Object dynamicInputValues,
                                   java.lang.Object staticInputValues,
                                   SqlOrder order)
                        throws org.hibernate.HibernateException,
                               SqlRuntimeException

Runs META SQL query statement obtain a list of database rows. This is one of the overriden methods. For the parameters description please see the most complex execution method query(Session, Class, Object, Object, SqlOrder, int, int, int, Map) .

Throws:

org.hibernate.HibernateException

SqlRuntimeException

query

public <E> java.util.List<E> query(org.hibernate.Session session,
                                   java.lang.Class<E> resultClass,
                                   java.lang.Object dynamicInputValues,
                                   java.lang.Object staticInputValues,
                                   SqlOrder order,
                                   java.util.Map<java.lang.String,java.lang.Class<?>> moreResultClasses)
                        throws org.hibernate.HibernateException,
                               SqlRuntimeException

Runs META SQL query statement obtain a list of database rows. This is one of the overriden methods. For the parameters description please see the most complex execution method query(Session, Class, Object, Object, SqlOrder, int, int, int, Map) .

Throws:

org.hibernate.HibernateException

SqlRuntimeException

query

public <E> java.util.List<E> query(org.hibernate.Session session,
                                   java.lang.Class<E> resultClass,
                                   java.lang.Object dynamicInputValues,
                                   int firstResult,
                                   int maxResults)
                        throws org.hibernate.HibernateException,
                               SqlRuntimeException

Runs META SQL query statement obtain a list of database rows. This is one of the overriden methods. For the parameters description please see the most complex execution method query(Session, Class, Object, Object, SqlOrder, int, int, int, Map) .

Throws:

org.hibernate.HibernateException

SqlRuntimeException

query

public <E> java.util.List<E> query(org.hibernate.Session session,
                                   java.lang.Class<E> resultClass,
                                   java.lang.Object dynamicInputValues,
                                   java.lang.Object staticInputValues,
                                   int firstResult,
                                   int maxResults)
                        throws org.hibernate.HibernateException,
                               SqlRuntimeException

Runs META SQL query statement obtain a list of database rows. This is one of the overriden methods. For the parameters description please see the most complex execution method query(Session, Class, Object, Object, SqlOrder, int, int, int, Map) .

Throws:

org.hibernate.HibernateException

SqlRuntimeException

query

public <E> java.util.List<E> query(org.hibernate.Session session,
                                   java.lang.Class<E> resultClass,
                                   java.lang.Object dynamicInputValues,
                                   java.lang.Object staticInputValues,
                                   SqlOrder order,
                                   int maxTimeout,
                                   int maxResults,
                                   int firstResult)
                        throws org.hibernate.HibernateException,
                               SqlRuntimeException

Runs META SQL query statement obtain a list of database rows. This is one of the overriden methods. For the parameters description please see the most complex execution method query(Session, Class, Object, Object, SqlOrder, int, int, int, Map) .

Throws:

org.hibernate.HibernateException

SqlRuntimeException

query

public <E> java.util.List<E> query(org.hibernate.Session session,
                                   java.lang.Class<E> resultClass,
                                   java.lang.Object dynamicInputValues,
                                   java.lang.Object staticInputValues,
                                   SqlOrder order,
                                   int maxTimeout,
                                   int maxResults,
                                   int firstResult,
                                   java.util.Map<java.lang.String,java.lang.Class<?>> moreResultClasses)
                        throws org.hibernate.HibernateException,
                               SqlRuntimeException

Runs META SQL query statement obtain a list of database rows. This is the primary and the most complex SQL Processor execution method to obtain a list of result class instances. Criteria to pickup the correct database rows are taken from input values.

Parameters:

session - Hibernate session, first level cache and the SQL query execution context

resultClass - The class used for the return values, the SQL query execution output. This class is also named as the output class or the transport class, In fact it's a standard POJO class, which must include all the attributes described in the Mapping rule statement. This class itself and all its subclasses must have public constructors without any parameters. All the attributes used in the mapping rule statement must be accessible using public getters and setters. The instances of this class are created on the fly in the query execution using the reflection API.

dynamicInputValues - The object used for the SQL statement dynamic parameters. The class of this object is also named as the input class or the dynamic parameters class. The exact class type isn't important, all the parameters substituted into the SQL prepared statement are picked up using the reflection API.

staticInputValues - The object used for the SQL statement static parameters. The class of this object is also named as the input class or the static parameters class. The exact class type isn't important, all the parameters injected into the SQL query command are picked up using the reflection API. Compared to dynamicInputValues input parameters, parameters in this class should't be produced by the end user to prevent SQL injection threat!

order - The ordering directive list. Using the class SqlOrder the ordering rules can be chained. Every ordering rule in this chain should correspond to one META SQL Ordering statement.

maxTimeout - The max SQL execution time. This parameter can help to protect production system against ineffective SQL query commands. The value is in milliseconds.

maxResults - The max number of SQL execution output rows, which can be returned as the result list. The primary usage is to support the pagination.

firstResult - The first SQL execution output row to be returned in the case we need to skip some rows in the result set. The primary usage is to support the pagination.

moreResultClasses - More result classes used for the return values, like the collections classes or the collections items. They are used mainly for one-to-one, one-to-many and many-to-many associations.

Returns:

The list of the resultClass instances.

Throws:

org.hibernate.HibernateException - in the case of any problem with ORM or JDBC

SqlRuntimeException - in the case of any problem with input/output values handling

queryCount

public int queryCount(org.hibernate.Session session)
               throws org.hibernate.HibernateException,
                      SqlRuntimeException

Runs META SQL query statement obtain the number of database rows. This is one of the overriden methods. For the parameters description please see the most complex execution method queryCount(Session, Object, Object, SqlOrder, int) .

Throws:

org.hibernate.HibernateException

SqlRuntimeException

queryCount

public int queryCount(org.hibernate.Session session,
                      java.lang.Object dynamicInputValues)
               throws org.hibernate.HibernateException,
                      SqlRuntimeException

Runs META SQL query statement obtain the number of database rows. This is one of the overriden methods. For the parameters description please see the most complex execution method queryCount(Session, Object, Object, SqlOrder, int) .

Throws:

org.hibernate.HibernateException

SqlRuntimeException

queryCount

public int queryCount(org.hibernate.Session session,
                      java.lang.Object dynamicInputValues,
                      java.lang.Object staticInputValues)
               throws org.hibernate.HibernateException,
                      SqlRuntimeException

Runs META SQL query statement obtain the number of database rows. This is one of the overriden methods. For the parameters description please see the most complex execution method queryCount(Session, Object, Object, SqlOrder, int) .

Throws:

org.hibernate.HibernateException

SqlRuntimeException

queryCount

public int queryCount(org.hibernate.Session session,
                      java.lang.Object dynamicInputValues,
                      java.lang.Object staticInputValues,
                      SqlOrder order,
                      int maxTimeout)
               throws org.hibernate.HibernateException,
                      SqlRuntimeException

Runs META SQL query statement obtain the number of database rows. This is the primary and the most complex SQL Processor execution method to count the rows in database, which match the criteria. These criteria are taken from input values. The primary usage is to support the pagination.

Parameters:

session - Hibernate session, first level cache and the SQL query execution context

dynamicInputValues - The object used for the SQL statement dynamic parameters. The class of this object is also named as the input class or the dynamic parameters class. The exact class type isn't important, all the parameters substituted into the SQL prepared statement are picked up using the reflection API.

staticInputValues - The object used for the SQL statement static parameters. The class of this object is also named as the input class or the static parameters class. The exact class type isn't important, all the parameters injected into the SQL query command are picked up using the reflection API. Compared to dynamicInputValues input parameters, parameters in this class should't be produced by the end user to prevent SQL injection threat!

order - The ordering directive list. Using the class SqlOrder the ordering rules can be chained. Every ordering rule in this chain should correspond to one META SQL Ordering statement.

maxTimeout - The max SQL execution time. This parameter can help to protect production system against ineffective SQL query commands. The value is in milliseconds.

Returns:

The size of potential list of resultClass instances.

Throws:

org.hibernate.HibernateException - in the case of any problem with ORM or JDBC

SqlRuntimeException - in the case of any problem with input/output values handling

countSql

private java.lang.String countSql(SqlProcessResult processResult)

getSql

public java.lang.String getSql(java.lang.Object dynamicInputValues,
                               java.lang.Object staticInputValues,
                               SqlOrder order)
                        throws org.hibernate.HibernateException,
                               SqlRuntimeException

Because the SQL Processor is Data Driven Query engine, every input parameters can produce in fact different SQL query command. This method can help to identify the exact SQL query command, which is produced in the background of the SQL Processor execution. The query is derived from the META SQL statement.

Parameters:

dynamicInputValues - The object used for the SQL statement dynamic parameters. The class of this object is also named as the input class or the dynamic parameters class. The exact class type isn't important, all the parameters substituted into the SQL prepared statement are picked up using the reflection API.

staticInputValues - The object used for the SQL statement static parameters. The class of this object is also named as the input class or the static parameters class. The exact class type isn't important, all the parameters injected into the SQL query command are picked up using the reflection API. Compared to dynamicInputValues input parameters, parameters in this class should't be produced by the end user to prevent SQL injection threat!

order - The ordering directive list. Using the class SqlOrder the ordering rules can be chained. Every ordering rule in this chain should correspond to one META SQL Ordering statement.

Returns:

The SQL query command derived from the META SQL statement based in the input parameters.

Throws:

org.hibernate.HibernateException - in the case of any problem with ORM or JDBC

SqlRuntimeException - in the case of any problem with input/output values handling

getName

public java.lang.String getName()

Returns the name of this META SQL, which uniquely identifies the instance. In the case the META SQL statement and Mapping rule are located in queries.properties, this name is the unique part of the keys in this file. For example for the name ALL in queries.properties there's META SQL statement with the name QRY_ALL and Mapping rule with the name OUT_ALL.

Returns:

The name of the SQL engine instance.

getMonitor

public SqlMonitor getMonitor()

Returns the SQL Monitor instance for the runtime statistics gathering. By default no runtime statistics gathering is active. So this SQL Monitor is implied in SQL engine constructor in the case the statistics gathering should be engaged.

Returns:

The SQL Monitor instance, which is active for this SQL engine instance.