OmeroBlitz API
Home Previous Up Next Index

omero::api::IQuery

Overview

[ "ami", "amd" ] 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 inconsistent state, but may provide stale data in some situations. By convention, all methods that begin with get will never return a null or empty java::util::Collection, but instead will throw a ValidationException.

Operation Index

get
Looks up an entity by class and id.
find
Looks up an entity by class and id.
findAll
Looks up all entities that belong to this class and match filter.
findByExample
Searches based on provided example entity.
findAllByExample
Searches based on provided example entity.
findByString
Searches a given field matching against a String.
findAllByString
Searches a given field matching against a String.
findByQuery
Executes the stored query with the given name.
findAllByQuery
Executes the stored query with the given name.
findAllByFullText
Executes a full text search based on Lucene.
projection
Return a sequence of RType sequences.
refresh
Refreshes an entire model::IObject graph, recursive loading all data for the managed instances in the graph from the database.

Operations

model::IObject get(string klass, long id) throws ServerError

Looks up 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

Return Value

an initialized entity

Exceptions

ValidationException
if the id doesn't exist.

model::IObject find(string klass, long id) throws ServerError

Looks up 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

Return Value

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

IObjectList findAll(string klass, sys::Filter filter) throws ServerError

Looks up 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.

Return Value

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

model::IObject findByExample(model::IObject example) throws ServerError

Searches 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 {@code find}, {@code get}, {@code findByQuery}, or {@code findAllByQuery}.

Parameters

example
Non-null example object.

Return Value

Possibly null IObject result.

Exceptions

ApiUsageException
if more than one result is return.

IObjectList findAllByExample(model::IObject example, sys::Filter filter) throws ServerError

Searches based on provided example entity. The returned entities will be limited by the sys::Filter object. Note: findAllbyExample does not operate on the id field. For that, use {@code find}, {@code get}, {@code findByQuery}, or {@code findAllByQuery}.

Parameters

example
Non-null example object.
filter
filters the result set. Can be null.

Return Value

Possibly empty List of IObject results.

model::IObject findByString(string klass, string field, string value) throws ServerError

Searches 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. {@code omero.model.Project.NAME}

Parameters

klass
type of entity to be searched
field
the name of the field, either as simple string or as public static final from the entity class, e.g. {
value
String used for search.

Return Value

found entity or possibly null.

Exceptions

ome::conditions::ApiUsageException
if more than one result.

IObjectList findAllByString(string klass, string field, string value, bool caseSensitive, sys::Filter filter) throws ServerError

Searches 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 sys::Filter instance. {@code omero.model.Project.NAME}. Not null.

Parameters

klass
type of entity to be searched. Not null.
field
the name of the field, either as simple string or as public static final from the entity class, e.g. {
value
String used for search. Not null.
caseSensitive
whether to use LIKE or ILIKE
filter
filters the result set. Can be null.

Return Value

A list (possibly empty) with the results.

model::IObject findByQuery(string query, sys::Parameters params) throws ServerError

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

query
Query to execute

Return Value

Possibly null IObject result.

Exceptions

IObjectList findAllByQuery(string query, sys::Parameters params) throws ServerError

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 model::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

query
Query to execute. Not null.

Return Value

Possibly empty List of IObject results.

IObjectList findAllByFullText(string klass, string query, sys::Parameters params) throws ServerError

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:

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

Parameters

klass
A non-null class specification of which type should be searched.
query
A non-null query string. An empty string will return no results.
params
Currently the parameters themselves are unused. But the sys::Parameters::theFilter can be used to limit the number of results returned (sys::Filter::limit) or the user for who the results will be found (sys::Filter::ownerId).

Return Value

A list of loaded model::IObject instances. Never null.

RTypeSeqSeq projection(string query, sys::Parameters params) throws ServerError

Return a sequence of RType sequences.

Each element of the outer sequence is one row in the return value. Each element of the inner sequence is one column specified in the HQL.

model::IObject instances are returned wrapped in an RObject instance. Primitives are mapped to the expected RType subclass. Types without an RType mapper if returned will throw an exception if present in the select except where a manual conversion is present on the server. This includes:

As with SQL, 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

model::IObject refresh(model::IObject iObject) throws ServerError

Refreshes an entire model::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 model::IObject graph which should have all values re-assigned from the database

Return Value

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

Exceptions

ApiUsageException
if any non-managed entities are found.

Home Previous Up Next Index