2.17.2: 2011-06-17

net.sf.basedb.core.query
Class Hql

java.lang.Object
  extended by net.sf.basedb.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: 2011-02-04 09:25:16 +0100 (Fri, 04 Feb 2011) $

Field Summary
static Pattern ALIAS_REGEXP
          An alias can only contain the characters a-z, A-Z or 0-9.
private static Logger log
          Log core events.
static Pattern PROPERTY_REGEXP
          A property can only contain the characters a-zA-Z0-9, period(.) or hash (#) It cannot begin or end with a period/hash and cannot have two periods/hashes in a sequence.
 
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(BasicData entity)
          Create an expression representing an item which is a subclass of BasicData, for example a reporter.
static Expression entity(BasicItem entity)
          Create an expression representing an item which is a subclass of BasicItem.
static Expression entityParameter(String name, Item itemType)
          Create an expression for a parameter which must be an entity of a specified type.
static Expression expression(String exprString, String prefix)
           
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 innerJoin(String alias, String property, String joinedAlias, boolean fetch)
          Same as innerJoin(null, propert, joinedAlias, null, false)
static Join innerJoin(String alias, String property, String joinedAlias, Restriction on, boolean fetch)
          Create an inner join query element and optionally prefetch the joined items in the same query.
static Restriction isNotPartOf(String alias, String property, ReporterList reporterList)
           
static Restriction isPartOf(String alias, String property, ReporterList reporterList)
           
static Join leftJoin(String property, String joinedAlias)
          Same as leftJoin(null, propert, joinedAlias, null, false)
static Join leftJoin(String alias, String property, String joinedAlias, Restriction on, boolean fetch)
          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 Restriction restriction(String restrictionString, String prefix)
           
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.
static Restriction sharedTo(boolean sharedTo, Restriction users, Restriction groups, Restriction projects)
          A special restriction that works on Shareable items.
static Expression size(String alias, String property)
          Create a size expression for a property that is a collection of values.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

log

private static final Logger log
Log core events.


PROPERTY_REGEXP

public static final Pattern PROPERTY_REGEXP
A property can only contain the characters a-zA-Z0-9, period(.) or hash (#) It cannot begin or end with a period/hash and cannot have two periods/hashes in a sequence. A hash indicates a path to a component while a period indicates a path to another entity.


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 which is a subclass of BasicItem. 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
Returns:
an object implementing Expression
Throws:
InvalidDataException - If the entity is null or isn't saved to the database
See Also:
entity(BasicData)

entity

public static Expression entity(BasicData entity)
                         throws InvalidDataException
Create an expression representing an item which is a subclass of BasicData, for example a reporter. 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 entity is null
Since:
2.2.2
See Also:
entity(BasicItem)

entityParameter

public static Expression entityParameter(String name,
                                         Item itemType)
Create an expression for a parameter which must be an entity of a specified type.

Parameters:
name - The name of the parameter. Can not be null
itemType - The type of the
Returns:
An expression representing the parameter
Throws:
InvalidDataException - If the 'name' is null or contains invalid characters or if 'itemType' is null
Since:
2.17

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

size

public static Expression size(String alias,
                              String property)
                       throws InvalidDataException
Create a size 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 size of the collection
Throws:
InvalidDataException - If both the alias and property parameters are null or if any of them contains invalid characters
Since:
2.7

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

innerJoin

public static Join innerJoin(String alias,
                             String property,
                             String joinedAlias,
                             boolean fetch)
                      throws InvalidDataException
Same as innerJoin(null, propert, joinedAlias, null, false)

Throws:
InvalidDataException
See Also:
innerJoin(String, String, String, Restriction, boolean)

innerJoin

public static Join innerJoin(String alias,
                             String property,
                             String joinedAlias,
                             Restriction on,
                             boolean fetch)
                      throws InvalidDataException
Create an inner join query element and optionally prefetch the joined items in the same query. This is useful to avoid subsequent queries to the database when you know that you are going to access the joined items in your code. If you are joining a collection the Query.setFirstResult(int) and Query.setMaxResults(int) shouldn't be used since the join will create multiple rows for the same root item.

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
fetch - If the joined items should be prefetched or not
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
Since:
2.8

leftJoin

public static Join leftJoin(String property,
                            String joinedAlias)
                     throws InvalidDataException
Same as leftJoin(null, propert, joinedAlias, null, false)

Throws:
InvalidDataException
See Also:
leftJoin(String, String, String, Restriction, boolean)

leftJoin

public static Join leftJoin(String alias,
                            String property,
                            String joinedAlias,
                            Restriction on,
                            boolean fetch)
                     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

The fetch parameter is used to fetch the joined data in the same query. This is useful to avoid subsequent queries to the database when you know that you are going to access the joined items in your code. If you are joining a collection the Query.setFirstResult(int) and Query.setMaxResults(int) shouldn't be used since the join will create multiple rows for the same root item.

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
fetch - If the joined items should be prefetched or not
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

restriction

public static Restriction restriction(String restrictionString,
                                      String prefix)
Parameters:
restrictionString - A restriction as a string. Null or empty string is not allowed.
prefix - Prefix used in the restriction string. The prefix will be replaced in the returned object by the query's root-alias. Null is allowed.
Returns:
a Restriction to use in a query.
Since:
2.5

expression

public static Expression expression(String exprString,
                                    String prefix)
Parameters:
exprString - An expression as a string. Null or empty string is not allowed.
prefix - Prefix used in the expression string. The prefix will be replaced in the returned object by the query's root-alias. Null is allowed.
Returns:
an Object implementing Expression.
Since:
2.5

isPartOf

public static Restriction isPartOf(String alias,
                                   String property,
                                   ReporterList reporterList)

isNotPartOf

public static Restriction isNotPartOf(String alias,
                                      String property,
                                      ReporterList reporterList)

sharedTo

public static Restriction sharedTo(boolean sharedTo,
                                   Restriction users,
                                   Restriction groups,
                                   Restriction projects)
A special restriction that works on Shareable items. The restriction is used to find items that have or have not been shared to users/groups and/or projects that meet some specific criteria.

Parameters:
sharedTo - TRUE to finds items that have been shared to at least one of the matching users/groups/projects, FALSE to find items that are not shared to any of the matching users/groups/projects. If all three restrictions are null, a value of TRUE will find items that are not shared and FALSE will find items that are shared to anyone.
users - A restriction to apply on the subquery that is matching users, or null to not match against users
groups - A restriction to apply on the subquery that is matching groups, or null to not match against groups
projects - A restriction to apply on the subquery that is matching projects, or null to not match against projects
Returns:
A restriction
Since:
2.15

2.17.2: 2011-06-17