org.hdpagination.dataaccess.support.orm
Class HBN3QueryCallbackNamedParamWrapper

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

All Implemented Interfaces:

java.io.Serializable, QueryCallback, HBN3QueryCallback

public class HBN3QueryCallbackNamedParamWrapper
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 named parameter type. If you prefer positioned parameter (JDBC-style ? parameters) type, HBN3QueryCallbackWrapper should be used.

The way to use HBN3QueryCallbackNamedParamWrapper usually follows the following steps:

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

(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:

HBN3QueryCallbackNamedParamWrapper callback = HBN3QueryCallbackNamedParamWrapper.newInstance("from ProductVO p")
.addRestriction( NamedParamRestrictions.eq("p.prodNo", "propNo", crit.getProdNo()) )
.addRestriction( NamedParamRestrictions.contains("p.description", "desc", crit.getDescription()) )
.addRestriction( NamedParamRestrictions.ge("p.price", "priceFrom", priceFrom) )
.addRestriction( NamedParamRestrictions.le("p.price", "priceTo", priceTo) )
.setOrderBy("p.madeIn");

Behind the scene, the way HBN3QueryCallbackNamedParamWrapper 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 :desc) 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

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

Method Summary

HBN3QueryCallbackNamedParamWrapper	addRestriction(NamedParamRestriction restriction) Add restriction applied to the query SELECT statement.
HBN3QueryCallbackNamedParamWrapper	addRestriction(java.lang.String clause) Add restriction applied to the query SELECT statement.
HBN3QueryCallbackNamedParamWrapper	addRestriction(java.lang.String clause, NamedParams params) Add restriction applied to the query SELECT statement.
HBN3QueryCallbackNamedParamWrapper	addRestriction(java.lang.String clause, java.lang.String paramName, java.lang.Object paramValue) Add restriction applied to the query SELECT statement.
java.lang.String	getCountRecordsQueryStatement() Query statement to count total records.
java.lang.String	getQueryStatement() Generate the full query statement
static HBN3QueryCallbackNamedParamWrapper	newInstance(java.lang.String selectFrom) As a convenient (or shortcut) factory method to get an initial HBN3QueryCallbackNamedParamWrapper 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).
HBN3QueryCallbackNamedParamWrapper	setOrderBy(java.lang.String orderBy) Set order by
HBN3QueryCallbackNamedParamWrapper	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

HBN3QueryCallbackNamedParamWrapper

public HBN3QueryCallbackNamedParamWrapper(java.lang.String selectFrom)

Please note that the factory method newInstance(java.lang.String) is encouraged to use to create an object of HBN3QueryCallbackNamedParamWrapper 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 HBN3QueryCallbackNamedParamWrapper 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 HBN3QueryCallbackNamedParamWrapper 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 HBN3QueryCallbackNamedParamWrapper addRestriction(NamedParamRestriction 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 NamedParamRestrictions. NamedParamRestrictions provides some static factory methods to generate object of NamedParamRestriction conditionally based on parameter value.

The general rule for these static factory methods in NamedParamRestrictions is:

If the value of argument paramValue is null or blank (with type of java.lang.String), it returns null. As a result,the restriction is not applied.

The benefit of doing this is you can avoid coding the annoying IF .. ELSE checking in your code.

Parameters:

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

Returns:

this, to enable chaining

addRestriction

public HBN3QueryCallbackNamedParamWrapper 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 named parameter. This argument can not be null or blank.

Returns:

this, to enable chaining

addRestriction

public HBN3QueryCallbackNamedParamWrapper addRestriction(java.lang.String clause,
                                                         java.lang.String paramName,
                                                         java.lang.Object paramValue)

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. This method allows single named query parameter.

Parameters:

clause - The WHERE clause fragment (after prefixing "WHERE" or "AND" HQL keywords) will be appended to the SELECT statement. Please note that the key words "WHERE" and "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 only contain ONE and ONLY ONE named query parameter of the form :name and it should match the 'paramName' argument. For example, if the argument clause is "p.madeIn = :country", then the value of argument paramName should be "country". This argument can not be null or blank.

paramName - The name of named query parameter. It must match the token value (it is country in above example) inside the clause fragment. This argument can not be null or blank.

paramValue - The value of named query parameter This argument can not be null.

Returns:

this, to enable chaining

addRestriction

public HBN3QueryCallbackNamedParamWrapper addRestriction(java.lang.String clause,
                                                         NamedParams 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. This method allows multiple named query parameters.

Parameters:

clause - The WHERE clause fragment (after prefixing "WHERE" or "AND" HQL keywords) will be appended to the SELECT statement. Please note that the key words "WHERE" and "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 named query parameters of the form :name and they should match the names defined in the argument params. For example, if the argument clause is "p.price BETWEEN :priceFrom and :priceTo"", the named parameters with name as priceFrom and priceTo should be included in the argument params. This argument can not be null or blank.

params - An object defining the mapping of named query parameters (key:parameter name, value:parameter value). NamedParamsList, a default implementation of NamedParams, can be used to add multiple named parameters. This argument can not be null.

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 the 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 HBN3QueryCallbackNamedParamWrapper newInstance(java.lang.String selectFrom)

As a convenient (or shortcut) factory method to get an initial HBN3QueryCallbackNamedParamWrapper object. Please note that this factory method is encouraged to create an object of HBN3QueryCallbackNamedParamWrapper 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: