Interface FilteringDao<O extends Identifiable>

All Superinterfaces:

BaseDao<O>

All Known Subinterfaces:

ArrayDesignDao, BioAssayDao, CachedFilteringDao<O>, CachedFilteringVoEnabledDao<O,VO>, CharacteristicDao, CompositeSequenceDao, DatabaseEntryDao, ExpressionAnalysisResultSetDao, ExpressionExperimentDao, FactorValueDao, FilteringVoEnabledDao<O,VO>, GeneDao, QuantitationTypeDao, TaxonDao

All Known Implementing Classes:

AbstractCriteriaFilteringVoEnabledDao, AbstractCuratableDao, AbstractFilteringVoEnabledDao, AbstractNoopFilteringVoEnabledDao, AbstractQueryFilteringVoEnabledDao, ArrayDesignDaoImpl, BioAssayDaoImpl, CharacteristicDaoImpl, CompositeSequenceDaoImpl, DatabaseEntryDaoImpl, ExpressionAnalysisResultSetDaoImpl, ExpressionExperimentDaoImpl, FactorValueDaoImpl, GeneDaoImpl, QuantitationTypeDaoImpl, TaxonDaoImpl

public interface FilteringDao<O extends Identifiable>
extends BaseDao<O>

Interface for filtering-capable DAO.

Filtering DAOs have the capability of using Filters and Sort abstractions for browsing entities. There are also extra conveniences for loading IDs loadIds(Filters, Sort) and counting entities count(Filters) without having to retrieve too much from the persistent storage.

This interface also provides introspection capabilities for enumerating and getting some meta information about filterable properties.

Author:

poirigui

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static final class	FilteringDao.ConjunctSpec	One predicate of a conjoined subquery filter.

Method Summary

Modifier and Type	Method	Description
long	count(Filters filters)	Count VOs matching the given filters.
<T> Filter	getFilter(String property, Class<T> propertyType, Filter.Operator operator, Collection<T> values)	Obtain a Filter with an already parsed collection of values.
<T> Filter	getFilter(String property, Class<T> propertyType, Filter.Operator operator, T value)	Obtain a Filter with an already parsed value.
Filter	getFilter(String property, Filter.Operator operator, String value)	Obtain an Filter for the entity this DAO is providing.
Filter	getFilter(String property, Filter.Operator operator, String value, SubqueryMode subqueryMode)
Filter	getFilter(String property, Filter.Operator operator, Collection<String> values)	Similar to getFilter(String, Filter.Operator, String), but with a collection of values.
Filter	getFilter(String property, Filter.Operator operator, Collection<String> values, SubqueryMode subqueryMode)
Filter	getFilter(List<FilteringDao.ConjunctSpec> conjuncts, SubqueryMode subqueryMode)	Build a filter requiring a SINGLE element of a to-many relation to satisfy EVERY given predicate.
Set<String>	getFilterableProperties()	List all properties availble for filtering.
List<Object>	getFilterablePropertyAllowedValues(String property)	Obtain a short list of allowed values for the given property, or null if unrestricted.
String	getFilterablePropertyDescription(String propertyName)	Obtain a short description for a given filterable property.
Class<?>	getFilterablePropertyType(String propertyName)	Obtain the type of the given filterable property.
Sort	getSort(String property, Sort.Direction direction, Sort.NullMode nullMode)	Obtain a Sort object for a property of the O.
boolean	isFilterablePropertyDeprecated(String property)	Indicate if the given property is deprecated.
boolean	isFilterablePropertyUsingSubquery(String property)	Indicate if the given property is using a subquery for filtering.
List<O>	load(Filters filters, Sort sort)	Load entities matching the given filters.
Slice<O>	load(Filters filters, Sort sort, int offset, int limit)	Load a slice of entities matching the given filters.
List<Long>	loadIds(Filters filters, Sort sort)	Load IDs of entities matching the given filters.

Methods inherited from interface BaseDao

countAll, create, create, find, findOrCreate, getElementClass, load, load, loadAll, loadReference, loadReference, reload, reload, remove, remove, save, save, streamAll, streamAll, update, update

Method Details

getFilterableProperties

Set<String> getFilterableProperties()

List all properties availble for filtering.

getFilterablePropertyType

Class<?> getFilterablePropertyType(String propertyName)
                            throws IllegalArgumentException

Obtain the type of the given filterable property.

Throws:

IllegalArgumentException - if no such property exists, the cause will be a NoSuchFieldException

getFilterablePropertyDescription

@Nullable
String getFilterablePropertyDescription(String propertyName)
                                 throws IllegalArgumentException

Obtain a short description for a given filterable property.

Throws:

IllegalArgumentException - if no such property exists

getFilterablePropertyAllowedValues

@Nullable
List<Object> getFilterablePropertyAllowedValues(String property)
                                         throws IllegalArgumentException

Obtain a short list of allowed values for the given property, or null if unrestricted.

The returned values must be of the type outlined by getFilterablePropertyType(String), generally a list of String or Integer to denote possible values for an enumerated type.

Throws:

IllegalArgumentException

isFilterablePropertyUsingSubquery

boolean isFilterablePropertyUsingSubquery(String property)
                                   throws IllegalArgumentException

Indicate if the given property is using a subquery for filtering.

Throws:

IllegalArgumentException - if the property does not exist

isFilterablePropertyDeprecated

boolean isFilterablePropertyDeprecated(String property)
                                throws IllegalArgumentException

Indicate if the given property is deprecated.

Throws:

IllegalArgumentException - if the property does not exist

getFilter

Filter getFilter(String property,
 Filter.Operator operator,
 String value)
          throws IllegalArgumentException

Obtain an Filter for the entity this DAO is providing.

It is the responsibility of the DAO to infer the filter property type as well as the alias to use.

If the filter refers to a related entity (i.e. a BioAssay of an ExpressionExperiment), then the DAO should inject the corresponding DAO and delegate it the work of creating the filter.

In the frontend, that correspond to a FilterArg, but since the definition is not available here, we unpack its attributes.

Parameters:

property - property name in the entity use as a left-hand side of the operator

operator - an operator

value - the corresponding, unparsed value, to the right-hand side of the operator

Returns:

a filter filled with the object alias, property, inferred type, operator and parsed value

Throws:

IllegalArgumentException - if the property does not exist in O, or if the operator cannot be applied, or if the value cannot apply to the property an operator see Filter.parse(String, String, Class, Filter.Operator, String, String) for more details

getFilter

Filter getFilter(String property,
 Filter.Operator operator,
 String value,
 SubqueryMode subqueryMode)

getFilter

Filter getFilter(List<FilteringDao.ConjunctSpec> conjuncts,
 @Nullable
 SubqueryMode subqueryMode)
          throws IllegalArgumentException

Build a filter requiring a SINGLE element of a to-many relation to satisfy EVERY given predicate.

Ordinary conjunction cannot express this. valueUri = X and categoryUri = Y becomes two independent subqueries and asks "has some characteristic valued X, and has some characteristic categorised Y" — which is true of a dataset where those are different characteristics. This conjoins the predicates inside one subquery, so they must hold of the same element.

Every predicate must be a subquery-filterable property on the same relation.

Parameters:

conjuncts - predicates to conjoin; at least one. A single conjunct behaves exactly like the corresponding getFilter overload.

subqueryMode - SubqueryMode.ANY (the default when null) or SubqueryMode.NONE. SubqueryMode.ALL is rejected for more than one conjunct: "every element satisfies A and B" negates to a disjunction, which a subquery carrying a conjunction cannot represent.

Throws:

IllegalArgumentException - if a property is not subquery-filterable, the properties do not share a relation, or ALL is combined with a conjunction

getFilter

Filter getFilter(String property,
 Filter.Operator operator,
 Collection<String> values)
          throws IllegalArgumentException

Similar to getFilter(String, Filter.Operator, String), but with a collection of values.

Throws:

IllegalArgumentException

getFilter

Filter getFilter(String property,
 Filter.Operator operator,
 Collection<String> values,
 SubqueryMode subqueryMode)

getFilter

<T> Filter getFilter(String property,
 Class<T> propertyType,
 Filter.Operator operator,
 @Nullable
 T value)
              throws IllegalArgumentException

Obtain a Filter with an already parsed value.

Throws:

IllegalArgumentException

See Also:

• getFilter(String, Filter.Operator, String)

getFilter

<T> Filter getFilter(String property,
 Class<T> propertyType,
 Filter.Operator operator,
 Collection<T> values)
              throws IllegalArgumentException

Obtain a Filter with an already parsed collection of values.

Throws:

IllegalArgumentException

See Also:

• getFilter(String, Filter.Operator, Collection)

getSort

Sort getSort(String property,
 @Nullable
 Sort.Direction direction,
 Sort.NullMode nullMode)
      throws IllegalArgumentException

Obtain a Sort object for a property of the O.

Parameters:

property - a property of O to sort by

direction - a sorting direction, or null if the default direction applies

nullMode - behavior for null values when sorting

Returns:

a Sort object that can be used, for example, on FilteringVoEnabledDao.loadValueObjects(Filters, Sort, int, int)

Throws:

IllegalArgumentException - if no such field exists in O

loadIds

List<Long> loadIds(@Nullable
 Filters filters,
 @Nullable
 Sort sort)

Load IDs of entities matching the given filters.

load

List<O> load(@Nullable
 Filters filters,
 @Nullable
 Sort sort)

Load entities matching the given filters.

load

Slice<O> load(@Nullable
 Filters filters,
 @Nullable
 Sort sort,
 int offset,
 int limit)

Load a slice of entities matching the given filters.

count

long count(@Nullable
 Filters filters)

Count VOs matching the given filters.