org.sqlproc.engine
Interface SqlQuery

All Known Implementing Classes:

JdbcQuery

public interface SqlQuery

The SQL Engine query contract definition. In fact it's an adapter or a proxy to an internal stuff in one of the stacks on top of which the SQL Processor works.

For the concrete implementation please see for example JdbcQuery.

For more info please see the Tutorials.

Author:

Vladimir Hudec

Method Summary

SqlQuery	addScalar(String columnAlias) Declares a scalar query result, which is an SQL query execution output value.
SqlQuery	addScalar(String columnAlias, Object type) Declares a scalar query result, which is an SQL query execution output value.
Object	callFunction() Executes the statements in the stored function, which return value of any type but the result set.
List	callList(SqlRuntimeContext runtime) Returns the stored procedure execution results as a List.
Object	callUnique(SqlRuntimeContext runtime) Convenience method to return a single instance that matches the stored procedure execution, or null if the stored procedure execution returns no results.
int	callUpdate(SqlRuntimeContext runtime) Executes the update, delete, insert statement or other statements in the stored procedure, which don't return the result set.
int[]	executeBatch(String[] statements) Submits a batch of commands to the database for execution and if all commands execute successfully, returns an array of update counts.
Object	getQuery() Returns the internal representation of this query.
List	list(SqlRuntimeContext runtime) Returns the query results as a List.
SqlQuery	setFetchSize(int fetchSize) Sets the fetch size of rows to retrieve.
SqlQuery	setFirstResult(int firstResult) Sets the first row to retrieve.
void	setLogError(boolean logError) Sets an indicator the failed SQL command should be logged
SqlQuery	setMaxResults(int maxResults) Sets the maximum number of rows to retrieve.
SqlQuery	setOrdered(boolean ordered) Sets the indicator the SQL output is sorted.
SqlQuery	setParameter(String name, Object val) Binds a value to a named query parameter.
SqlQuery	setParameter(String name, Object val, Object type) Binds a value to a named query parameter.
SqlQuery	setParameterList(String name, Object[] vals) Binds multiple values to a named query parameter.
SqlQuery	setParameterList(String name, Object[] vals, Object type) Binds multiple values to a named query parameter.
SqlQuery	setTimeout(int timeout) Sets a timeout for the underlying query.
Object	unique(SqlRuntimeContext runtime) Convenience method to return a single instance that matches the query, or null if the query returns no results.
int	update(SqlRuntimeContext runtime) Executes the update, delete or insert statement.

Method Detail

getQuery

Object getQuery()

Returns the internal representation of this query. This implementation depends on the stack on top of which the SQL Processor works. It can be for example the Hibernate SQLQuery instance.

Returns:

the internal representation of this query

setTimeout

SqlQuery setTimeout(int timeout)

Sets a timeout for the underlying query.

Parameters:

timeout - the timeout in seconds

Returns:

this instance to enable the methods chaining

setFirstResult

SqlQuery setFirstResult(int firstResult)

Sets the first row to retrieve. If not set, rows will be retrieved beginning from row 0.

Parameters:

firstResult - a row number, numbered from 0

Returns:

this instance to enable the methods chaining

setMaxResults

SqlQuery setMaxResults(int maxResults)

Sets the maximum number of rows to retrieve. If not set, there is no limit to the number of rows retrieved.

Parameters:

maxResults - the maximum number of rows

Returns:

this instance to enable the methods chaining

setFetchSize

SqlQuery setFetchSize(int fetchSize)

Sets the fetch size of rows to retrieve. If not set, there is no limit to the number of rows retrieved.

Parameters:

fetchSize - the fetch size of rows

Returns:

this instance to enable the methods chaining

setOrdered

SqlQuery setOrdered(boolean ordered)

Sets the indicator the SQL output is sorted.

Parameters:

ordered - the indicator the SQL output is sorted

Returns:

this instance to enable the methods chaining

list

List list(SqlRuntimeContext runtime)
          throws SqlProcessorException

Returns the query results as a List. If the query contains multiple results per row, the results are returned in an instance of Object[].

Parameters:

runtime - the public runtime context

Returns:

the result list

Throws:

SqlProcessorException - in the case of any problem in ORM or JDBC stack

unique

Object unique(SqlRuntimeContext runtime)
              throws SqlProcessorException

Convenience method to return a single instance that matches the query, or null if the query returns no results.

Parameters:

runtime - the public runtime context

Returns:

the single result or null

