org.proteios.core.query
Class Hql

java.lang.Object
  org.proteios.core.query.Hql

public class Hql
extends Object

A factory class to create expressions, joins, etc. that are only used by HQL queries. The elements will throw an UnsupportedOperationException if passed to a SQL query.

Version:

2.0

Author:

Nicklas

Last modified

$Date: 2009-04-09 08:48:11 +0200 (Thu, 09 Apr 2009) $

Field Summary

static Pattern	ALIAS_REGEXP An alias can only contain the characters a-z, A-Z or 0-9.
static Pattern	PROPERTY_REGEXP A property can only contain the characters a-zA-Z0-9 and period(.)

Constructor Summary

Hql()

Method Summary

static Expression	alias(String alias) Same as property(alias, null).
static Expression	elements(String alias, String property) Create an elements expression for a property that is a collection of values.
static Expression	entity(BasicItem entity) Create an expression representing an item.
static Expression	index(String alias, String property) Create an index expression for a property that is a map or a list.
static Join	innerJoin(String property, String joinedAlias) Same as innerJoin(null, propert, joinedAlias)
static Join	innerJoin(String alias, String property, String joinedAlias) Create an inner join query element.
static Join	leftJoin(String property, String joinedAlias) Same as leftJoin(null, propert, joinedAlias, null)
static Join	leftJoin(String alias, String property, String joinedAlias, Restriction on) Create a left join query element.
static Expression	property(String property) Same as property(null, property).
static Expression	property(String alias, String property) Create an expression representing a property of an object or joined alias.
static Join	rightJoin(String property, String joinedAlias) Same as rightJoin(null, propert, joinedAlias, null)
static Join	rightJoin(String alias, String property, String joinedAlias, Restriction on) Create a right join query element.

Methods inherited from class java.lang.Object

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

Field Detail

PROPERTY_REGEXP

public static final Pattern PROPERTY_REGEXP

A property can only contain the characters a-zA-Z0-9 and period(.) It cannot begin or end with a period and cannot have two periods in a sequence.

ALIAS_REGEXP

public static final Pattern ALIAS_REGEXP

An alias can only contain the characters a-z, A-Z or 0-9.

Constructor Detail

Hql

public Hql()

Method Detail

entity

public static Expression entity(BasicItem entity)
                         throws InvalidDataException

Create an expression representing an item. In the query the actual value used is the id of the entity. See property(String, String) for a code example.

Parameters:

entity - The entity

Throws:

InvalidDataException - If the etity is null

property

public static Expression property(String property)
                           throws InvalidDataException

Same as property(null, property).

Throws:

InvalidDataException

See Also:

property(String, String)

alias

public static Expression alias(String alias)
                        throws InvalidDataException

Same as property(alias, null).

Throws:

InvalidDataException

See Also:

property(String, String)

property

public static Expression property(String alias,
                                  String property)
                           throws InvalidDataException

Create an expression representing a property of an object or joined alias. Property names are usually named after a getter method minus the "get" part. Ie. a getName() method corresponds to a "name" property. If no alias is given the property name is resolved against the root entity of the query, otherwise it is resolved against the joined entity with the given alias.

// Sorting user by the "name" property
ItemQuery<User> query = User.getQuery();
query.order(Orders.asc(Hql.property("name")));

// Generated HQL
SELECT usr
FROM UserData usr
ORDER BY usr.name ASC

// Loading users members of the Administrators role
DbControl dc = ...
int adminId = SystemItems.get(Role.ADMINISTRATOR); // Assume adminId = 1
Role admin = Role.getById(dc, adminId);
ItemQuery<User> query = User.getQuery();
query.join(Hql.innerJoin("roles", "rle"));
query.restrict(
  Restrictions.eq(
    Hql.alias("rle"),
    Hql.entity(admin)
  )
);

// Generated HQL
SELECT usr 
FROM UserData usr
JOIN usr.roles rle
WHERE rle = 1

Parameters:

property - The property name of the object

alias - Alias to resolve the property against, use null to resolve the property agains the root entity

Returns:

An expression representing the property

Throws:

InvalidDataException - If both the property and alias is null or any of the parameters contains invalid characters

index

public static Expression index(String alias,
                               String property)
                        throws InvalidDataException

Create an index expression for a property that is a map or a list. If no alias is given the property name is resolved against the root entity of the query, otherwise it is resolved against the joined entity with the given alias. If no property is given only the alias is used.

Parameters:

alias - The alias to resolve the property agains, or null to resolve the property against the root entity

property - The property name of the object which must be a map or list association

Returns:

An expression representing the index collection of the property

Throws:

InvalidDataException - If both the alias and property parameters are null or if any of them contains invalid characters

elements

public static Expression elements(String alias,
                                  String property)
                           throws InvalidDataException

Create an elements expression for a property that is a collection of values. If no alias is given the property name is resolved against the root entity of the query, otherwise it is resolved against the joined entity with the given alias.

Parameters:

property - The property name of the object which must set, map or other collection

Returns:

An expression representing the values collection of the property

Throws:

InvalidDataException - If both the alias and property parameters are null or if any of them contains invalid characters

innerJoin

public static Join innerJoin(String property,
                             String joinedAlias)
                      throws InvalidDataException

Same as innerJoin(null, propert, joinedAlias)

Throws:

InvalidDataException

See Also:

innerJoin(String, String, String)

innerJoin

public static Join innerJoin(String alias,
                             String property,
                             String joinedAlias)
                      throws InvalidDataException

Create an inner join query element. An inner join only selects an item if it has an associated item. The property must reference an association to another item or collection of values. See property(String, String) for a code example.

Parameters:

alias - The alias to resolve the property against, or null to resolve the property against the root entity

property - The property name of the associated entity (required)

joinedAlias - The alias to give the joined entity (required)

Returns:

A join query element

Throws:

InvalidDataException - If the property or joined alias parameter are null or if any of the parameters contains invalid characters

leftJoin

public static Join leftJoin(String property,
                            String joinedAlias)
                     throws InvalidDataException

Same as leftJoin(null, propert, joinedAlias, null)

Throws:

InvalidDataException

See Also:

leftJoin(String, String, String, Restriction)

leftJoin

public static Join leftJoin(String alias,
                            String property,
                            String joinedAlias,
                            Restriction on)
                     throws InvalidDataException

Create a left join query element. A left join selects all items from the root entity even if they don't have an associated item. The property must reference an association to another item or collection of values.

// Find all users not assigned to a role
ItemQuery<User> query = User.getQuery();
query.join(Hql.leftJoin("roles", "rle"));
query.restrict(
  Restrictions.eq(
    Hql.alias("rle"),
    null
  )
);

// Generated HQL
SELECT usr 
FROM UserData usr
LEFT JOIN usr.roles rle
WHERE rle IS NULL

Parameters:

alias - The alias to resolve the property against, or null to resolve the property against the root entity

property - The property name of the associated entity (required)

joinedAlias - The alias to give the joined entity (required)

on - Optional extra restriction that is used in the ON clause of the generated query

Returns:

A join query element

Throws:

InvalidDataException - If the property or joined alias parameter are null or if any of the parameters contains invalid characters

rightJoin

public static Join rightJoin(String property,
                             String joinedAlias)
                      throws InvalidDataException

Same as rightJoin(null, propert, joinedAlias, null)

Throws:

InvalidDataException

See Also:

rightJoin(String, String, String, Restriction)

rightJoin

public static Join rightJoin(String alias,
                             String property,
                             String joinedAlias,
                             Restriction on)
                      throws InvalidDataException

Create a right join query element. A right join selects all items from the joined association even if they don't have an associated item in the root entity. The property must reference an association to another item or collection of values.

Parameters:

alias - The alias to resolve the property against, or null to resolve the property against the root entity

property - The property name of the associated entity (required)

joinedAlias - The alias to give the joined entity (required)

on - Optional extra restriction that is used in the ON clause of the generated query

Returns:

A join query element

Throws:

InvalidDataException - If the property or joined alias parameter are null or if any of the parameters contains invalid characters