public interface Search extends StatefulServiceInterface, java.util.Iterator<IObject>
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()
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.IQuery
Modifier and Type | Field and Description |
---|---|
static boolean |
ALLOW_LEADING_WILDCARD
Default
leading-wildcard setting |
static java.lang.String |
DATE_TYPE_ACQUISITION
Treat date range as acquisition date
|
static java.lang.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 java.lang.String |
SCORE
String constant used to look up the score value of Lucene queries
returned by this interface. |
Modifier and Type | Method and Description |
---|---|
int |
activeQueries()
Returns the number of active queries.
|
void |
addOrderByAsc(java.lang.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(java.lang.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()
|
void |
byAnnotatedWith(Annotation... examples)
Finds entities annotated with an
Annotation similar to the
example. |
void |
byFullText(java.lang.String query)
Passes the query as is to the Lucene backend.
|
void |
byGroupForTags(java.lang.String group)
Returns transient (without ID)
TagAnnotation instances which
represent all the tags in
the given group. |
void |
byHqlQuery(java.lang.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(java.lang.String fields,
java.lang.String from,
java.lang.String to,
java.lang.String dateType,
java.lang.String query)
Builds a Lucene query and passes it to the Lucene backend.
|
void |
bySimilarTerms(java.lang.String... terms)
Returns transient (without ID)
TextAnnotation instances which represent
terms which are similar to the given terms. |
void |
bySomeMustNone(java.lang.String[] some,
java.lang.String[] must,
java.lang.String[] none)
Builds a Lucene query and passes it to
byFullText(String) . |
void |
byTagForGroups(java.lang.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. |
java.util.Map<java.lang.String,Annotation> |
currentMetadata()
Provides access to the extra query information (for example Lucene score
and boost values) for a single call to
next() . |
java.util.List<java.util.Map<java.lang.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(java.lang.String... fetches)
Adds a fetch clause for loading non-annotation fields of returned
entities.
|
void |
fetchAnnotations(java.lang.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()
|
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(java.sql.Timestamp start,
java.sql.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(java.lang.Class... classes)
Restricts entities to having an
Annotation of all the given
types. |
void |
onlyCreatedBetween(java.sql.Timestamp start,
java.sql.Timestamp stop)
Restricts the time between which an entity may have been created.
|
void |
onlyIds(java.lang.Long... ids)
Restricts the set of
ids which will be checked. |
void |
onlyModifiedBetween(java.sql.Timestamp start,
java.sql.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> |
onlyType(java.lang.Class<T> klass)
Restricts the search to a single type.
|
<T extends IObject> |
onlyTypes(java.lang.Class<T>... classes)
Restricts searches to a set of types.
|
void |
or()
|
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> |
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.
|
activate, close, getCurrentEventContext, passivate
static final java.lang.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.static final int DEFAULT_BATCH_SIZE
batch size
static final boolean DEFAULT_MERGED_BATCHES
merged-batches
static final boolean DEFAULT_CASE_SENSITIVTY
case sensitivity
static final boolean DEFAULT_USE_PROJECTIONS
use-projections
static final boolean DEFAULT_RETURN_UNLOADED
return-unloaded
static final boolean ALLOW_LEADING_WILDCARD
leading-wildcard setting
static final java.lang.String DATE_TYPE_IMPORT
static final java.lang.String DATE_TYPE_ACQUISITION
int activeQueries()
activeQueries
gives the minimum number of remaining calls
to results()
when batches are not
merged
.void setBatchSize(int size)
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.size
- maximum number of results per call to results()
int getBatchSize()
setBatchSize(int)
has not
been called, the default value
will be in
effect.results()
DEFAULT_BATCH_SIZE
void setMergedBatches(boolean merge)
results()
.boolean isMergedBatches()
setMergedBatches(boolean)
has not been called, the
default value
will be in effect.void setCaseSentivice(boolean caseSensitive)
boolean isCaseSensitive()
setCaseSentivice(boolean)
has not been called, the
default value
will be in effect.void setUseProjections(boolean useProjections)
boolean isUseProjections()
for more.
If
setUseProjections(boolean)
has not been called, the
DEFAULT_USE_PROJECTIONS
will be in effect.void setReturnUnloaded(boolean returnUnloaded)
IQuery
. This value overrides the
setUseProjections(boolean)
setting.boolean isReturnUnloaded()
setReturnUnloaded(boolean)
has not
been called, the default value
will be
in effect.void setAllowLeadingWildcard(boolean allowLeadingWildcard)
boolean isAllowLeadingWildcard()
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.<T extends IObject> void onlyType(java.lang.Class<T> klass)
<T extends IObject> void onlyTypes(java.lang.Class<T>... classes)
void allTypes()
void onlyIds(java.lang.Long... ids)
ids
which will be checked.
This is useful for testing one of the given restrictions on a reduced set
of objects.ids
- Can be null, in which case the previous restriction is
removed.void onlyOwnedBy(Details d)
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.d
- Can be null, in which case the previous restriction is
removed.void notOwnedBy(Details d)
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.d
- Can be null, in which case the previous restriction is
removed.void onlyCreatedBetween(java.sql.Timestamp start, java.sql.Timestamp stop)
start
- Can be null, i.e. interval open to negative infinity.stop
- Can be null, i.e. interval opens to positive infinity.void onlyModifiedBetween(java.sql.Timestamp start, java.sql.Timestamp stop)
start
- Can be null, i.e. interval open to negative infinity.stop
- Can be null, i.e. interval open to positive infinity.void onlyAnnotatedBetween(java.sql.Timestamp start, java.sql.Timestamp stop)
creation event
of the
Annotation
.start
- Can be null, i.e. interval open to negative infinity.stop
- Can be null, i.e. interval open to positive infinity.void onlyAnnotatedBy(Details d)
Annotation
matching the other filters. As onlyOwnedBy(Details)
, the
Details.getOwner()
and Details.getGroup()
information is
combined with an AND condition.d
- Can be null, in which case any previous restriction is
removed.void notAnnotatedBy(Details d)
Annotation
matching the other filters. As
notOwnedBy(Details)
, the Details.getOwner()
and
Details.getGroup()
information is combined with an AND condition.d
- Can be null, in which case any previous restriction is
removed.void onlyAnnotatedWith(java.lang.Class... classes)
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.classes
- Can be empty, in which case restriction is removed.void addOrderByAsc(java.lang.String path)
path
- Non-null.unordered()
void addOrderByDesc(java.lang.String path)
path
- Non-null.unordered()
void unordered()
addOrderByAsc(String)
,
addOrderByDesc(String)
void fetchAnnotations(java.lang.Class... classes)
annotations
of the given
types for all returned instances.classes
- Can be empty, which removes previous fetch setting.void fetchAlso(java.lang.String... fetches)
fetches
- Can be empty, which removes previous fetch setting.void resetDefaults()
void bySimilarTerms(java.lang.String... terms)
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.terms
- Cannot be empty.void byGroupForTags(java.lang.String group)
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.group
- Can be null or empty to return all tags.void byTagForGroups(java.lang.String tag)
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.tag
- Can be null or empty to return all groups.void byFullText(java.lang.String query)
query
- May not be null or of zero length.void byLuceneQueryBuilder(java.lang.String fields, java.lang.String from, java.lang.String to, java.lang.String dateType, java.lang.String query)
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.void bySomeMustNone(java.lang.String[] some, java.lang.String[] must, java.lang.String[] none)
byFullText(String)
.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.void byHqlQuery(java.lang.String query, Parameters p)
IQuery.findAllByQuery(String, Parameters)
method to
take advantage of the and()
, or()
, and
not()
methods, or queue-semantics.query
- Not null.p
- May be null. Defaults are then in effect.IQuery.findAllByQuery(String, Parameters)
void byAnnotatedWith(Annotation... examples)
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:
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.
examples
- Not empty.void or()
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.void and()
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.
void not()
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.
void clearQueries()
settings
alone), such that activeQueries()
will return 0.boolean hasNext()
next()
is valid. A call to
next()
may throw an exception for another reason, however.hasNext
in interface java.util.Iterator<IObject>
IObject next() throws ApiUsageException
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()
.next
in interface java.util.Iterator<IObject>
ApiUsageException
- if hasNext()
returns false.java.util.Map<java.lang.String,Annotation> currentMetadata()
void remove() throws java.lang.UnsupportedOperationException
remove
in interface java.util.Iterator<IObject>
java.lang.UnsupportedOperationException
<T extends IObject> java.util.List<T> results() throws ApiUsageException
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.ApiUsageException
- if hasNext()
returns false.java.util.List<java.util.Map<java.lang.String,Annotation>> currentMetadataList()
Version: 5.4.10-ice35-b105
Copyright © 2019 The University of Dundee & Open Microscopy Environment. All Rights Reserved.