Search (OMERO API)

All Superinterfaces:

Iterator<IObject>, ServiceInterface, StatefulServiceInterface

All Known Implementing Classes:

SearchBean
```
public interface Search
extends StatefulServiceInterface, Iterator<IObject>
```
Central search interface, allowing Web2.0 style queries. Each Search instance keeps up with several queries and lazily-loads the results as hasNext(), next() and results() are called. These queries are created by the "by*" methods. Each instance also has a number of settings which can all be changed from their defaults via accessors, e.g.setBatchSize(int) or setCaseSentivice(boolean). The only methods which are required for the proper functioning of a Search instance are:
- onlyType(Class), onlyTypes(Class...) OR allTypes()
- Any by* method to create a query
Use of the allTypes() method is discouraged, since it is possibly very resource intensive, which is why any attempt to receive results without specifically setting types or allowing all is prohibited.
Since:

3.0-Beta3

Author:

Josh Moore, josh at glencoesoftware.com

See Also:

IQuery

Field Summary

Fields
Modifier and Type	Field and Description
`static boolean`	`ALLOW_LEADING_WILDCARD` Default `leading-wildcard setting`
`static String`	`DATE_TYPE_ACQUISITION` Treat date range as acquisition date
`static String`	`DATE_TYPE_IMPORT` Treat date range as import date
`static int`	`DEFAULT_BATCH_SIZE` Default `batch size`
`static boolean`	`DEFAULT_CASE_SENSITIVTY` Default `case sensitivity`
`static boolean`	`DEFAULT_MERGED_BATCHES` Default `merged-batches`
`static boolean`	`DEFAULT_RETURN_UNLOADED` Default `return-unloaded`
`static boolean`	`DEFAULT_USE_PROJECTIONS` Default `use-projections`
`static String`	`SCORE` `String` constant used to look up the score value of Lucene queries returned by this interface.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`int`	`activeQueries()` Returns the number of active queries.
`void`	`addOrderByAsc(String path)` A path from the target entity which will be added to the current stack of order statements applied to the query.
`void`	`addOrderByDesc(String path)` A path from the target entity which will be added to the current stack of order statements applied to the query.
`void`	`allTypes()` Permits all types to be returned.
`void`	`and()` Applies the next by* method to the previous by* method, so that a call `hasNext()`, `next()`, or `results()` sees only the intersection of the two calls.
`void`	`byAnnotatedWith(Annotation... examples)` Finds entities annotated with an `Annotation` similar to the example.
`void`	`byFullText(String query)` Passes the query as is to the Lucene backend.
`void`	`byGroupForTags(String group)` Returns transient (without ID) `TagAnnotation` instances which represent all the `tags` in the given group.
`void`	`byHqlQuery(String query, Parameters p)` Delegates to `IQuery.findAllByQuery(String, Parameters)` method to take advantage of the `and()`, `or()`, and `not()` methods, or queue-semantics.
`void`	`byLuceneQueryBuilder(String fields, String from, String to, String dateType, String query)` Builds a Lucene query and passes it to the Lucene backend.
`void`	`bySimilarTerms(String... terms)` Returns transient (without ID) `TextAnnotation` instances which represent terms which are similar to the given terms.
`void`	`bySomeMustNone(String[] some, String[] must, String[] none)` Builds a Lucene query and passes it to `byFullText(String)`.
`void`	`byTagForGroups(String tag)` Creates a query which will return transient (without ID) `TagAnnotation` instances which represent all the `tag groups` which the given tag belongs to.
`void`	`clearQueries()` Removes all active queries (leaving `settings` alone), such that `activeQueries()` will return 0.
`Map<String,Annotation>`	`currentMetadata()` Provides access to the extra query information (for example Lucene score and boost values) for a single call to `next()`.
`List<Map<String,Annotation>>`	`currentMetadataList()` Provides access to the extra query information (for example Lucene score and boost values) for a single call to `results()`.
`void`	`fetchAlso(String... fetches)` Adds a fetch clause for loading non-annotation fields of returned entities.
`void`	`fetchAnnotations(Class... classes)` Queries the database for all `annotations` of the given types for all returned instances.
`int`	`getBatchSize()` Returns the current batch size.
`boolean`	`hasNext()` Returns true if another call to `next()` is valid.
`boolean`	`isAllowLeadingWildcard()` Returns the current leading-wildcard setting.
`boolean`	`isCaseSensitive()` Returns the current case sensitivity setting.
`boolean`	`isMergedBatches()` Returns the current merged-batches setting.
`boolean`	`isReturnUnloaded()` Returns the current return-unloaded setting.
`boolean`	`isUseProjections()` Returns the current use-projection setting.
`IObject`	`next()` Returns the next entity from the current query.
`void`	`not()` Applies the next by* method to the previous by* method, so that a call `hasNext()`, `next()`, or `results()` sees only the intersection of the two calls.
`void`	`notAnnotatedBy(Details d)` Restricts entities by who has not annotated them with an `Annotation` matching the other filters.
`void`	`notOwnedBy(Details d)` Uses the `Details.getOwner()` and `Details.getGroup()` information to restrict the entities which will be returned.
`void`	`onlyAnnotatedBetween(Timestamp start, Timestamp stop)` Restricts entities by the time in which any annotation (which matches the other filters) was added them.
`void`	`onlyAnnotatedBy(Details d)` Restricts entities by who has annotated them with an `Annotation` matching the other filters.
`void`	`onlyAnnotatedWith(Class... classes)` Restricts entities to having an `Annotation` of all the given types.
`void`	`onlyCreatedBetween(Timestamp start, Timestamp stop)` Restricts the time between which an entity may have been created.
`void`	`onlyIds(Long... ids)` Restricts the set of `ids` which will be checked.
`void`	`onlyModifiedBetween(Timestamp start, Timestamp stop)` Restricts the time between which an entity may have last been modified.
`void`	`onlyOwnedBy(Details d)` Uses the `Details.getOwner()` and `Details.getGroup()` information to restrict the entities which will be returned.
`<T extends IObject> void`	`onlyType(Class<T> klass)` Restricts the search to a single type.
`<T extends IObject> void`	`onlyTypes(Class<T>... classes)` Restricts searches to a set of types.
`void`	`or()` Applies the next by* method to the previous by* method, so that a call `hasNext()`, `next()`, or `results()` sees only the union of the two calls.
`void`	`remove()` Unsupported operation.
`void`	`resetDefaults()` Resets all settings (non-query state) to the original default values, as if the instance had just be created.
`<T extends IObject> List<T>`	`results()` Returns up to `batch size` number of results along with the related query metadata.
`void`	`setAllowLeadingWildcard(boolean allowLeadingWildcard)` Permits full-text queries with a leading query if true.
`void`	`setBatchSize(int size)` Sets the maximum number of results that will be returned by one call to `results()`.
`void`	`setCaseSentivice(boolean caseSensitive)` Sets the case sensitivity on all queries where case-sensitivity is supported.
`void`	`setMergedBatches(boolean merge)` Set whether or not results from two separate queries can be returned in the same call to `results()`.
`void`	`setReturnUnloaded(boolean returnUnloaded)` Determines if all results should be returned as unloaded objects.
`void`	`setUseProjections(boolean useProjections)` Determines if Lucene queries should not hit the database.
`void`	`unordered()` Removes the current stack of order statements.

Methods inherited from interface ome.api.StatefulServiceInterface
activate, close, getCurrentEventContext, passivate

Methods inherited from interface java.util.Iterator
forEachRemaining

- Field Detail
  - SCORE
```
static final String SCORE
```
    String constant used to look up the score value of Lucene queries returned by this interface. Not all queries will fill this value.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_BATCH_SIZE
```
static final int DEFAULT_BATCH_SIZE
```
    Default batch size
    
    See Also:
    
    Constant Field Values
  - DEFAULT_MERGED_BATCHES
```
static final boolean DEFAULT_MERGED_BATCHES
```
    Default merged-batches
    
    See Also:
    
    Constant Field Values
  - DEFAULT_CASE_SENSITIVTY
```
static final boolean DEFAULT_CASE_SENSITIVTY
```
    Default case sensitivity
    
    See Also:
    
    Constant Field Values
  - DEFAULT_USE_PROJECTIONS
```
static final boolean DEFAULT_USE_PROJECTIONS
```
    Default use-projections
    
    See Also:
    
    Constant Field Values
  - DEFAULT_RETURN_UNLOADED
```
static final boolean DEFAULT_RETURN_UNLOADED
```
    Default return-unloaded
    
    See Also:
    
    Constant Field Values
  - ALLOW_LEADING_WILDCARD
