org.hdpagination.dataaccess.support.orm
Class JPAQueryCallbackNamedParamWrapper

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

All Implemented Interfaces:

java.io.Serializable, QueryCallback, JPAQueryCallback

public class JPAQueryCallbackNamedParamWrapper
extends QueryBuilder
implements JPAQueryCallback

This class is used as a convenient wrapper class for JPAQueryCallback. It simplifies the way to generate an instance of JPAQueryCallback based on the searching criteria fields. Typically, there are two types of query parameters binding in the JP QL (Java Persistence Query Language) Queries. 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, JPAQueryCallbackWrapper should be used.

The way to use JPAQueryCallbackNamedParamWrapper usually follows the following steps:

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

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

JPAQueryCallbackNamedParamWrapper callback = JPAQueryCallbackNamedParamWrapper.newInstance("select p from ProductVO p", "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 JPAQueryCallbackNamedParamWrapper 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

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

Method Summary

JPAQueryCallbackNamedParamWrapper	addRestriction(NamedParamRestriction restriction) Add restriction applied to the query SELECT statement.
JPAQueryCallbackNamedParamWrapper	addRestriction(java.lang.String clause) Add restriction applied to the query SELECT statement.
JPAQueryCallbackNamedParamWrapper	addRestriction(java.lang.String clause, NamedParams params) Add restriction applied to the query SELECT statement.
JPAQueryCallbackNamedParamWrapper	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 JPAQueryCallbackNamedParamWrapper	newInstance(java.lang.String selectFrom, java.lang.String countArgument) As a convenient (or shortcut) factory method to get an initial JPAQueryCallbackNamedParamWrapper object.
java.util.List	processQueriedResult(java.util.List queriedResult) process the result from calling javax.persistence.Query.list() method in JPAQueryTemplate.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 JPAQueryTemplate.query(QueryCallback callback, int pageSize, int pageNo).
JPAQueryCallbackNamedParamWrapper	setOrderBy(java.lang.String orderBy) Set order by
JPAQueryCallbackNamedParamWrapper	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 EntityManager is closed.
void	setValues(javax.persistence.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

JPAQueryCallbackNamedParamWrapper

public JPAQueryCallbackNamedParamWrapper(java.lang.String selectFrom,
                                         java.lang.String countArgument)

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

Parameters:

selectFrom - the "SELECT ... FROM .." statement for the JP QL (Java Persistence Query Language) query. 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.

countArgument - to query the total number of records, the "SELECT COUNT([countArgument]) FROM ..." statement (generated based on the query statement) needs to be executed. As specified by JPA Specification, the COUNT function takes either an identification variable or a path expression as its argument. This argument will be used as the COUNT function's argument. This argument can not be null or empty, unless the property countRecordsQueryStatement is set explicitly by calling the method JPAQueryCallbackNamedParamWrapper.setCountRecordsQueryStatement(java.lang.String) (in this case, it will be ignored).

Method Detail

setOrderBy

public JPAQueryCallbackNamedParamWrapper 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 JPAQueryCallbackNamedParamWrapper 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 EntityManager is closed. Its main purpose is to allow you to trigger lazy loading before EntityManager is closed. See sample code is provided in QueryResultProcessor.

Parameters:

queryResultProcessor -

Since:

1.3.2

addRestriction

public JPAQueryCallbackNamedParamWrapper 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 JPAQueryCallbackNamedParamWrapper 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 JPAQueryCallbackNamedParamWrapper 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" 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 JPAQueryCallbackNamedParamWrapper 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" 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(javax.persistence.Query query)

Description copied from interface: JPAQueryCallback

Operate on Query instance to bind parameters

Specified by:

setValues in interface JPAQueryCallback

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

process the result from calling javax.persistence.Query.list() method in JPAQueryTemplate.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 JPAQueryTemplate.query(QueryCallback callback, int pageSize, int pageNo).

Specified by:

processQueriedResult in interface JPAQueryCallback

Returns:

newInstance

public static JPAQueryCallbackNamedParamWrapper newInstance(java.lang.String selectFrom,
                                                            java.lang.String countArgument)

As a convenient (or shortcut) factory method to get an initial JPAQueryCallbackNamedParamWrapper object. This factory method is encouraged to create an object of JPAQueryCallbackNamedParamWrapper rather than instantiating it directly.

Please note, since version 1.3.2, this method adds a second argument countArgument to fix a design defect not complying with the JPA specification. So if you upgrade from previous version (1.3.1), you will find a compilation error.

Parameters:

selectFrom - the "SELECT ... FROM .." or "FROM ..." statement for the 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.

countArgument - to query the total number of records, the "SELECT COUNT([countArgument]) FROM ..." statement (generated based on the query statement) needs to be executed. As specified by JPA Specification, the COUNT function takes either an identification variable or a path expression as its argument. This argument will be used as the COUNT function's argument. This argument can not be null or empty, unless the property countRecordsQueryStatement is set explicitly by calling the method JPAQueryCallbackNamedParamWrapper.setCountRecordsQueryStatement(java.lang.String) (in this case, it will be ignored).

Returns: