org.hdpagination.dataaccess.support.orm
Class HBN3QueryCallbackWrapper

java.lang.Object
  org.hdpagination.dataaccess.support.QueryBuilder
      org.hdpagination.dataaccess.support.orm.HBN3QueryCallbackWrapper

All Implemented Interfaces:

java.io.Serializable, QueryCallback, HBN3QueryCallback

public class HBN3QueryCallbackWrapper
extends QueryBuilder
implements HBN3QueryCallback

This class is used as a convenient wrapper class for HBN3QueryCallback. It simplifies the way to generate an instance of HBN3QueryCallback based on the searching criteria fields. Typically, there are two types of query parameters binding in the Hibernate Query. One is positioned parameter (JDBC-style ? parameters) and another one is named parameter. This wrapper class is used for positioned parameter (JDBC-style) type. If you prefer named parameter type, HBN3QueryCallbackNamedParamWrapper should be used.

The way to use HBN3QueryCallbackWrapper usually follows the following steps:

(1) Call its static factory method getInstance to get an initial instance of HBN3QueryCallbackWrapper.

(2) Call addRestriction methods from the instance.

(3) Call setOrderBy method if you want to sort the search result.

A sample code is as follows:

HBN3QueryCallbackWrapper callback = HBN3QueryCallbackWrapper.newInstance("from ProductVO p")
.addRestriction( Restrictions.eq("p.prodNo", crit.getProdNo()) )
.addRestriction( Restrictions.in("p.madeIn", crit.getMadeIn()) )
.addRestriction( Restrictions.contains("p.description", crit.getDescription()) )
.addRestriction( Restrictions.range("p.price", priceFrom, priceTo))
.setOrderBy("p.madeIn");

Behind the scene, the way HBN3QueryCallbackWrapper generates the full query statement can be described as:

It uses the value of 'selectFrom' (the first argument from static factory methods newInstance) to construct an initial query statement.

It goes through all the restrictions (added by calling the methods addRestriction). For each restriction:

(1) It appends the keyword 'WHERE' or 'AND' to the query statement first. If it is the first restriction, 'WHERE' is added; otherwise 'AND' is added.

(2) Then it appends the restriction's clause statement (e.g. p.description LIKE ?) to the query statement.

If orderBy is set, then append the generated ORDER BY clause to the query statement.

Since:

1.3.1

Author:

Liangfeng Ren

See Also:

Serialized Form

Field Summary

Fields inherited from class org.hdpagination.dataaccess.support.QueryBuilder

asending, countStatement, orderBy, selectFrom

Constructor Summary

HBN3QueryCallbackWrapper(java.lang.String selectFrom)
Please note that the factory method newInstance(java.lang.String) is encouraged to use to create an object of HBN3QueryCallbackWrapper rather than instantiating it directly.

Method Summary

HBN3QueryCallbackWrapper	addRestriction(Restriction restriction) Add restriction applied to the query SELECT statement.
HBN3QueryCallbackWrapper	addRestriction(java.lang.String clause) Add restriction applied to the query SELECT statement.
HBN3QueryCallbackWrapper	addRestriction(java.lang.String clause, java.util.List params) Add restriction applied to the query SELECT statement.
HBN3QueryCallbackWrapper	addRestriction(java.lang.String clause, java.lang.Object param) Add restriction applied to the query SELECT statement.
HBN3QueryCallbackWrapper	addRestriction(java.lang.String clause, java.lang.Object[] params) Add restriction applied to the query SELECT statement.
java.lang.String	getCountRecordsQueryStatement() Query statement to count total records.
java.lang.String	getQueryStatement() Generate full query statement
static HBN3QueryCallbackWrapper	newInstance(java.lang.String selectFrom) As a convenient (or shortcut) factory method to get an HBN3QueryCallbackWrapper object.
java.util.List	processQueriedResult(java.util.List queriedResult) process the result from calling org.hibernate.Query.list() method in Hibernate3QueryTemplate.query(QueryCallback callback, int pageSize, int pageNo), and the value(java.util.List) returned by current method will be used as the return value of Hibernate3QueryTemplate.query(QueryCallback callback, int pageSize, int pageNo).
HBN3QueryCallbackWrapper	setOrderBy(java.lang.String orderBy) Set order by
HBN3QueryCallbackWrapper	setOrderBy(java.lang.String orderBy, boolean ascending) Set order by
void	setQueryResultProcessor(QueryResultProcessor queryResultProcessor) Set an instance of QueryResultProcessor to process the query result (java.util.List) before Session is closed.
void	setValues(org.hibernate.Query query) Operate on Query instance to bind parameters