```
static final boolean ALLOW_LEADING_WILDCARD
```
    Default leading-wildcard setting
    
    See Also:
    
    Constant Field Values
  - DATE_TYPE_IMPORT
```
static final String DATE_TYPE_IMPORT
```
    Treat date range as import date
    
    See Also:
    
    Constant Field Values
  - DATE_TYPE_ACQUISITION
```
static final String DATE_TYPE_ACQUISITION
```
    Treat date range as acquisition date
    
    See Also:
    
    Constant Field Values
- Method Detail
  - activeQueries
```
int activeQueries()
```
    Returns the number of active queries. This means that activeQueries gives the minimum number of remaining calls to results() when batches are not merged.
    
    Returns:
    
    number of active queries
  - setBatchSize
```
void setBatchSize(int size)
```
    Sets the maximum number of results that will be returned by one call to results(). If batches are not merged, then results may often be less than the batch size. If batches are merged, then only the last call to results() can be less than batch size. Note: some query types may not support batching at the query level, and all instances must then be loaded into memory simultaneously.
    
    Parameters:
    
    size - maximum number of results per call to results()
  - getBatchSize
```
int getBatchSize()
```
    Returns the current batch size. If setBatchSize(int) has not been called, the default value will be in effect.
    
    Returns:
    
    maximum number of results per call to results()
    
    See Also:
    
    DEFAULT_BATCH_SIZE
  - setMergedBatches
```
void setMergedBatches(boolean merge)
```
    Set whether or not results from two separate queries can be returned in the same call to results().
  - isMergedBatches
```
boolean isMergedBatches()
```
    Returns the current merged-batches setting. If setMergedBatches(boolean) has not been called, the default value will be in effect.
  - setCaseSentivice
```
void setCaseSentivice(boolean caseSensitive)
```
    Sets the case sensitivity on all queries where case-sensitivity is supported.
  - isCaseSensitive
```
boolean isCaseSensitive()
```
    Returns the current case sensitivity setting. If setCaseSentivice(boolean) has not been called, the default value will be in effect.
  - setUseProjections
```
void setUseProjections(boolean useProjections)
```
    Determines if Lucene queries should not hit the database. Instead all values which are stored in the index will be loaded into the object, which includes the id. However, the entity will not be marked unloaded and therefore it is especially important to not allow a projection-instance to be saved back to the server. This can result in DATA LOSS.
  - isUseProjections
```
boolean isUseProjections()
```
    Returns the current use-projection setting. If true, the client must be careful with all results that are returned. See for more. If setUseProjections(boolean) has not been called, the DEFAULT_USE_PROJECTIONS will be in effect.
  - setReturnUnloaded
```
void setReturnUnloaded(boolean returnUnloaded)
```
    Determines if all results should be returned as unloaded objects. This is particularly useful for creating lists for further querying via IQuery. This value overrides the setUseProjections(boolean) setting.
  - isReturnUnloaded
```
boolean isReturnUnloaded()
```
    Returns the current return-unloaded setting. If true, all returned entities will be unloaded. If setReturnUnloaded(boolean) has not been called, the default value will be in effect.
  - setAllowLeadingWildcard
```
void setAllowLeadingWildcard(boolean allowLeadingWildcard)
```
    Permits full-text queries with a leading query if true.
    
    See Also:
    
    isAllowLeadingWildcard(), byFullText(String), bySomeMustNone(String[], String[], String[])
  - isAllowLeadingWildcard
```
boolean isAllowLeadingWildcard()
```
    Returns the current leading-wildcard setting. If false, byFullText(String) and bySomeMustNone(String[], String[], String[]) will throw an ApiUsageException, since leading-wildcard searches are quite slow. Use setAllowLeadingWildcard(boolean) in order to permit this usage.
  - onlyType
```
<T extends IObject> void onlyType(Class<T> klass)
```
    Restricts the search to a single type. All return values will match this type.
  - onlyTypes
