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 the meta statements file statements.qry there's the next definition:

 ALL_PEOPLE(QRY)=
   select ID @id, NAME @name
   from PERSON
   {= where
    {& id=:id}
    {& UPPER(name)=:+name}
   }
   {#1 order by ID}
   {#2 order by NAME}
 ;
 

In the case of SQL Processor initialization

 JdbcEngineFactory sqlFactory = new JdbcEngineFactory();
 sqlFactory.setMetaFilesNames("statements.qry"); // the meta statements file
 SqlQueryEngine sqlEngine = sqlFactory.getQueryEngine("ALL_PEOPLE");
 
 // for the case it runs on the top of the JDBC stack
 Connection connection = DriverManager.getConnection("jdbc:hsqldb:mem:sqlproc", "sa", "");
 SqlSession session = new JdbcSimpleSession(connection);
 

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 Tutorials.

Author:

Vladimir Hudec

Field Summary

static SqlOrder	ASC_ORDER The ordering directive list with one ascending 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

features, logger, mapping, monitor, name, statement, typeFactory

Constructor Summary

SqlQueryEngine(String name, SqlMetaStatement statement, SqlMappingRule mapping, SqlMonitor monitor, Map<String,Object> features, SqlTypeFactory typeFactory)
Creates a new instance of the SqlQueryEngine from one META SQL statement and one SQL mapping rule instances.

SqlQueryEngine(String name, SqlMetaStatement statement, SqlMappingRule mapping, SqlTypeFactory typeFactory)
Creates a new instance of the SqlQueryEngine from one META SQL statement and one SQL mapping rule instances.

SqlQueryEngine(String name, String statement, String mapping, SqlMonitor monitor, Map<String,Object> features, SqlTypeFactory typeFactory)
Creates a new instance of the SqlQueryEngine from one META SQL statement string and one SQL Mapping rule string.

SqlQueryEngine(String name, String statement, String mapping, SqlTypeFactory typeFactory)
Creates a new instance of the SqlQueryEngine from one META SQL query string and one SQL mapping rule string.

Method Summary

private String	countSql(SqlProcessResult processResult)
SqlMonitor	getMonitor() Returns the SQL Monitor instance for the runtime statistics gathering.
String	getName() Returns the name of this META SQL, which uniquely identifies this instance.
String	getSql(Object dynamicInputValues, 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> List<E>	query(SqlSession session, Class<E> resultClass) Runs the META SQL query to obtain a list of database rows.
<E> List<E>	query(SqlSession session, Class<E> resultClass, Object dynamicInputValues) Runs the META SQL query to obtain a list of database rows.
<E> List<E>	query(SqlSession session, Class<E> resultClass, Object dynamicInputValues, int firstResult, int maxResults) Runs the META SQL query to obtain a list of database rows.
<E> List<E>	query(SqlSession session, Class<E> resultClass, Object dynamicInputValues, Object staticInputValues) Runs the META SQL query to obtain a list of database rows.
<E> List<E>	query(SqlSession session, Class<E> resultClass, Object dynamicInputValues, Object staticInputValues, int firstResult, int maxResults) Runs the META SQL query to obtain a list of database rows.
<E> List<E>	query(SqlSession session, Class<E> resultClass, Object dynamicInputValues, Object staticInputValues, Map<String,Class<?>> moreResultClasses) Runs the META SQL query to obtain a list of database rows.
<E> List<E>	query(SqlSession session, Class<E> resultClass, Object dynamicInputValues, Object staticInputValues, SqlOrder order) Runs the META SQL query to obtain a list of database rows.
<E> List<E>	query(SqlSession session, Class<E> resultClass, Object dynamicInputValues, Object staticInputValues, SqlOrder order, int maxTimeout, int maxResults, int firstResult) Runs the META SQL query to obtain a list of database rows.
<E> List<E>	query(SqlSession session, Class<E> resultClass, Object dynamicInputValues, Object staticInputValues, SqlOrder order, int maxTimeout, int maxResults, int firstResult, Map<String,Class<?>> moreResultClasses) Runs the META SQL query to obtain a list of database rows.
<E> List<E>	query(SqlSession session, Class<E> resultClass, Object dynamicInputValues, Object staticInputValues, SqlOrder order, Map<String,Class<?>> moreResultClasses) Runs the META SQL query to obtain a list of database rows.
<E> List<E>	query(SqlSession session, Class<E> resultClass, Object dynamicInputValues, SqlOrder order) Runs the META SQL query to obtain a list of database rows.
int	queryCount(SqlSession session) Runs the META SQL query to obtain the number of database rows.
int	queryCount(SqlSession session, Object dynamicInputValues) Runs the META SQL query to obtain the number of database rows.
int	queryCount(SqlSession session, Object dynamicInputValues, Object staticInputValues) Runs the META SQL query to obtain the number of database rows.
int	queryCount(SqlSession session, Object dynamicInputValues, Object staticInputValues, SqlOrder order, int maxTimeout) Runs META SQL query to 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 ascending ordering rule.

DESC_ORDER

public static final SqlOrder DESC_ORDER

The ordering directive list with one descending ordering rule.

Constructor Detail

SqlQueryEngine

public SqlQueryEngine(String name,
                      String statement,
                      String mapping,
                      SqlTypeFactory typeFactory)
               throws SqlEngineException

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

Parameters:

name - the name of this SQL Engine instance

statement - the META SQL query statement

mapping - the SQL mapping rule

typeFactory - the factory for the META types construction

Throws:

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

SqlQueryEngine

public SqlQueryEngine(String name,
                      String statement,
                      String mapping,
                      SqlMonitor monitor,
                      Map<String,Object> features,
                      SqlTypeFactory typeFactory)
               throws SqlEngineException

Creates a new instance of the 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 rule instances construction. Compared to the previous constructor, an external SQL Monitor for the runtime statistics gathering is engaged and the optional features can be involved. This constructor is devoted to manual META SQL queries and mapping rules construction. More obvious is to put these definitions into the meta statements file and engage the SqlProcessorLoader or SqlEngineLoader for the SqlQueryEngine instances construction.

Parameters:

name - the name of this SQL Engine instance

statement - the META SQL query statement

mapping - the SQL mapping rule

monitor - the SQL Monitor for the runtime statistics gathering

features - the optional SQL Processor features

typeFactory - the factory for the META types construction

Throws:

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

SqlQueryEngine

public SqlQueryEngine(String name,
                      SqlMetaStatement statement,
                      SqlMappingRule mapping,
                      SqlTypeFactory typeFactory)

Creates a new instance of the SqlQueryEngine from one META SQL statement and one SQL mapping rule instances. Both parameters are already pre-compiled 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 statements and mapping rules definitions from an external meta statements file and create the named SqlQueryEngine instances.

Parameters:

name - the name of this SQL Engine instance

statement - the pre-compiled META SQL query statement

mapping - the pre-compiled SQL mapping rule

typeFactory - the factory for the META types construction

SqlQueryEngine

public SqlQueryEngine(String name,
                      SqlMetaStatement statement,
                      SqlMappingRule mapping,
                      SqlMonitor monitor,
                      Map<String,Object> features,
                      SqlTypeFactory typeFactory)

Creates a new instance of the SqlQueryEngine from one META SQL statement and one SQL mapping rule instances. Both parameters are already pre-compiled 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 statements and mapping rules definitions from an external meta statements file and create the named instances. Compared to the previous constructor, an external SQL Monitor for the runtime statistics gathering is engaged and the optional features can be involved.

Parameters:

name - the name of this SQL Engine instance

statement - the pre-compiled META SQL query statement

mapping - the pre-compiled SQL mapping rule

monitor - the SQL Monitor for the runtime statistics gathering

features - the optional SQL Processor features

typeFactory - the factory for the META types construction

Method Detail

query

public <E> List<E> query(SqlSession session,
                         Class<E> resultClass)
              throws SqlProcessorException,
                     SqlRuntimeException

Runs the META SQL query to 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(SqlSession, Class, Object, Object, SqlOrder, int, int, int, Map) .

Throws:

SqlProcessorException

SqlRuntimeException

query

public <E> List<E> query(SqlSession session,
                         Class<E> resultClass,
                         Object dynamicInputValues)
              throws SqlProcessorException,
                     SqlRuntimeException

Runs the META SQL query to 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(SqlSession, Class, Object, Object, SqlOrder, int, int, int, Map) .

Throws:

SqlProcessorException

SqlRuntimeException

query

public <E> List<E> query(SqlSession session,
                         Class<E> resultClass,
                         Object dynamicInputValues,
                         SqlOrder order)
              throws SqlProcessorException,
                     SqlRuntimeException

Runs the META SQL query to 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(SqlSession, Class, Object, Object, SqlOrder, int, int, int, Map) .

Throws:

SqlProcessorException

SqlRuntimeException

query

public <E> List<E> query(SqlSession session,
                         Class<E> resultClass,
                         Object dynamicInputValues,
                         Object staticInputValues)
              throws SqlProcessorException,
                     SqlRuntimeException

Runs the META SQL query to 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(SqlSession, Class, Object, Object, SqlOrder, int, int, int, Map) .

Throws:

SqlProcessorException

SqlRuntimeException

query

public <E> List<E> query(SqlSession session,
                         Class<E> resultClass,
                         Object dynamicInputValues,
                         Object staticInputValues,
                         Map<String,Class<?>> moreResultClasses)
              throws SqlProcessorException,
                     SqlRuntimeException

Runs the META SQL query to 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(SqlSession, Class, Object, Object, SqlOrder, int, int, int, Map) .

Throws:

SqlProcessorException

SqlRuntimeException

query

public <E> List<E> query(SqlSession session,
                         Class<E> resultClass,
                         Object dynamicInputValues,
                         Object staticInputValues,
                         SqlOrder order)
              throws SqlProcessorException,
                     SqlRuntimeException

Runs the META SQL query to 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(SqlSession, Class, Object, Object, SqlOrder, int, int, int, Map) .

Throws:

SqlProcessorException

SqlRuntimeException

query

public <E> List<E> query(SqlSession session,
                         Class<E> resultClass,
                         Object dynamicInputValues,
                         Object staticInputValues,
                         SqlOrder order,
                         Map<String,Class<?>> moreResultClasses)
              throws SqlProcessorException,
                     SqlRuntimeException

Runs the META SQL query to 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(SqlSession, Class, Object, Object, SqlOrder, int, int, int, Map) .

Throws:

SqlProcessorException

SqlRuntimeException

query

public <E> List<E> query(SqlSession session,
                         Class<E> resultClass,
                         Object dynamicInputValues,
                         int firstResult,
                         int maxResults)
              throws SqlProcessorException,
                     SqlRuntimeException

Runs the META SQL query to 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(SqlSession, Class, Object, Object, SqlOrder, int, int, int, Map) .

Throws:

SqlProcessorException

SqlRuntimeException

query

public <E> List<E> query(SqlSession session,
                         Class<E> resultClass,
                         Object dynamicInputValues,
                         Object staticInputValues,
                         int firstResult,
                         int maxResults)
              throws SqlProcessorException,
                     SqlRuntimeException

Runs the META SQL query to 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(SqlSession, Class, Object, Object, SqlOrder, int, int, int, Map) .

Throws:

SqlProcessorException

SqlRuntimeException

query

public <E> List<E> query(SqlSession session,
                         Class<E> resultClass,
                         Object dynamicInputValues,
                         Object staticInputValues,
                         SqlOrder order,
                         int maxTimeout,
                         int maxResults,
                         int firstResult)
              throws SqlProcessorException,
                     SqlRuntimeException

Runs the META SQL query to 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(SqlSession, Class, Object, Object, SqlOrder, int, int, int, Map) .

Throws:

SqlProcessorException

SqlRuntimeException

query

public <E> List<E> query(SqlSession session,
                         Class<E> resultClass,
                         Object dynamicInputValues,
                         Object staticInputValues,
                         SqlOrder order,
                         int maxTimeout,
                         int maxResults,
                         int firstResult,
                         Map<String,Class<?>> moreResultClasses)
              throws SqlProcessorException,
                     SqlRuntimeException

Runs the META SQL query to 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 the input values.

Parameters:

session - The SQL Engine session. It can work as a first level cache and the SQL query execution context. The implementation depends on the stack, on top of which the SQL Processor works. For example it can be an Hibernate session.

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 process of query execution using the reflection API.

dynamicInputValues - The object used for the SQL statement dynamic input values. 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 settled into the SQL prepared statement are picked up using the reflection API.

staticInputValues - The object used for the SQL statement static input values. 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 an 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 in 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 the one-to-one, one-to-many and many-to-many associations.

Returns:

The list of the resultClass instances.

Throws:

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

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

SqlProcessorException

queryCount

public int queryCount(SqlSession session)
               throws SqlProcessorException,
                      SqlRuntimeException

Runs the META SQL query to 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(SqlSession, Object, Object, SqlOrder, int) .

Throws:

SqlProcessorException

SqlRuntimeException

queryCount

public int queryCount(SqlSession session,
                      Object dynamicInputValues)
               throws SqlProcessorException,
                      SqlRuntimeException

Runs the META SQL query to 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(SqlSession, Object, Object, SqlOrder, int) .

Throws:

SqlProcessorException

SqlRuntimeException

queryCount

public int queryCount(SqlSession session,
                      Object dynamicInputValues,
                      Object staticInputValues)
               throws SqlProcessorException,
                      SqlRuntimeException

Runs the META SQL query to 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(SqlSession, Object, Object, SqlOrder, int) .

Throws:

SqlProcessorException

SqlRuntimeException

queryCount

public int queryCount(SqlSession session,
                      Object dynamicInputValues,
                      Object staticInputValues,
                      SqlOrder order,
                      int maxTimeout)
               throws SqlProcessorException,
                      SqlRuntimeException

Runs META SQL query to 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 the input values. The primary usage is to support the pagination.

Parameters:

session - The SQL Engine session. It can work as a first level cache and the SQL query execution context. The implementation depends on the stack, on top of which the SQL Processor works. For example it can be an Hibernate session.

dynamicInputValues - The object used for the SQL statement dynamic input values. 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 settled into the SQL prepared statement are picked up using the reflection API.

staticInputValues - The object used for the SQL statement static input values. 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 an 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.SqlProcessorException - in the case of any problem with ORM or JDBC stack stack

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

SqlProcessorException

countSql

private String countSql(SqlProcessResult processResult)

getSql

public String getSql(Object dynamicInputValues,
                     Object staticInputValues,
                     SqlOrder order)
              throws SqlProcessorException,
                     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 generated in the background of the SQL Processor execution. The query is derived from the META SQL query.

Parameters:

dynamicInputValues - The object used for the SQL statement dynamic input values. 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 settled into the SQL prepared statement are picked up using the reflection API.

staticInputValues - The object used for the SQL statement static input values. 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 an 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 query based on the input parameters.

Throws:

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

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

SqlProcessorException

getName

public String getName()

Returns the name of this META SQL, which uniquely identifies this instance. In the case the META SQL query and mapping rule are located in the meta statements file, this name is the unique part of the keys in this file. For example for the name ALL in the meta statements file there's the META SQL query with the name ALL(QRY) and the mapping rule with the name ALL(OUT).

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.