Methods inherited from class org.hdpagination.dataaccess.support.QueryBuilder

getQueryOrder, setCountRecordsQueryStatement, setQueryOrder

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.hdpagination.core.QueryCallback

getQueryOrder, setQueryOrder

Constructor Detail

HBN3QueryCallbackWrapper

public HBN3QueryCallbackWrapper(java.lang.String selectFrom)

Please note that the factory method newInstance(java.lang.String) is encouraged to use to create an object of HBN3QueryCallbackWrapper rather than instantiating it directly.

Parameters:

selectFrom - the "SELECT ... FROM .." or "FROM ..." statement for the HQL query. Ideally, it should not contain the "WHERE" clause, otherwise when restrictions are added later, the full generated query statement will not be correct (it contains more than one "WHERE" key words). The methods addRestriction are used to specify the "WHERE" clause. It also should not contain the "ORDER BY" clause, the method setOrderBy is for this purpose.

Method Detail

setOrderBy

public HBN3QueryCallbackWrapper setOrderBy(java.lang.String orderBy)

Set order by

Parameters:

orderBy - the column after the key word ORDER BY in 'ORDER BY' clause

Returns:

this, to enable chaining

setOrderBy

public HBN3QueryCallbackWrapper setOrderBy(java.lang.String orderBy,
                                           boolean ascending)

Set order by

Parameters:

orderBy - the column after the key word ORDER BY in 'ORDER BY' clause

ascending - if sorted in ascending order

Returns:

this, to enable chaining

setQueryResultProcessor

public void setQueryResultProcessor(QueryResultProcessor queryResultProcessor)

Set an instance of QueryResultProcessor to process the query result (java.util.List) before Session is closed. Its main purpose is to allow you to trigger lazy loading before Session is closed. See sample code is provided in QueryResultProcessor (Event that sample code is for JPA, but code will be very similar for Hibernate).

Parameters:

queryResultProcessor -

Since:

1.3.2

addRestriction

public HBN3QueryCallbackWrapper addRestriction(Restriction restriction)

Add restriction applied to the query SELECT statement.

If the argument 'restriction' is not null, the restriction will be appended to the WHERE clause of the SELECT statement to filter the search result. Otherwise, the restriction will not be appended.

Typically, this method is used together with one of static factory methods from Restrictions. Restrictions provides some static factory methods to generate object of Restriction conditionally based on the parameter value.

A general rule for some of its simple factory methods (eq, gt, ge, lt, le, contains) is:

If the parameter is null or blank (if the type of parameter is java.lang.String), the method returns null. As a result,the restriction will not be added.

In a typical search scenario, only if the search criteria field is provided (e.g. its value is not null and empty), the restriction should be applied. This method particularly suits this scenario. You can avoid coding the annoying IF .. ELSE checking by doing this.

Parameters:

restriction - If the argument is null, the restriction is not applied to the query.

Returns:

this, to enable chaining

addRestriction

public HBN3QueryCallbackWrapper addRestriction(java.lang.String clause)

Add restriction applied to the query SELECT statement. The restriction will be appended to the WHERE clause of the SELECT statement to filter the search result.

Parameters:

clause - The WHERE clause fragment (after prefixing "WHERE" or "AND" keywords) will be appended to the SELECT statement. Please note that the key words "WHERE" or "AND" should be excluded from this clause fragment. When generating the full query statement, the framework knows when to prefix "WHERE" or "AND". The clause fragment should not contain '?' IN parameter placeholder. This argument can not be null or blank.

Returns:

this, to enable chaining

addRestriction

public HBN3QueryCallbackWrapper addRestriction(java.lang.String clause,
                                               java.lang.Object param)

Add restriction applied to the query SELECT statement. The restriction will be appended to the WHERE clause of the SELECT statement to filter the search result.

Parameters:

clause - The WHERE clause fragment (after prefixing "WHERE" or "AND" keywords) will be appended to the SELECT statement. Please note that the key words "WHERE" or "AND" should be excluded from this clause fragment. When generating the full query statement, the framework knows when to prefix "WHERE" or "AND". The clause fragment should contain ONE and ONLY ONE '?' IN parameter placeholder. This argument can not be null or blank.

