ome.api

Interface IQuery

All Superinterfaces:

ServiceInterface

All Known Subinterfaces:

LocalQuery

All Known Implementing Classes:

QueryImpl

public interface IQuery
extends ServiceInterface

Provides methods for directly querying object graphs. As far as is possible, IQuery should be considered the lowest level DB-access (SELECT) interface. Unlike the IUpdate interface, using other methods will most likely not leave the database in an inconsitent state, but may provide stale data in some situations. By convention, all methods that begin with get will never return a null or empty Collection, but instead will throw a ValidationException.

Since:

3.0

Version:

3.0

Author:

Josh Moore josh.moore@gmx.de

See Also:

Filter, Parameters, QueryParameter

Method Summary

Modifier and Type	Method and Description
<T extends IObject> T	find(java.lang.Class<T> klass, long id) lookup an entity by class and id.
<T extends IObject> java.util.List<T>	findAll(java.lang.Class<T> klass, Filter filter) lookup all entities that belong to this class and match filter.
<T extends IObject> java.util.List<T>	findAllByExample(T example, Filter filter) search based on provided example entity.
<T extends IObject> java.util.List<T>	findAllByFullText(java.lang.Class<T> type, java.lang.String query, Parameters parameters) executes a full text search based on Lucene.
<T extends IObject> java.util.List<T>	findAllByQuery(java.lang.String queryName, Parameters parameters) executes the stored query with the given name.
<T extends IObject> java.util.List<T>	findAllByString(java.lang.Class<T> klass, java.lang.String field, java.lang.String stringValue, boolean caseSensitive, Filter filter) search a given field matching against a String.
<T extends IObject> T	findByExample(T example) search based on provided example entity.
<T extends IObject> T	findByQuery(java.lang.String queryName, Parameters parameters) executes the stored query with the given name.
<T extends IObject> T	findByString(java.lang.Class<T> klass, java.lang.String field, java.lang.String value) search a given field matching against a String.
<T extends IObject> T	get(java.lang.Class<T> klass, long id) lookup an entity by class and id.
java.util.List<java.lang.Object[]>	projection(java.lang.String query, Parameters parameters) Return a list of Java Object instances (not IObject instances).
<T extends IObject> T	refresh(T iObject) refreshes an entire IObject graph, recursive loading all data for the managed instances in the graph from the database.

Method Detail

get

<T extends IObject> T get(java.lang.Class<T> klass,
                          long id)
                   throws ValidationException

lookup an entity by class and id. If no such object exists, an exception will be thrown.

Parameters:

klass - the type of the entity. Not null.

id - the entity's id

Returns:

an initialized entity

Throws:

ValidationException - if the id doesn't exist.

find

<T extends IObject> T find(java.lang.Class<T> klass,
                           long id)

lookup an entity by class and id. If no such objects exists, return a null.

Parameters:

klass - klass the type of the entity. Not null.

id - the entity's id

Returns:

an initialized entity or null if id doesn't exist.

findAll

<T extends IObject> java.util.List<T> findAll(java.lang.Class<T> klass,
                                              Filter filter)

lookup all entities that belong to this class and match filter.

Parameters:

klass - entity type to be searched. Not null.

filter - filters the result set. Can be null.

Returns:

a collection if initialized entities or an empty List if none exist.

findByExample

<T extends IObject> T findByExample(T example)
                             throws ApiUsageException

search based on provided example entity. The example entity should uniquely specify the entity or an exception will be thrown. Note: findByExample does not operate on the id field. For that, use find(Class, long), get(Class, long), findByQuery(String, Parameters), or findAllByQuery(String, Parameters)

Parameters:

example - Non-null example object.

Returns:

Possibly null IObject result.

Throws:

ApiUsageException - if more than one result is return.

findAllByExample

<T extends IObject> java.util.List<T> findAllByExample(T example,
                                                       Filter filter)

search based on provided example entity. The returned entities will be limited by the Filter object. Note: findAllbyExample does not operate on the id field. For that, use find(Class, long), get(Class, long), findByQuery(String, Parameters), or findAllByQuery(String, Parameters)

Parameters:

example - Non-null example object.

filter - filters the result set. Can be null.

Returns:

Possibly empty List of IObject results.

findByString

<T extends IObject> T findByString(java.lang.Class<T> klass,
                                   java.lang.String field,
                                   java.lang.String value)
                            throws ApiUsageException