```
<T extends IObject> void onlyTypes(Class<T>... classes)
```
    Restricts searches to a set of types. The entities returned are guaranteed to be one of these types.
  - allTypes
```
void allTypes()
```
    Permits all types to be returned. For some types of queries, this carries a performance penalty as every database table must be hit.
  - onlyIds
```
void onlyIds(Long... ids)
```
    Restricts the set of ids which will be checked. This is useful for testing one of the given restrictions on a reduced set of objects.
    
    Parameters:
    
    ids - Can be null, in which case the previous restriction is removed.
  - onlyOwnedBy
```
void onlyOwnedBy(Details d)
```
    Uses the Details.getOwner() and Details.getGroup() information to restrict the entities which will be returned. If both are non-null, the two restrictions are joined by an AND.
    
    Parameters:
    
    d - Can be null, in which case the previous restriction is removed.
  - notOwnedBy
```
void notOwnedBy(Details d)
```
    Uses the Details.getOwner() and Details.getGroup() information to restrict the entities which will be returned. If both are non-null, the two restrictions are joined by an AND.
    
    Parameters:
    
    d - Can be null, in which case the previous restriction is removed.
  - onlyCreatedBetween
```
void onlyCreatedBetween(Timestamp start,
                        Timestamp stop)
```
    Restricts the time between which an entity may have been created.
    
    Parameters:
    
    start - Can be null, i.e. interval open to negative infinity.
    
    stop - Can be null, i.e. interval opens to positive infinity.
  - onlyModifiedBetween
```
void onlyModifiedBetween(Timestamp start,
                         Timestamp stop)
```
    Restricts the time between which an entity may have last been modified.
    
    Parameters:
    
    start - Can be null, i.e. interval open to negative infinity.
    
    stop - Can be null, i.e. interval open to positive infinity.
  - onlyAnnotatedBetween
```
void onlyAnnotatedBetween(Timestamp start,
                          Timestamp stop)
```
    Restricts entities by the time in which any annotation (which matches the other filters) was added them. This matches the creation event of the Annotation.
    
    Parameters:
    
    start - Can be null, i.e. interval open to negative infinity.
    
    stop - Can be null, i.e. interval open to positive infinity.
  - onlyAnnotatedBy
```
void onlyAnnotatedBy(Details d)
```
    Restricts entities by who has annotated them with an Annotation matching the other filters. As onlyOwnedBy(Details), the Details.getOwner() and Details.getGroup() information is combined with an AND condition.
    
    Parameters:
    
    d - Can be null, in which case any previous restriction is removed.
  - notAnnotatedBy
```
void notAnnotatedBy(Details d)
```
    Restricts entities by who has not annotated them with an Annotation matching the other filters. As notOwnedBy(Details), the Details.getOwner() and Details.getGroup() information is combined with an AND condition.
    
    Parameters:
    
    d - Can be null, in which case any previous restriction is removed.
  - onlyAnnotatedWith
```
void onlyAnnotatedWith(Class... classes)
```
    Restricts entities to having an Annotation of all the given types. This is useful in combination with the other onlyAnnotated* methods to say, e.g., only annotated with a file by user X. By default, this value is null and imposes no restriction. Passing an empty array implies an object that is not annotated at all. Note: If the semantics were OR, then a client would have to query each class individually, and compare all the various values, checking which ids are where. However, since this method defaults to AND, multiple calls (optionally with isMergedBatches() and isReturnUnloaded()) and combine the results. Duplicate ids are still possible, so a set of some form should be used to collect the results.
    
    Parameters:
    
    classes - Can be empty, in which case restriction is removed.
  - addOrderByAsc
```
void addOrderByAsc(String path)
```
    A path from the target entity which will be added to the current stack of order statements applied to the query.
    
    Parameters:
    
    path - Non-null.
    
    See Also:
    
    unordered()
  - addOrderByDesc
```
void addOrderByDesc(String path)
```
    A path from the target entity which will be added to the current stack of order statements applied to the query.
    
    Parameters:
    
    path - Non-null.
    
    See Also:
    
    unordered()
  - unordered
```
void unordered()
```
    Removes the current stack of order statements.
    
    See Also:
    
    addOrderByAsc(String), addOrderByDesc(String)
  - fetchAnnotations
```
void fetchAnnotations(Class... classes)
```
    Queries the database for all annotations of the given types for all returned instances.
    
    Parameters:
    
    classes - Can be empty, which removes previous fetch setting.
  - fetchAlso
```
void fetchAlso(String... fetches)
```
    Adds a fetch clause for loading non-annotation fields of returned entities. Each fetch is a hibernate clause in dot notation.
    
    Parameters:
    
    fetches - Can be empty, which removes previous fetch setting.
  - resetDefaults
```
void resetDefaults()
```
    Resets all settings (non-query state) to the original default values, as if the instance had just be created.
  - bySimilarTerms
```
void bySimilarTerms(String... terms)
```
    Returns transient (without ID) TextAnnotation instances which represent terms which are similar to the given terms. For example, if the argument is "cell", one return value might have as its textValue: "cellular" while another has "cellularize". No filtering or fetching is performed.
    
    Parameters:
    
    terms - Cannot be empty.
  - byGroupForTags
```
void byGroupForTags(String group)
```
    Returns transient (without ID) TagAnnotation instances which represent all the tags in the given group. The entities are transient and without ownership since multiple users can own the same tag. This method will override settings for types.
    
    Parameters:
    
    group - Can be null or empty to return all tags.
  - byTagForGroups
```
void byTagForGroups(String tag)
```
    Creates a query which will return transient (without ID) TagAnnotation instances which represent all the tag groups which the given tag belongs to. The entities are transient and without ownership since multiple users can own the same tag group. This method will override settings for types.
    
    Parameters:
    
    tag - Can be null or empty to return all groups.
  - byFullText
```
void byFullText(String query)
```
    Passes the query as is to the Lucene backend.
    
    Parameters:
    
    query - May not be null or of zero length.
  - byLuceneQueryBuilder
```
void byLuceneQueryBuilder(String fields,
                          String from,
                          String to,
                          String dateType,
                          String query)
```
    Builds a Lucene query and passes it to the Lucene backend.
    
    Parameters:
    
    fields - The fields (comma separated) to search in (name, description, ...)
    
    from - The date range from, in the form YYYYMMDD (may be null)
    
    to - The date range to (inclusive), in the form YYYYMMDD (may be null)
    
    dateType - DATE_TYPE_ACQUISITION or DATE_TYPE_IMPORT
    
    query - May not be null or of zero length.
  - bySomeMustNone
```
void bySomeMustNone(String[] some,
                    String[] must,
                    String[] none)
```
    Builds a Lucene query and passes it to byFullText(String).
    
    Parameters:
    
    some - Some (at least one) of these terms must be present in the document. May be null.
    
    must - All of these terms must be present in the document. May be null.
    
    none - None of these terms may be present in the document. May be null.
  - byHqlQuery
```
void byHqlQuery(String query,
                Parameters p)
```
    Delegates to IQuery.findAllByQuery(String, Parameters) method to take advantage of the and(), or(), and not() methods, or queue-semantics.
    
    Parameters:
    
    query - Not null.
    
    p - May be null. Defaults are then in effect.
    
    See Also:
    
    IQuery.findAllByQuery(String, Parameters)
  - byAnnotatedWith
```
void byAnnotatedWith(Annotation... examples)
```
    Finds entities annotated with an Annotation similar to the example. This does not use Hibernate's Query-By-Example mechanism, since that cannot handle joins. The fields which are used are:
    - the main content of the annotation : String, OriginalFile.getId(), etc.
    If the main content is null it is assumed to be a wildcard searched, and only the type of the annotation is searched. Currently, ListAnnotations are not supported.
    Parameters:
    
    examples - Not empty.
  - or
```
void or()
```
    Applies the next by* method to the previous by* method, so that a call hasNext(), next(), or results() sees only the union of the two calls. For example,
```
 service.onlyType(Image.class);
 service.byFullText("foo");
 service.or();
 service.onlyType(Dataset.class);
 service.byFullText("foo");
 
```
    will return both Images and Datasets together. Calling this method overrides a previous setting of and() or not(). If there is no active queries (i.e. activeQueries() > 0), then an ApiUsageException will be thrown.
  - and
```
void and()
```
    Applies the next by* method to the previous by* method, so that a call hasNext(), next(), or results() sees only the intersection of the two calls. For example,
```
 service.onlyType(Image.class);
 service.byFullText("foo");
 service.intersection();
 service.byAnnotatedWith(TagAnnotation.class);
 
```
    will return only the Images with TagAnnotations.
    Calling this method overrides a previous setting of or() or not(). If there is no active queries (i.e. activeQueries() > 0), then an ApiUsageException will be thrown.
  - not
```
void not()
```
    Applies the next by* method to the previous by* method, so that a call hasNext(), next(), or results() sees only the intersection of the two calls. For example,
```
 service.onlyType(Image.class);
 service.byFullText("foo");
 service.complement();
 service.byAnnotatedWith(TagAnnotation.class);
 
```
    will return all the Images not annotated with TagAnnotation.
    Calling this method overrides a previous setting of or() or and(). If there is no active queries (i.e. activeQueries() > 0), then an ApiUsageException will be thrown.
  - clearQueries
```
void clearQueries()
```
    Removes all active queries (leaving settings alone), such that activeQueries() will return 0.
  - hasNext
```
boolean hasNext()
```
    Returns true if another call to next() is valid. A call to next() may throw an exception for another reason, however.
    
    Specified by:
    
    hasNext in interface Iterator<IObject>
  - next
```
IObject next()
      throws ApiUsageException
```
    Returns the next entity from the current query. If the previous call returned the last entity from a given query, the first entity from the next query will be returned and activeQueries() decremented. Since this method only returns the entity itself, a single call to currentMetadata() may follow this call to gather the extra metadata which is returned in the map via results().
    
    Specified by:
    
    next in interface Iterator<IObject>
    
    Throws:
    
    ApiUsageException - if hasNext() returns false.
  - currentMetadata
```
Map<String,Annotation> currentMetadata()
```
    Provides access to the extra query information (for example Lucene score and boost values) for a single call to next(). This method may only be called once for any given call to next().
  - remove
```
void remove()
     throws UnsupportedOperationException
```
    Unsupported operation.
    
    Specified by:
    
    remove in interface Iterator<IObject>
    
    Throws:
    
    UnsupportedOperationException
  - results
```
<T extends IObject> List<T> results()
                             throws ApiUsageException
```
    Returns up to batch size number of results along with the related query metadata. If batches are merged then the results from multiple queries may be returned together.
    
    Throws:
    
    ApiUsageException - if hasNext() returns false.
  - currentMetadataList
```
List<Map<String,Annotation>> currentMetadataList()
```
    Provides access to the extra query information (for example Lucene score and boost values) for a single call to results(). This method may only be called once for any given call to results().

Interface Search

Field Summary

Method Summary

Methods inherited from interface ome.api.StatefulServiceInterface

Methods inherited from interface java.util.Iterator

Field Detail

SCORE

DEFAULT_BATCH_SIZE

DEFAULT_MERGED_BATCHES

DEFAULT_CASE_SENSITIVTY

DEFAULT_USE_PROJECTIONS

DEFAULT_RETURN_UNLOADED

ALLOW_LEADING_WILDCARD

DATE_TYPE_IMPORT

DATE_TYPE_ACQUISITION

Method Detail

activeQueries

setBatchSize

getBatchSize

setMergedBatches

isMergedBatches

setCaseSentivice

isCaseSensitive

setUseProjections

isUseProjections

setReturnUnloaded

isReturnUnloaded

setAllowLeadingWildcard

isAllowLeadingWildcard

onlyType

onlyTypes

allTypes

onlyIds

onlyOwnedBy

notOwnedBy

onlyCreatedBetween

onlyModifiedBetween

onlyAnnotatedBetween

onlyAnnotatedBy

notAnnotatedBy

onlyAnnotatedWith

addOrderByAsc

addOrderByDesc

unordered

fetchAnnotations

fetchAlso

resetDefaults

bySimilarTerms

byGroupForTags

byTagForGroups

byFullText

byLuceneQueryBuilder

bySomeMustNone

byHqlQuery

byAnnotatedWith

or

and

not

clearQueries

hasNext

next

currentMetadata

remove

results

currentMetadataList