js.transaction.hibernate

Interface HqlQuery

All Known Implementing Classes:

HqlQueryImpl

public interface HqlQuery

Hibernate query language helper.

Author:

Iulian Rotaru

Method Summary

Modifier and Type	Method and Description
void	delete() Surrogate for update used for delete queries.
HqlQuery	limit(int rowsCount) Set the maximum number of rows this query may return.
HqlQuery	limit(int offset, int rowsCount) Set first record offset and maximum number of rows this query may return.
<T> List<T>	list() Execute database select and return list of entities.
<T> List<T>	list(Class<T> type) Variant of list() that return list of entities of specified type.
HqlQuery	load(String... lazyFields) Load fields declared as lazy into mapping definition.
<K,V> Map<K,V>	map() Execute database select on two properties and returns them as key/values map, first property in query being the map key.
<T> T	object() Execute database select and return single entity.
HqlQuery	param(String name, Collection<?> value, boolean forceEmpty) Bind collection to named query parameter and select behavior for empty value.
HqlQuery	param(String name, Object value) Bind a not null value to a named query parameter.
void	update() Execute update designated by this HQL query.

Method Detail

param

HqlQuery param(String name,
               Object value)

Bind a not null value to a named query parameter. Please remember that if mix positioned and named parameters former must appear first into query; more specifically, all positioned parameters MUST precede first named one.

Parameters:

name - parameter name,

value - parameter value.

Returns:

this pointer.

Throws:

IllegalArgumentException - if parameter value is null.

param

HqlQuery param(String name,
               Collection<?> value,
               boolean forceEmpty)

Bind collection to named query parameter and select behavior for empty value. The same rule for positioned parameters applies to this method, see param(String, Object).

The third argument is used to select this HQL query behavior when value argument is an empty collection. Not sure if depends on database driver or is by specification, but observed on some: there is exception when use empty collection parameter with IN clause. If true, argument forceEmpty will force list() and list(Class) to return empty result; otherwise provided collection should not be empty.

Parameters:

name - parameter name,

value - parameter value,

forceEmpty - force list() and list(Class) to return empty result if value is empty.

Returns:

this pointer.

Throws:

IllegalArgumentException - if parameter value is null.

limit

HqlQuery limit(int rowsCount)

Set the maximum number of rows this query may return. Internally uses Query.setMaxResults(int).

Parameters:

rowsCount - maximum number of rows count.

Returns:

this pointer.

Throws:

IllegalArgumentException - if rows count argument is not strict positive.

limit

HqlQuery limit(int offset,
               int rowsCount)

Set first record offset and maximum number of rows this query may return. Internally uses Query.setFirstResult(int) and Query.setMaxResults(int).

Parameters:

offset - first record offset, starting with 0,

rowsCount - the number of maximum rows count.

Returns:

this pointer.

Throws:

IllegalArgumentException - if any given argument is negative or rows count is zero.

load

HqlQuery load(String... lazyFields)

Load fields declared as lazy into mapping definition. This method uses internally Hibernate.initialize(Object).

Parameters:

lazyFields - variable number of field names.

Returns:

this pointer.

Throws:

IllegalArgumentException - if no lazy field argument supplied.

object

<T> T object()

Execute database select and return single entity. In the scope of this interface an entity is a Java type with defined ORM mapping. Hibernate engine will rise exception if given entity argument is not defined.

 class Person {
    int id;
    String name;
 }
 . . .
 Person person = sm.HQL("from Person where id=?", personId).object();
 

In above, Person class has mapping defined and entity has the same name. Query must return at most one record into results set; there is Hibernate runtime exception if more records. This method uses internally Query.uniqueResult().

Type Parameters:

T - instance type.

Returns:

instance of given entity.

Throws:

org.hibernate.NonUniqueObjectException - if query returns more than one record.

org.hibernate.HibernateException - for Hibernate related fails like bad query syntax or entity not defined.

list

<T> List<T> list()

Execute database select and return list of entities. See object() for a discussion about entities. This method uses internally Query.list(). Usage pattern is like below:

 List<Person> persons = sm.HQL("from Person").list();
 

Type Parameters:

T - list type.

Returns:

list of entities, possible empty.

Throws:

org.hibernate.HibernateException - for Hibernate related fails like bad query syntax or entity not defined.

list

<T> List<T> list(Class<T> type)

Variant of list() that return list of entities of specified type. This variant is especially useful when want to map columns to arbitrary user defined types. Selected column alias is used to invoke setter on user defined type. Column alias should be present even if the same as column name; it is possible for database driver to force column names as upper case if if in HWL query is lower.

Usage pattern is like below:

 class Person {
    private String name;
    private int age;
    ...
    // properties setters
 }
 
 List<Person> persons = sm.HQL("select column1 as name, column2 as age from ... ").list(Person.class);
 

Implementation uses Transformers.aliasToBean(type) to bind a built-in result transformer. It is caller responsibility to ensure type compatibility between selected columns and type fields. For example if database numeric value is LONG there will be exception when try to set age value.

Type Parameters:

T - list type.

Parameters:

type - requested entity type.

Returns:

list of entities, possible empty.

map

<K,V> Map<K,V> map()

Execute database select on two properties and returns them as key/values map, first property in query being the map key. It is user code responsibility to ensure properties to map key/value type compatibility.

 Map<String, Integer> serialMap = sm.HQL("select serial,id from Ticket where county=?", county).map();
 

Note that in above example database ID is map value, not necessarily map key. Key and value are determined by property position in query, first is key and the second is value.

Type Parameters:

K - map key type.

V - map value type.

Returns:

maps of key/values possible empty.

Throws:

org.hibernate.HibernateException - for Hibernate related fails like bad query syntax or entity not defined.

update

void update()

Execute update designated by this HQL query.

delete

void delete()

Surrogate for update used for delete queries. For now just delegate update().