search a given field matching against a String. Method does not allow for case sensitive or insensitive searching since this is essentially a lookup. The existence of more than one result will result in an exception.

Parameters:

klass - type of entity to be searched

field - the name of the field, either as simple string or as public final static from the entity class, e.g. Project.NAME

value - String used for search.

Returns:

found entity or possibly null.

Throws:

ApiUsageException - if more than one result.

findAllByString

<T extends IObject> java.util.List<T> findAllByString(java.lang.Class<T> klass,
                                                      java.lang.String field,
                                                      java.lang.String stringValue,
                                                      boolean caseSensitive,
                                                      Filter filter)

search a given field matching against a String. Method allows for case sensitive or insensitive searching using the (I)LIKE comparators. Result set will be reduced by the Filter instance.

Parameters:

klass - type of entity to be searched. Not null.

field - the name of the field, either as simple string or as public final static from the entity class, e.g. Project.NAME. Not null.

stringValue - String used for search. Not null.

caseSensitive - whether to use LIKE or ILIKE

filter - filters the result set. Can be null.

Returns:

A list (possibly empty) with the results.

findByQuery

<T extends IObject> T findByQuery(java.lang.String queryName,
                                  Parameters parameters)
                           throws ValidationException

executes the stored query with the given name. If a query with the name cannot be found, an exception will be thrown. The queryName parameter can be an actual query String if the StringQuerySource is configured on the server and the user running the query has proper permissions.

Parameters:

queryName - String identifier of the query to execute

parameters - array of QueryParameter. Not null. The QueryParameter.name field maps to a field-name which is then matched against the QueryParameter.value

Returns:

Possibly null IObject result.

Throws:

ValidationException

findAllByQuery

<T extends IObject> java.util.List<T> findAllByQuery(java.lang.String queryName,
                                                     Parameters parameters)

executes the stored query with the given name. If a query with the name cannot be found, an exception will be thrown. The queryName parameter can be an actual query String if the StringQuerySource is configured on the server and the user running the query has proper permissions. Queries can only return lists of IObject instances. This means all must be of the form:

 select this from SomeModelClass this ...
 

though the alias "this" is unimportant. Do not try to return multiple classes in one call like:

 select this, that from SomeClass this, SomeOtherClass that ...
 

nor to project values out of an object:

 select this.name from SomeClass this ...
 

If a page is desired, add it to the query parameters.

Parameters:

queryName - String identifier of the query to execute. Not null.

parameters - array of QueryParameter. The QueryParameter.name field maps to a field-name which is then matched against the QueryParameter.value

Returns:

Possibly empty List of IObject results.

findAllByFullText

<T extends IObject> java.util.List<T> findAllByFullText(java.lang.Class<T> type,
                                                        java.lang.String query,
                                                        Parameters parameters)

executes a full text search based on Lucene. Each term in the query can also be prefixed by the name of the field to which is should be restricted. Examples:

• owner:root AND annotation:someTag
• file:xml AND name:*hoechst*

For more information, see Query Parser Synax The return values are first filtered by the security system.

Type Parameters:

T -

Parameters:

type - A non-null class specification of which type should be searched.

query - A non-null query string. An empty string will return no results.

parameters - Currently the parameters themselves are unusued. But the Parameters.filter can be used to limit the number of results returned (Filter.limit) or the user for who the results will be found (Filter.owner()).

Returns:

A list of loaded IObject instances. Never null.

projection

java.util.List<java.lang.Object[]> projection(java.lang.String query,
                                              Parameters parameters)

Return a list of Java Object instances (not IObject instances). These are the column names as specified in the HQL select statement (more than one is required). If an aggregation statement is used, a group by clause must be added. Examples:

• select i.name, i.description from Image i where i.name like '%.dv'
• select tag.textValue, tagset.textValue from TagAnnotation tag join tag.annotationLinks l join l.child tagset
• select p.pixelsType.value, count(p.id) from Pixel p group by p.pixelsType.value

refresh

<T extends IObject> T refresh(T iObject)
                       throws ApiUsageException

refreshes an entire IObject graph, recursive loading all data for the managed instances in the graph from the database. If any non-managed entities are detected (e.g. without ids), an ApiUsageException will be thrown.

Parameters:

iObject - Non-null managed IObject graph which should have all values re-assigned from the database

Returns:

a similar IObject graph (with possible additions and deletions) which is in-sync with the database.

Throws:

ApiUsageException - if any non-managed entities are found.