Throws:

SqlProcessorException - in the case of any problem in ORM or JDBC stack

update

int update(SqlRuntimeContext runtime)
           throws SqlProcessorException

Executes the update, delete or insert statement.

Parameters:

runtime - the public runtime context

Returns:

the number of affected rows

Throws:

SqlProcessorException - in the case of any problem in ORM or JDBC stack

callList

List callList(SqlRuntimeContext runtime)
              throws SqlProcessorException

Returns the stored procedure execution results as a List. If the query contains multiple results per row, the results are returned in an instance of Object[]. It's based on the CallableStatement invocation.

Parameters:

runtime - the public runtime context

Returns:

the result list

Throws:

SqlProcessorException - in the case of any problem in ORM or JDBC stack

callUnique

Object callUnique(SqlRuntimeContext runtime)
                  throws SqlProcessorException

Convenience method to return a single instance that matches the stored procedure execution, or null if the stored procedure execution returns no results. It's based on the CallableStatement invocation.

Parameters:

runtime - the public runtime context

Returns:

the single result or null

Throws:

SqlProcessorException - in the case of any problem in ORM or JDBC stack

callUpdate

int callUpdate(SqlRuntimeContext runtime)
               throws SqlProcessorException

Executes the update, delete, insert statement or other statements in the stored procedure, which don't return the result set. It's based on the CallableStatement invocation.

Parameters:

runtime - the public runtime context

Returns:

the number of affected rows

Throws:

SqlProcessorException - in the case of any problem in ORM or JDBC stack

callFunction

Object callFunction()
                    throws SqlProcessorException

Executes the statements in the stored function, which return value of any type but the result set. It's based on the CallableStatement invocation.

Returns:

the result of the stored function invocation

Throws:

SqlProcessorException - in the case of any problem in ORM or JDBC stack

addScalar

SqlQuery addScalar(String columnAlias)

Declares a scalar query result, which is an SQL query execution output value.

Parameters:

columnAlias - the name of the database column or the alias in the result set

Returns:

this instance to enable the methods chaining

addScalar

SqlQuery addScalar(String columnAlias,
                   Object type)

Declares a scalar query result, which is an SQL query execution output value.

Parameters:

columnAlias - the name of the database column or the alias in the result set

type - the (META) type of the parameter

Returns:

this instance to enable the methods chaining

setParameter

SqlQuery setParameter(String name,
                      Object val)
                      throws SqlProcessorException

Binds a value to a named query parameter.

Parameters:

name - the name of the parameter

val - the not-null parameter value

Returns:

this instance to enable the methods chaining

Throws:

SqlProcessorException - in the case of any problem in ORM or JDBC stack

setParameter

SqlQuery setParameter(String name,
                      Object val,
                      Object type)
                      throws SqlProcessorException

Binds a value to a named query parameter.

Parameters:

name - the name of the parameter

val - the possibly-null parameter value

type - the (META) type of the parameter

Returns:

this instance to enable the methods chaining

Throws:

SqlProcessorException - in the case of any problem in ORM or JDBC stack

setParameterList

SqlQuery setParameterList(String name,
                          Object[] vals)
                          throws SqlProcessorException

Binds multiple values to a named query parameter. This is useful for binding a list of values to the query fragment in (:value_list).

Parameters:

name - the name of the parameter

vals - a collection of values

Returns:

this instance to enable the methods chaining

Throws:

SqlProcessorException - in the case of any problem in ORM or JDBC stack

setParameterList

SqlQuery setParameterList(String name,
                          Object[] vals,
                          Object type)
                          throws SqlProcessorException

Binds multiple values to a named query parameter. This is useful for binding a list of values to the query fragment in (:value_list).

Parameters:

name - the name of the parameter

vals - a collection of values

type - the (META) type of the parameter

Returns:

this instance to enable the methods chaining

Throws:

SqlProcessorException - in the case of any problem in ORM or JDBC stack

executeBatch

int[] executeBatch(String[] statements)
                   throws SqlProcessorException

Submits a batch of commands to the database for execution and if all commands execute successfully, returns an array of update counts.

Parameters:

statements - SQL statements to be executed in batch

Returns:

an array of update counts containing one element for each command in the batch

Throws:

SqlProcessorException - in the case of any problem in ORM or JDBC stack

setLogError

void setLogError(boolean logError)

Sets an indicator the failed SQL command should be logged

Parameters:

logError - an indicator the failed SQL command should be logged