ome.services.query

Class Query<T>

java.lang.Object

ome.services.query.Query<T>

All Implemented Interfaces:

org.springframework.orm.hibernate3.HibernateCallback

Direct Known Subclasses:

AbstractClassIdsOptionsQuery, CollectionCountQueryDefinition, IObjectClassQuery, PojosFindAnnotationsQueryDefinition, PojosGetImagesByOptionsQueryDefinition, PojosGetUserImagesQueryDefinition, PojosLoadHierarchyQueryDefinition, StringQuery

public abstract class Query<T>
extends Object
implements org.springframework.orm.hibernate3.HibernateCallback

base Query type to facilitate the creation of ORM queries. This class attempts to enforce a strict usage pattern. First, subclasses must define a Definitions instance, which can optionally (and perhaps preferrably) be static, which must be passed into the super constructor along with the Parameters provided during lookup.

Queries can optionally define a enableFilters(Session) method (perhaps using pre-defined filters like #ownerOrGroupFilters(Session, String[]) to limit the entities returned.

Since:

OMERO 3.0

Version:

1.0 (Internal version: $Rev$ $Date$)

Author:

Josh Moore, josh.moore@gmx.de

Field Summary

Fields

Modifier and Type	Field and Description
protected Definitions	defs container of QueryParameterDef instances.
protected static org.hibernate.FetchMode	FETCH imported constant for ease of use
protected static int	INNER_JOIN imported constant for ease of use
protected static int	LEFT_JOIN imported constant for ease of use
protected Set<String>	newlyEnabledFilters the set of filters that is being or has been enabled for this Query.
protected Parameters	params container of QueryParameter instances.

Constructor Summary

Constructors

Constructor and Description
Query(Definitions definitions, Parameters parameters) main constructor used by subclasses.

Method Summary

Methods

Modifier and Type	Method and Description
protected abstract void	buildQuery(org.hibernate.Session session) main point of entry for subclasses.
boolean	check(String name) check that there is a definition for this Query with the provided argument as its name.
protected void	checkParameters() check the Parameters instance against the Definitions instance for this Query.
protected void	disableFilters(org.hibernate.Session session) turns the filters off that are listed in newlyEnabledFilters
Object	doInHibernate(org.hibernate.Session session) template method defined by HibernateTemplate.
protected void	enableFilters(org.hibernate.Session session) does nothing by default, but can be overridden by subclasses to enable particular filters.
QueryParameter	get(String name) get the QueryParameter for this name argument.
protected void	ownerOrGroupFilters(org.hibernate.Session session, String[] ownerFilters, String[] groupFilters) standard filter used by many subclasses which uses the PojoOptions#isExperimenter() and PojoOptions#isGroup() booleans to see if a filter should be turned on.
protected void	setCriteria(org.hibernate.Criteria criteria) provide this Query instance with a Criteria to be used for retrieving data.
protected void	setQuery(org.hibernate.Query query) provide this Query instance with a Query to be used for retrieving data.
Object	value(String name) get the Object value for this name argument.

Methods inherited from class java.lang.Object

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

Field Detail

FETCH

protected static final org.hibernate.FetchMode FETCH

imported constant for ease of use

See Also:

FetchMode.JOIN

LEFT_JOIN

protected static final int LEFT_JOIN

imported constant for ease of use

See Also:

CriteriaSpecification.LEFT_JOIN, Constant Field Values

INNER_JOIN

protected static final int INNER_JOIN

imported constant for ease of use

See Also:

CriteriaSpecification.INNER_JOIN, Constant Field Values

defs

protected final Definitions defs

container of QueryParameterDef instances. Typically created statically in Query subclasses and passed to the Query(Definitions, Parameters) constructor

params

protected final Parameters params

container of QueryParameter instances. These must at least cover all the QueryParameterDefs defined for this Query but can define more. Other special fields of Parameters, such as a Filter instance can also be used by Query instances.

newlyEnabledFilters

protected Set<String> newlyEnabledFilters

the set of filters that is being or has been enabled for this Query.

Constructor Detail

Query

public Query(Definitions definitions,
     Parameters parameters)

main constructor used by subclasses. Both arguments must be provided.

Parameters:

definitions - Not null.

parameters - Not null.

Method Detail

checkParameters

protected void checkParameters()

check the Parameters instance against the Definitions instance for this Query. Can be extended by subclasses, but super.checkParameters() should most likely be called.

check

public boolean check(String name)

check that there is a definition for this Query with the provided argument as its name.

get

public QueryParameter get(String name)

get the QueryParameter for this name argument.

value

public Object value(String name)

get the Object value for this name argument. Returns null even if no QueryParameter is associated with the name (no exception).

doInHibernate

public Object doInHibernate(org.hibernate.Session session)
                     throws org.hibernate.HibernateException,
                            SQLException

template method defined by HibernateTemplate. This does not need to be overridden by subclasses, but rather buildQuery(Session). This ensures that the filters are set properly, that buildQuery(Session) does its job, and that everything is cleaned up properly afterwards. It also enforces contracts established by Parameters and Filter

Specified by:

doInHibernate in interface org.springframework.orm.hibernate3.HibernateCallback

Parameters:

session - active Hibernate session

Returns:

a result object, or null if none

Throws:

org.hibernate.HibernateException - if thrown by the Hibernate API

SQLException - if thrown by Hibernate-exposed JDBC API

See Also:

HibernateTemplate.execute(org.springframework.orm.hibernate3.HibernateCallback<T>), HibernateTemplate.executeFind(org.springframework.orm.hibernate3.HibernateCallback<?>)

buildQuery

protected abstract void buildQuery(org.hibernate.Session session)
                            throws org.hibernate.HibernateException,
                                   SQLException

main point of entry for subclasses. This method must build either a Criteria or a Query instance and make it available via setCriteria(org.hibernate.Criteria) or setQuery(org.hibernate.Query)

Throws:

org.hibernate.HibernateException

SQLException

setQuery

protected void setQuery(org.hibernate.Query query)

provide this Query instance with a Query to be used for retrieving data. setCriteria(org.hibernate.Criteria) should not also be called with a non-null value.

setCriteria

protected void setCriteria(org.hibernate.Criteria criteria)

provide this Query instance with a Criteria to be used for retrieving data. setQuery(org.hibernate.Query) should not also be called with a non-null value.

enableFilters

protected void enableFilters(org.hibernate.Session session)

does nothing by default, but can be overridden by subclasses to enable particular filters.

ownerOrGroupFilters

protected void ownerOrGroupFilters(org.hibernate.Session session,
                       String[] ownerFilters,
                       String[] groupFilters)

standard filter used by many subclasses which uses the PojoOptions#isExperimenter() and PojoOptions#isGroup() booleans to see if a filter should be turned on. If both booleans are active, group wins. The constant Parameters.OWNER_ID or Parameters.GROUP_ID is then used to define a filter.

disableFilters

protected void disableFilters(org.hibernate.Session session)

turns the filters off that are listed in newlyEnabledFilters