param - parameter binding to the '?' IN parameter placeholder in the clause argument. It should be a valid type to call the method org.hibernate.Query.setParameter(int position, Object val) as the second argument. This argument can not be null.

Returns:

this, to enable chaining

addRestriction

public HBN3QueryCallbackWrapper addRestriction(java.lang.String clause,
                                               java.lang.Object[] params)

Add restriction applied to the query SELECT statement. The restriction will be appended to the WHERE clause of the SELECT statement to filter the search result.

Parameters:

clause - The WHERE clause fragment (after prefixing "WHERE" or "AND" keywords) will be appended to the SELECT statement. Please note that the key words "WHERE" or "AND" should be excluded from this clause fragment. When generating the full query statement, the framework knows when to prefix "WHERE" or "AND". The clause fragment can contain multiple '?' IN parameter placeholders, and the number of placeholders must match the number of elements in the params argument. This argument can not be null or blank.

params - the parameter values binding to the '?' IN parameter placeholders in the clause argument. Its elements should be a valid type to call the method org.hibernate.Query.setParameter(int position, Object val) as the second argument. This argument can not be null and should contain at least one element.

Returns:

this, to enable chaining

addRestriction

public HBN3QueryCallbackWrapper addRestriction(java.lang.String clause,
                                               java.util.List params)

Add restriction applied to the query SELECT statement. The restriction will be appended to the WHERE clause of the SELECT statement to filter the search result.

Parameters:

clause - The WHERE clause fragment (after prefixing "WHERE" or "AND" sql keywords) will be appended to the SELECT statement. Please note that the key words "WHERE" or "AND" should be excluded from this clause fragment. When generating the full query statement, the framework knows when to prefix "WHERE" or "AND". The clause fragment can contain multiple '?' IN parameter placeholders, and the number of placeholders must match the number of elements in the params argument. This argument can not be null or blank.

params - the parameter values binding to the '?' IN parameter placeholders in the clause argument. Its elements should be a valid type to call the method org.hibernate.Query.setParameter(int position, Object val) as the second argument. This argument can not be null and should contain at least one element.

Returns:

this, to enable chaining

setValues

public void setValues(org.hibernate.Query query)

Description copied from interface: HBN3QueryCallback

Operate on Query instance to bind parameters

Specified by:

setValues in interface HBN3QueryCallback

getQueryStatement

public java.lang.String getQueryStatement()

Generate full query statement

Specified by:

getQueryStatement in interface QueryCallback

Returns:

getCountRecordsQueryStatement

public java.lang.String getCountRecordsQueryStatement()

Description copied from class: QueryBuilder

Query statement to count total records. If this property is not provided, the corresponding QueryTemplate will do some auto translation to generate the "count query statement" based on "queryStatement" property and related persistence technology or database provides (e.g. the way of translation is different between Hibernate and JDBC, Oracle and DB2).

Specified by:

getCountRecordsQueryStatement in interface QueryCallback

Overrides:

getCountRecordsQueryStatement in class QueryBuilder

Returns:

processQueriedResult

public java.util.List processQueriedResult(java.util.List queriedResult)

Description copied from interface: HBN3QueryCallback

process the result from calling org.hibernate.Query.list() method in Hibernate3QueryTemplate.query(QueryCallback callback, int pageSize, int pageNo), and the value(java.util.List) returned by current method will be used as the return value of Hibernate3QueryTemplate.query(QueryCallback callback, int pageSize, int pageNo).

Specified by:

processQueriedResult in interface HBN3QueryCallback

Returns:

newInstance

public static HBN3QueryCallbackWrapper newInstance(java.lang.String selectFrom)

As a convenient (or shortcut) factory method to get an HBN3QueryCallbackWrapper object. Please note that the factory methods are encouraged to use to create an object of HBN3QueryCallbackWrapper rather than instantiating it directly.

Parameters:

selectFrom - the "SELECT ... FROM .." or "FROM ..." statement for the HQL query. Ideally, it should not contain the "WHERE" clause, otherwise when restrictions are added later, the full generated query statement will not be correct (it contains more than one "WHERE" key words). The methods addRestriction are used to specify the "WHERE" clause. It also should not contain the "ORDER BY" clause, the method setOrderBy is for this purpose. This argument can not be null or empty.

Returns: