org.apache.unomi.persistence.spi

Interface PersistenceService

All Known Implementing Classes:

ElasticSearchPersistenceServiceImpl

public interface PersistenceService

A service to provide persistence and retrieval of context server entities.

Method Summary

Modifier and Type	Method and Description
Map<String,Long>	aggregateQuery(Condition filter, BaseAggregate aggregate, String itemType) Deprecated. As of 1.3.0-incubating, please use aggregateWithOptimizedQuery(Condition, BaseAggregate, String) instead
Map<String,Long>	aggregateWithOptimizedQuery(Condition filter, BaseAggregate aggregate, String itemType) Retrieves the number of items with the specified type as defined by the Item subclass public field ITEM_TYPE matching the optional specified condition and aggregated according to the specified BaseAggregate.
Map<String,Long>	aggregateWithOptimizedQuery(Condition filter, BaseAggregate aggregate, String itemType, int size) Retrieves the number of items with the specified type as defined by the Item subclass public field ITEM_TYPE matching the optional specified condition and aggregated according to the specified BaseAggregate.
PartialList<CustomItem>	continueCustomItemScrollQuery(String customItemType, String scrollIdentifier, String scrollTimeValidity) Continues the execution of a scroll query, to retrieve the next results.
<T extends Item> PartialList<T>	continueScrollQuery(Class<T> clazz, String scrollIdentifier, String scrollTimeValidity) Continues the execution of a scroll query, to retrieve the next results.
boolean	createIndex(String itemType) Creates an index with for the specified item type in the persistence engine.
void	createMapping(String type, String source) Create mapping
<T extends Item> List<T>	getAllItems(Class<T> clazz) Retrieves all known items of the specified class.
<T extends Item> PartialList<T>	getAllItems(Class<T> clazz, int offset, int size, String sortBy) Retrieves all known items of the specified class, ordered according to the specified sortBy String and and paged: only size of them are retrieved, starting with the offset-th one.
<T extends Item> PartialList<T>	getAllItems(Class<T> clazz, int offset, int size, String sortBy, String scrollTimeValidity) Retrieves all known items of the specified class, ordered according to the specified sortBy String and and paged: only size of them are retrieved, starting with the offset-th one.
long	getAllItemsCount(String itemType) Retrieves the number of items with the specified type as defined by the Item subclass public field ITEM_TYPE.
Map<String,Map<String,Object>>	getPropertiesMapping(String itemType) Retrieve the type mappings for a given itemType.
Map<String,Object>	getPropertyMapping(String property, String itemType) Retrieve the mapping for one specific property for a given type.
Map<String,Double>	getSingleValuesMetrics(Condition condition, String[] metrics, String field, String type) Retrieves the specified metrics for the specified field of items of the specified type as defined by the Item subclass public field ITEM_TYPE and matching the specified Condition.
boolean	isConsistent(Item item) Return true if the item which is saved in the persistence service is consistent
boolean	isValidCondition(Condition condition, Item item) validates if a condition throws exception at query build.
<T extends Item> T	load(String itemId, Class<T> clazz) Retrieves the item identified with the specified identifier and with the specified Item subclass if it exists.
<T extends Item> T	load(String itemId, Date dateHint, Class<T> clazz) Deprecated. use load(String, Class)
CustomItem	loadCustomItem(String itemId, Date dateHint, String customItemType) Deprecated. use loadCustomItem(String, String)
default CustomItem	loadCustomItem(String itemId, String customItemType) Load a custom item type identified by an identifier, an optional date hint and the identifier of the custom item type
void	purge(Date date) Deprecated.
void	purge(String scope) Removes all data associated with the provided scope.
<T extends Item> void	purgeTimeBasedItems(int existsNumberOfDays, Class<T> clazz) Purges time based data in the context server up to the specified days number of existence.
<T extends Item> List<T>	query(Condition query, String sortBy, Class<T> clazz) Same as query(query, sortBy, clazz, 0, -1).getList()
<T extends Item> PartialList<T>	query(Condition query, String sortBy, Class<T> clazz, int offset, int size) Retrieves a list of items satisfying the specified Condition, ordered according to the specified sortBy String and and paged: only size of them are retrieved, starting with the offset-th one.
<T extends Item> PartialList<T>	query(Condition query, String sortBy, Class<T> clazz, int offset, int size, String scrollTimeValidity) Retrieves a list of items satisfying the specified Condition, ordered according to the specified sortBy String and and paged: only size of them are retrieved, starting with the offset-th one.
<T extends Item> List<T>	query(String fieldName, String[] fieldValues, String sortBy, Class<T> clazz) Retrieves a list of items with the specified field having the specified values.
<T extends Item> List<T>	query(String fieldName, String fieldValue, String sortBy, Class<T> clazz) Same as query(fieldName, fieldValue, sortBy, clazz, 0, -1).getList()
<T extends Item> PartialList<T>	query(String fieldName, String fieldValue, String sortBy, Class<T> clazz, int offset, int size) Retrieves a list of items with the specified field having the specified value.
long	queryCount(Condition query, String itemType) Retrieves the number of items of the specified type as defined by the Item subclass public field ITEM_TYPE and matching the specified Condition.
PartialList<CustomItem>	queryCustomItem(Condition query, String sortBy, String customItemType, int offset, int size, String scrollTimeValidity) Retrieves a list of items satisfying the specified Condition, ordered according to the specified sortBy String and paged: only size of them are retrieved, starting with the offset-th one.
<T extends Item> PartialList<T>	queryFullText(String fulltext, Condition query, String sortBy, Class<T> clazz, int offset, int size) Retrieves the same items as query(query, sortBy, clazz, 0, -1) with the added constraints that the matching elements must also have at least a field matching the specified full text query.
<T extends Item> PartialList<T>	queryFullText(String fulltext, String sortBy, Class<T> clazz, int offset, int size) Retrieves a list of items having at least a field with the specified full text value in it, ordered according to the specified sortBy String and and paged: only size of them are retrieved, starting with the offset-th one.
<T extends Item> PartialList<T>	queryFullText(String fieldName, String fieldValue, String fulltext, String sortBy, Class<T> clazz, int offset, int size) Retrieves a list of items with the specified field having the specified value and having at least a field with the specified full text value in it, ordered according to the specified sortBy String and and paged: only size of them are retrieved, starting with the offset-th one.
<T extends Item> PartialList<T>	rangeQuery(String s, String from, String to, String sortBy, Class<T> clazz, int offset, int size) Retrieves all items of the specified Item subclass which specified ranged property is within the specified bounds, ordered according to the specified sortBy String and and paged: only size of them are retrieved, starting with the offset-th one.
void	refresh() Updates the persistence's engine indices if needed.
default <T extends Item> void	refreshIndex(Class<T> clazz) Updates the persistence's engine specific index.
<T extends Item> void	refreshIndex(Class<T> clazz, Date dateHint) Deprecated. use refreshIndex(Class)
<T extends Item> boolean	remove(String itemId, Class<T> clazz) Deletes the item identified with the specified identifier and with the specified Item subclass if it exists.
<T extends Item> boolean	removeByQuery(Condition query, Class<T> clazz) Deletes items with the specified Item subclass matching the specified Condition.
boolean	removeCustomItem(String itemId, String customItemType) Remove a custom item identified by the custom item identifier and the custom item type identifier
boolean	removeIndex(String itemType) Removes the index for the specified item type.
boolean	removeQuery(String queryName) Deletes the query identified by the specified name.
boolean	save(Item item) Persists the specified Item in the context server.
boolean	save(Item item, boolean useBatching) Persists the specified Item in the context server.
boolean	save(Item item, Boolean useBatching, Boolean alwaysOverwrite) Persists the specified Item in the context server.
boolean	saveQuery(String queryName, Condition query) Persists the specified query under the specified name.
void	setPropertyMapping(PropertyType property, String itemType) Create the persistence mapping for specific property for a given type.
boolean	storeScripts(Map<String,String> scripts) Store script in the Database for later usage with updateWithQueryAndStoredScript function for example.
boolean	testMatch(Condition query, Item item) Checks whether the specified item satisfies the provided condition.
default boolean	update(Item item, Class<?> clazz, Map<?,?> source) Updates the item of the specified class and identified by the specified identifier with new property values provided as name - value pairs in the specified Map.
default boolean	update(Item item, Class<?> clazz, Map<?,?> source, boolean alwaysOverwrite) Updates the item of the specified class and identified by the specified identifier with new property values provided as name - value pairs in the specified Map.
default boolean	update(Item item, Class<?> clazz, String propertyName, Object propertyValue) Updates the item of the specified class and identified by the specified identifier with a new property value for the specified property name.
boolean	update(Item item, Date dateHint, Class<?> clazz, Map<?,?> source) Deprecated. use update(Item, Class, Map)
boolean	update(Item item, Date dateHint, Class<?> clazz, Map<?,?> source, boolean alwaysOverwrite) Deprecated. use update(Item, Class, Map, boolean)
boolean	update(Item item, Date dateHint, Class<?> clazz, String propertyName, Object propertyValue) Deprecated. use update(Item, Class, String, Object)
default List<String>	update(Map<Item,Map> items, Class clazz) Updates Map of items of the specified class and identified by the specified identifier with a new property value for the specified property name.
List<String>	update(Map<Item,Map> items, Date dateHint, Class clazz) Deprecated. use update(Map, Class)
default boolean	updateWithQueryAndScript(Class<?> clazz, String[] scripts, Map<String,Object>[] scriptParams, Condition[] conditions) Updates the items of the specified class by a query with a new property value for the specified property name based on provided scripts and script parameters
boolean	updateWithQueryAndScript(Date dateHint, Class<?> clazz, String[] scripts, Map<String,Object>[] scriptParams, Condition[] conditions) Deprecated. use updateWithQueryAndScript(Class, String[], Map[], Condition[])
default boolean	updateWithQueryAndStoredScript(Class<?> clazz, String[] scripts, Map<String,Object>[] scriptParams, Condition[] conditions) Updates the items of the specified class by a query with a new property value for the specified property name based on provided stored scripts and script parameters
boolean	updateWithQueryAndStoredScript(Date dateHint, Class<?> clazz, String[] scripts, Map<String,Object>[] scriptParams, Condition[] conditions) Deprecated. use updateWithQueryAndStoredScript(Class, String[], Map[], Condition[])
default boolean	updateWithScript(Item item, Class<?> clazz, String script, Map<String,Object> scriptParams) Updates the item of the specified class and identified by the specified identifier with a new property value for the specified property name.
boolean	updateWithScript(Item item, Date dateHint, Class<?> clazz, String script, Map<String,Object> scriptParams) Deprecated. use updateWithScript(Item, Class, String, Map)

Method Detail

getAllItems

<T extends Item> List<T> getAllItems(Class<T> clazz)

Retrieves all known items of the specified class. WARNING: this method can be quite computationally intensive and calling the paged version getAllItems(Class, int, int, String) is preferred.

Type Parameters:

T - the type of the Items we want to retrieve

Parameters:

clazz - the Item subclass of entities we want to retrieve

Returns:

a list of all known items with the given type

getAllItems

<T extends Item> PartialList<T> getAllItems(Class<T> clazz,
                                            int offset,
                                            int size,
                                            String sortBy)

Retrieves all known items of the specified class, ordered according to the specified sortBy String and and paged: only size of them are retrieved, starting with the offset-th one.

TODO: use a Query object instead of distinct parameters?

Type Parameters:

T - the type of the Items we want to retrieve

Parameters:

clazz - the Item subclass of entities we want to retrieve

offset - zero or a positive integer specifying the position of the first item in the total ordered collection of matching items

size - a positive integer specifying how many matching items should be retrieved or -1 if all of them should be retrieved

sortBy - an optional (null if no sorting is required) String of comma (,) separated property names on which ordering should be performed, ordering elements according to the property order in the String, considering each in turn and moving on to the next one in case of equality of all preceding ones. Each property name is optionally followed by a column (:) and an order specifier: asc or desc.

Returns:

a PartialList of pages items with the given type

getAllItems

<T extends Item> PartialList<T> getAllItems(Class<T> clazz,
                                            int offset,
                                            int size,
                                            String sortBy,
                                            String scrollTimeValidity)

Retrieves all known items of the specified class, ordered according to the specified sortBy String and and paged: only size of them are retrieved, starting with the offset-th one.

TODO: use a Query object instead of distinct parameters?

Type Parameters:

T - the type of the Items we want to retrieve

Parameters:

clazz - the Item subclass of entities we want to retrieve

offset - zero or a positive integer specifying the position of the first item in the total ordered collection of matching items

size - a positive integer specifying how many matching items should be retrieved or -1 if all of them should be retrieved

sortBy - an optional (null if no sorting is required) String of comma (,) separated property names on which ordering should be performed, ordering elements according to the property order in the String, considering each in turn and moving on to the next one in case of equality of all preceding ones. Each property name is optionally followed by a column (:) and an order specifier: asc or desc.

scrollTimeValidity - the time the scrolling query should stay valid. This must contain a time unit value such as the ones supported by ElasticSearch, such as * the ones declared here : https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html#time-units

Returns:

a PartialList of pages items with the given type

isConsistent

boolean isConsistent(Item item)

Return true if the item which is saved in the persistence service is consistent

Parameters:

item - the item to the check if consistent

Returns:

true if the item is consistent, false otherwise

save

boolean save(Item item)

Persists the specified Item in the context server.

Parameters:

item - the item to persist

Returns:

true if the item was properly persisted, false otherwise

save

boolean save(Item item,
             boolean useBatching)

Persists the specified Item in the context server.

Parameters:

item - the item to persist

useBatching - whether to use batching or not for saving the item. If activating there may be a delay between the call to this method and the actual saving in the persistence backend.

Returns:

true if the item was properly persisted, false otherwise

save

boolean save(Item item,
             Boolean useBatching,
             Boolean alwaysOverwrite)

Persists the specified Item in the context server.

Parameters:

item - the item to persist

useBatching - whether to use batching or not for saving the item. If activating there may be a delay between the call to this method and the actual saving in the persistence backend

alwaysOverwrite - whether to overwrite a document even if we are holding an old item when saving

Returns:

true if the item was properly persisted, false otherwise

update

default boolean update(Item item,
                       Class<?> clazz,
                       Map<?,?> source)

Updates the item of the specified class and identified by the specified identifier with new property values provided as name - value pairs in the specified Map.

Parameters:

item - the item we want to update

clazz - the Item subclass of the item to update

source - a Map with entries specifying as key the property name to update and as value its new value

Returns:

true if the update was successful, false otherwise

update

@Deprecated
boolean update(Item item,
                           Date dateHint,
                           Class<?> clazz,
                           Map<?,?> source)

Deprecated. use update(Item, Class, Map)

update

default boolean update(Item item,
                       Class<?> clazz,
                       String propertyName,
                       Object propertyValue)

Updates the item of the specified class and identified by the specified identifier with a new property value for the specified property name. Same as update(itemId, clazz, Collections.singletonMap(propertyName, propertyValue))

Parameters:

item - the item we want to update

clazz - the Item subclass of the item to update

propertyName - the name of the property to update

propertyValue - the new value of the property

Returns:

true if the update was successful, false otherwise

update

@Deprecated
boolean update(Item item,
                           Date dateHint,
                           Class<?> clazz,
                           String propertyName,
                           Object propertyValue)

Deprecated. use update(Item, Class, String, Object)

update

default boolean update(Item item,
                       Class<?> clazz,
                       Map<?,?> source,
                       boolean alwaysOverwrite)

Updates the item of the specified class and identified by the specified identifier with new property values provided as name - value pairs in the specified Map.

Parameters:

item - the item we want to update

clazz - the Item subclass of the item to update

source - a Map with entries specifying as key the property name to update and as value its new value

alwaysOverwrite - whether to overwrite a document even if we are holding an old item when saving

Returns:

true if the update was successful, false otherwise

update

@Deprecated
boolean update(Item item,
                           Date dateHint,
                           Class<?> clazz,
                           Map<?,?> source,
                           boolean alwaysOverwrite)

Deprecated. use update(Item, Class, Map, boolean)

update

default List<String> update(Map<Item,Map> items,
                            Class clazz)

Updates Map of items of the specified class and identified by the specified identifier with a new property value for the specified property name. Same as update(itemId, clazz, Collections.singletonMap(propertyName, propertyValue))

Parameters:

items - A map the consist of item (key) and properties to update (value)

clazz - the Item subclass of the item to update

Returns:

List of failed Items Ids, if all succesful then returns an empty list. if the whole operation failed then will return null

update

@Deprecated
List<String> update(Map<Item,Map> items,
                                Date dateHint,
                                Class clazz)

Deprecated. use update(Map, Class)

updateWithScript

default boolean updateWithScript(Item item,
                                 Class<?> clazz,
                                 String script,
                                 Map<String,Object> scriptParams)

Updates the item of the specified class and identified by the specified identifier with a new property value for the specified property name. Same as update(itemId, clazz, Collections.singletonMap(propertyName, propertyValue))

Parameters:

item - the item we want to update

clazz - the Item subclass of the item to update

script - inline script

scriptParams - script params

Returns:

true if the update was successful, false otherwise

updateWithScript

@Deprecated
boolean updateWithScript(Item item,
                                     Date dateHint,
                                     Class<?> clazz,
                                     String script,
                                     Map<String,Object> scriptParams)

Deprecated. use updateWithScript(Item, Class, String, Map)

updateWithQueryAndScript

default boolean updateWithQueryAndScript(Class<?> clazz,
                                         String[] scripts,
                                         Map<String,Object>[] scriptParams,
                                         Condition[] conditions)

Updates the items of the specified class by a query with a new property value for the specified property name based on provided scripts and script parameters

Parameters:

clazz - the Item subclass of the item to update

scripts - inline scripts array

scriptParams - script params array

conditions - conditions array

Returns:

true if the update was successful, false otherwise

updateWithQueryAndScript

@Deprecated
boolean updateWithQueryAndScript(Date dateHint,
                                             Class<?> clazz,
                                             String[] scripts,
                                             Map<String,Object>[] scriptParams,
                                             Condition[] conditions)

Deprecated. use updateWithQueryAndScript(Class, String[], Map[], Condition[])

updateWithQueryAndStoredScript

default boolean updateWithQueryAndStoredScript(Class<?> clazz,
                                               String[] scripts,
                                               Map<String,Object>[] scriptParams,
                                               Condition[] conditions)

Updates the items of the specified class by a query with a new property value for the specified property name based on provided stored scripts and script parameters

Parameters:

clazz - the Item subclass of the item to update

scripts - Stored scripts name

scriptParams - script params array

conditions - conditions array

Returns:

true if the update was successful, false otherwise

updateWithQueryAndStoredScript

@Deprecated
boolean updateWithQueryAndStoredScript(Date dateHint,
                                                   Class<?> clazz,
                                                   String[] scripts,
                                                   Map<String,Object>[] scriptParams,
                                                   Condition[] conditions)

Deprecated. use updateWithQueryAndStoredScript(Class, String[], Map[], Condition[])

storeScripts

boolean storeScripts(Map<String,String> scripts)

Store script in the Database for later usage with updateWithQueryAndStoredScript function for example.

Parameters:

scripts - inline scripts map indexed by id

Returns:

true if the update was successful, false otherwise

load

<T extends Item> T load(String itemId,
                        Class<T> clazz)

Retrieves the item identified with the specified identifier and with the specified Item subclass if it exists.

Type Parameters:

T - the type of the Item subclass we want to retrieve

Parameters:

itemId - the identifier of the item we want to retrieve

clazz - the Item subclass of the item we want to retrieve

Returns:

the item identified with the specified identifier and with the specified Item subclass if it exists, null otherwise

load

@Deprecated
<T extends Item> T load(String itemId,
                                    Date dateHint,
                                    Class<T> clazz)

Deprecated. use load(String, Class)

loadCustomItem

default CustomItem loadCustomItem(String itemId,
                                  String customItemType)

Load a custom item type identified by an identifier, an optional date hint and the identifier of the custom item type

Parameters:

itemId - the identifier of the custom type we want to retrieve

customItemType - an identifier of the custom item type to load

Returns:

the CustomItem instance with the specified identifier and the custom item type if it exists, null otherwise

loadCustomItem

@Deprecated
CustomItem loadCustomItem(String itemId,
                                      Date dateHint,
                                      String customItemType)

Deprecated. use loadCustomItem(String, String)

remove

<T extends Item> boolean remove(String itemId,
                                Class<T> clazz)

Deletes the item identified with the specified identifier and with the specified Item subclass if it exists.

Type Parameters:

T - the type of the Item subclass we want to delete

Parameters:

itemId - the identifier of the item we want to delete

clazz - the Item subclass of the item we want to delete

Returns:

true if the deletion was successful, false otherwise

removeCustomItem

boolean removeCustomItem(String itemId,
                         String customItemType)

Remove a custom item identified by the custom item identifier and the custom item type identifier

Parameters:

itemId - the identifier of the custom item to be removed

customItemType - the name of the custom item type

Returns:

true if the deletion was successful, false otherwise

removeByQuery

<T extends Item> boolean removeByQuery(Condition query,
                                       Class<T> clazz)

Deletes items with the specified Item subclass matching the specified Condition.

Type Parameters:

T - the type of the Item subclass we want to delete

Parameters:

query - a Condition identifying which elements we want to delete

clazz - the Item subclass of the items we want to delete

Returns:

true if the deletion was successful, false otherwise

saveQuery

boolean saveQuery(String queryName,
                  Condition query)

Persists the specified query under the specified name.

Parameters:

queryName - the name under which the specified query should be recorded

query - the query to be recorded

Returns:

true if the query was properly saved, false otherwise

removeQuery

boolean removeQuery(String queryName)

Deletes the query identified by the specified name.

Parameters:

queryName - the name under which the specified query was recorded

Returns:

true if the deletion was successful, false otherwise

getPropertiesMapping

Map<String,Map<String,Object>> getPropertiesMapping(String itemType)

Retrieve the type mappings for a given itemType. This method queries the persistence service implementation to retrieve any type mappings it may have for the specified itemType.

This method may not return any results if the implementation doesn't support property type mappings

Parameters:

itemType - the itemType we want to retrieve the mappings for

Returns:

properties mapping

getPropertyMapping

Map<String,Object> getPropertyMapping(String property,
                                      String itemType)

Retrieve the mapping for one specific property for a given type.

Parameters:

property - the property name (can use nested dot notation)

itemType - the itemType we want to retrieve the mappings for

Returns:

property mapping

setPropertyMapping

void setPropertyMapping(PropertyType property,
                        String itemType)

Create the persistence mapping for specific property for a given type.

Parameters:

property - the PropertyType to create mapping for

itemType - the itemType we want to retrieve the mappings for

createMapping

void createMapping(String type,
                   String source)

Create mapping

Parameters:

type - the type

source - the source

testMatch

boolean testMatch(Condition query,
                  Item item)

Checks whether the specified item satisfies the provided condition.

TODO: rename to isMatching?

Parameters:

query - the condition we're testing the specified item against

item - the item we're checking against the specified condition

Returns:

true if the item satisfies the condition, false otherwise

isValidCondition

boolean isValidCondition(Condition condition,
                         Item item)

validates if a condition throws exception at query build.

Parameters:

condition - the condition we're testing the specified item against

item - the item we're checking against the specified condition

Returns:

true if the item satisfies the condition, false otherwise

query

<T extends Item> List<T> query(String fieldName,
                               String fieldValue,
                               String sortBy,
                               Class<T> clazz)

Same as query(fieldName, fieldValue, sortBy, clazz, 0, -1).getList()

Type Parameters:

T - the type of the Item subclass we want to retrieve

Parameters:

fieldName - the name of the field which we want items to have the specified values

fieldValue - the value the items to retrieve should have for the specified field

sortBy - an optional (null if no sorting is required) String of comma (,) separated property names on which ordering should be performed, ordering elements according to the property order in the String, considering each in turn and moving on to the next one in case of equality of all preceding ones. Each property name is optionally followed by a column (:) and an order specifier: asc or desc.

clazz - the Item subclass of the items we want to retrieve

Returns:

a list of items matching the specified criteria

See Also:

query(Condition, String, Class, int, int)

query

<T extends Item> List<T> query(String fieldName,
                               String[] fieldValues,
                               String sortBy,
                               Class<T> clazz)

Retrieves a list of items with the specified field having the specified values.

Type Parameters:

T - the type of the Item subclass we want to retrieve

Parameters:

fieldName - the name of the field which we want items to have the specified values

fieldValues - the values the items to retrieve should have for the specified field

sortBy - an optional (null if no sorting is required) String of comma (,) separated property names on which ordering should be performed, ordering elements according to the property order in the String, considering each in turn and moving on to the next one in case of equality of all preceding ones. Each property name is optionally followed by a column (:) and an order specifier: asc or desc.

clazz - the Item subclass of the items we want to retrieve

Returns:

a list of items matching the specified criteria

query

<T extends Item> PartialList<T> query(String fieldName,
                                      String fieldValue,
                                      String sortBy,
                                      Class<T> clazz,
                                      int offset,
                                      int size)

Retrieves a list of items with the specified field having the specified value.

Type Parameters:

T - the type of the Item subclass we want to retrieve

Parameters:

fieldName - the name of the field which we want items to have the specified value

fieldValue - the value the items to retrieve should have for the specified field

sortBy - an optional (null if no sorting is required) String of comma (,) separated property names on which ordering should be performed, ordering elements according to the property order in the String, considering each in turn and moving on to the next one in case of equality of all preceding ones. Each property name is optionally followed by a column (:) and an order specifier: asc or desc.

clazz - the Item subclass of the items we want to retrieve

offset - zero or a positive integer specifying the position of the first item in the total ordered collection of matching items

size - a positive integer specifying how many matching items should be retrieved or -1 if all of them should be retrieved

Returns:

a PartialList of items matching the specified criteria

queryFullText

<T extends Item> PartialList<T> queryFullText(String fieldName,
                                              String fieldValue,
                                              String fulltext,
                                              String sortBy,
                                              Class<T> clazz,
                                              int offset,
                                              int size)

Retrieves a list of items with the specified field having the specified value and having at least a field with the specified full text value in it, ordered according to the specified sortBy String and and paged: only size of them are retrieved, starting with the offset-th one.

Type Parameters:

T - the type of the Item subclass we want to retrieve

Parameters:

fieldName - the name of the field which we want items to have the specified value

fieldValue - the value the items to retrieve should have for the specified field

fulltext - the text that the item must have in one of its fields to be considered a match

sortBy - an optional (null if no sorting is required) String of comma (,) separated property names on which ordering should be performed, ordering elements according to the property order in the String, considering each in turn and moving on to the next one in case of equality of all preceding ones. Each property name is optionally followed by a column (:) and an order specifier: asc or desc.

clazz - the Item subclass of the items we want to retrieve

offset - zero or a positive integer specifying the position of the first item in the total ordered collection of matching items

size - a positive integer specifying how many matching items should be retrieved or -1 if all of them should be retrieved

Returns:

a PartialList of items matching the specified criteria

queryFullText

<T extends Item> PartialList<T> queryFullText(String fulltext,
                                              String sortBy,
                                              Class<T> clazz,
                                              int offset,
                                              int size)

Retrieves a list of items having at least a field with the specified full text value in it, ordered according to the specified sortBy String and and paged: only size of them are retrieved, starting with the offset-th one.

Type Parameters:

T - the type of the Item subclass we want to retrieve

Parameters:

fulltext - the text that the item must have in one of its fields to be considered a match

sortBy - an optional (null if no sorting is required) String of comma (,) separated property names on which ordering should be performed, ordering elements according to the property order in the String, considering each in turn and moving on to the next one in case of equality of all preceding ones. Each property name is optionally followed by a column (:) and an order specifier: asc or desc.

clazz - the Item subclass of the items we want to retrieve

offset - zero or a positive integer specifying the position of the first item in the total ordered collection of matching items

size - a positive integer specifying how many matching items should be retrieved or -1 if all of them should be retrieved

Returns:

a PartialList of items matching the specified criteria

query

<T extends Item> List<T> query(Condition query,
                               String sortBy,
                               Class<T> clazz)

Same as query(query, sortBy, clazz, 0, -1).getList()

Type Parameters:

T - the type of the Item subclass we want to retrieve

Parameters:

query - the Condition the items must satisfy to be retrieved

sortBy - an optional (null if no sorting is required) String of comma (,) separated property names on which ordering should be performed, ordering elements according to the property order in the String, considering each in turn and moving on to the next one in case of equality of all preceding ones. Each property name is optionally followed by a column (:) and an order specifier: asc or desc.

clazz - the Item subclass of the items we want to retrieve

Returns:

a PartialList of items matching the specified criteria

See Also:

query(Condition, String, Class, int, int)

query

<T extends Item> PartialList<T> query(Condition query,
                                      String sortBy,
                                      Class<T> clazz,
                                      int offset,
                                      int size)

Retrieves a list of items satisfying the specified Condition, ordered according to the specified sortBy String and and paged: only size of them are retrieved, starting with the offset-th one.

Type Parameters:

T - the type of the Item subclass we want to retrieve

Parameters:

query - the Condition the items must satisfy to be retrieved

sortBy - an optional (null if no sorting is required) String of comma (,) separated property names on which ordering should be performed, ordering elements according to the property order in the String, considering each in turn and moving on to the next one in case of equality of all preceding ones. Each property name is optionally followed by a column (:) and an order specifier: asc or desc.

clazz - the Item subclass of the items we want to retrieve

offset - zero or a positive integer specifying the position of the first item in the total ordered collection of matching items

size - a positive integer specifying how many matching items should be retrieved or -1 if all of them should be retrieved

Returns:

a PartialList of items matching the specified criteria

query

<T extends Item> PartialList<T> query(Condition query,
                                      String sortBy,
                                      Class<T> clazz,
                                      int offset,
                                      int size,
                                      String scrollTimeValidity)

Retrieves a list of items satisfying the specified Condition, ordered according to the specified sortBy String and and paged: only size of them are retrieved, starting with the offset-th one. If a scroll identifier and time validity are specified, they will be used to perform a scrolling query, meaning that only partial results will be returned, but the scrolling can be continued.

Type Parameters:

T - the type of the Item subclass we want to retrieve

Parameters:

query - the Condition the items must satisfy to be retrieved

sortBy - an optional (null if no sorting is required) String of comma (,) separated property names on which ordering should be performed, ordering elements according to the property order in the String, considering each in turn and moving on to the next one in case of equality of all preceding ones. Each property name is optionally followed by a column (:) and an order specifier: asc or desc.

clazz - the Item subclass of the items we want to retrieve

offset - zero or a positive integer specifying the position of the first item in the total ordered collection of matching items

size - a positive integer specifying how many matching items should be retrieved or -1 if all of them should be retrieved. In the case of a scroll query this will be used as the scrolling window size.

scrollTimeValidity - the time the scrolling query should stay valid. This must contain a time unit value such as the ones supported by ElasticSearch, such as the ones declared here : https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html#time-units

Returns:

a PartialList of items matching the specified criteria, with an scroll identifier and the scroll validity used if a scroll query was requested.

continueScrollQuery

<T extends Item> PartialList<T> continueScrollQuery(Class<T> clazz,
                                                    String scrollIdentifier,
                                                    String scrollTimeValidity)

Continues the execution of a scroll query, to retrieve the next results. If there are no more results the scroll query is also cleared.

Type Parameters:

T - the type of the Item subclass we want to retrieve

Parameters:

clazz - the Item subclass of the items we want to retrieve

scrollIdentifier - a scroll identifier obtained by the execution of a first query and returned in the PartialList object

scrollTimeValidity - a scroll time validity value for the scroll query to stay valid. This must contain a time unit value such as the ones supported by ElasticSearch, such as the ones declared here : https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html#time-units

Returns:

a PartialList of items matching the specified criteria, with an scroll identifier and the scroll validity used if a scroll query was requested. Note that if there are no more results the list will be empty but not null.

queryCustomItem

PartialList<CustomItem> queryCustomItem(Condition query,
                                        String sortBy,
                                        String customItemType,
                                        int offset,
                                        int size,
                                        String scrollTimeValidity)

Retrieves a list of items satisfying the specified Condition, ordered according to the specified sortBy String and paged: only size of them are retrieved, starting with the offset-th one. If a scroll identifier and time validity are specified, they will be used to perform a scrolling query, meaning that only partial results will be returned, but the scrolling can be continued.

Parameters:

query - the Condition the items must satisfy to be retrieved

sortBy - an optional (null if no sorting is required) String of comma (,) separated property names on which ordering should be performed, ordering elements according to the property order in the String, considering each in turn and moving on to the next one in case of equality of all preceding ones. Each property name is optionally followed by a column (:) and an order specifier: asc or desc.

customItemType - the identifier of the custom item type we want to query

offset - zero or a positive integer specifying the position of the first item in the total ordered collection of matching items

size - a positive integer specifying how many matching items should be retrieved or -1 if all of them should be retrieved. In the case of a scroll query this will be used as the scrolling window size.

scrollTimeValidity - the time the scrolling query should stay valid. This must contain a time unit value such as the ones supported by ElasticSearch, such as the ones declared here : https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html#time-units

Returns:

a PartialList of items matching the specified criteria, with an scroll identifier and the scroll validity used if a scroll query was requested.

continueCustomItemScrollQuery

PartialList<CustomItem> continueCustomItemScrollQuery(String customItemType,
                                                      String scrollIdentifier,
                                                      String scrollTimeValidity)

Continues the execution of a scroll query, to retrieve the next results. If there are no more results the scroll query is also cleared.

Parameters:

customItemType - the identifier of the custom item type we want to continue querying

scrollIdentifier - a scroll identifier obtained by the execution of a first query and returned in the PartialList object

scrollTimeValidity - a scroll time validity value for the scroll query to stay valid. This must contain a time unit value such as the ones supported by ElasticSearch, such as the ones declared here : https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html#time-units

Returns:

a PartialList of items matching the specified criteria, with an scroll identifier and the scroll validity used if a scroll query was requested. Note that if there are no more results the list will be empty but not null.

queryFullText

<T extends Item> PartialList<T> queryFullText(String fulltext,
                                              Condition query,
                                              String sortBy,
                                              Class<T> clazz,
                                              int offset,
                                              int size)

Retrieves the same items as query(query, sortBy, clazz, 0, -1) with the added constraints that the matching elements must also have at least a field matching the specified full text query.

Type Parameters:

T - the type of the Item subclass we want to retrieve

Parameters:

fulltext - the text that the item must have in one of its fields to be considered a match

query - the Condition the items must satisfy to be retrieved

sortBy - an optional (null if no sorting is required) String of comma (,) separated property names on which ordering should be performed, ordering elements according to the property order in the String, considering each in turn and moving on to the next one in case of equality of all preceding ones. Each property name is optionally followed by a column (:) and an order specifier: asc or desc.

clazz - the Item subclass of the items we want to retrieve

offset - zero or a positive integer specifying the position of the first item in the total ordered collection of matching items

size - a positive integer specifying how many matching items should be retrieved or -1 if all of them should be retrieved

Returns:

a PartialList of items matching the specified criteria

queryCount

long queryCount(Condition query,
                String itemType)

Retrieves the number of items of the specified type as defined by the Item subclass public field ITEM_TYPE and matching the specified Condition.

Parameters:

query - the condition the items must satisfy

itemType - the String representation of the item type we want to retrieve the count of, as defined by its class' ITEM_TYPE field

Returns:

the number of items of the specified type

See Also:

Item for a discussion of {@code ITEM_TYPE}

getAllItemsCount

long getAllItemsCount(String itemType)

Retrieves the number of items with the specified type as defined by the Item subclass public field ITEM_TYPE.

Parameters:

itemType - the String representation of the item type we want to retrieve the count of, as defined by its class' ITEM_TYPE field

Returns:

the number of items of the specified type

See Also:

Item for a discussion of {@code ITEM_TYPE}

aggregateQuery

@Deprecated
Map<String,Long> aggregateQuery(Condition filter,
                                            BaseAggregate aggregate,
                                            String itemType)

Deprecated. As of 1.3.0-incubating, please use aggregateWithOptimizedQuery(Condition, BaseAggregate, String) instead

Retrieves the number of items with the specified type as defined by the Item subclass public field ITEM_TYPE matching the optional specified condition and aggregated according to the specified BaseAggregate. Also return the global count of document matching the ITEM_TYPE

Parameters:

filter - the condition the items must match or null if no filtering is needed

aggregate - an aggregate specifying how matching items must be bundled

itemType - the String representation of the item type we want to retrieve the count of, as defined by its class' ITEM_TYPE field

Returns:

a Map associating aggregation dimension name as key and cardinality for that dimension as value

aggregateWithOptimizedQuery

Map<String,Long> aggregateWithOptimizedQuery(Condition filter,
                                             BaseAggregate aggregate,
                                             String itemType)

Retrieves the number of items with the specified type as defined by the Item subclass public field ITEM_TYPE matching the optional specified condition and aggregated according to the specified BaseAggregate. This aggregate won't return the global count and should therefore be much faster than aggregateQuery(Condition, BaseAggregate, String)

Parameters:

filter - the condition the items must match or null if no filtering is needed

aggregate - an aggregate specifying how matching items must be bundled

itemType - the String representation of the item type we want to retrieve the count of, as defined by its class' ITEM_TYPE field

Returns:

a Map associating aggregation dimension name as key and cardinality for that dimension as value

aggregateWithOptimizedQuery

Map<String,Long> aggregateWithOptimizedQuery(Condition filter,
                                             BaseAggregate aggregate,
                                             String itemType,
                                             int size)

Retrieves the number of items with the specified type as defined by the Item subclass public field ITEM_TYPE matching the optional specified condition and aggregated according to the specified BaseAggregate.

Parameters:

filter - the condition the items must match or null if no filtering is needed

aggregate - an aggregate specifying how matching items must be bundled

itemType - the String representation of the item type we want to retrieve the count of, as defined by its class' ITEM_TYPE field

size - size of returned buckets in the response

Returns:

a Map associating aggregation dimension name as key and cardinality for that dimension as value

refresh

void refresh()

Updates the persistence's engine indices if needed.

refreshIndex

default <T extends Item> void refreshIndex(Class<T> clazz)

Updates the persistence's engine specific index.

Type Parameters:

T - a class that extends Item

Parameters:

clazz - will use an index by class type

refreshIndex

@Deprecated
<T extends Item> void refreshIndex(Class<T> clazz,
                                               Date dateHint)

Deprecated. use refreshIndex(Class)

purge

@Deprecated
void purge(Date date)

Deprecated.

deprecated: (use: purgeTimeBasedItems instead)

purgeTimeBasedItems

<T extends Item> void purgeTimeBasedItems(int existsNumberOfDays,
                                          Class<T> clazz)

Purges time based data in the context server up to the specified days number of existence. (This only works for time based data stored in rolling over indices, it have no effect on other types)

Parameters:

existsNumberOfDays - the number of days

clazz - the item type to be purged

rangeQuery

<T extends Item> PartialList<T> rangeQuery(String s,
                                           String from,
                                           String to,
                                           String sortBy,
                                           Class<T> clazz,
                                           int offset,
                                           int size)

Retrieves all items of the specified Item subclass which specified ranged property is within the specified bounds, ordered according to the specified sortBy String and and paged: only size of them are retrieved, starting with the offset-th one.

Type Parameters:

T - the type of the Item subclass we want to retrieve

Parameters:

s - the name of the range property we want items to retrieve to be included between the specified start and end points

from - the beginning of the range we want to consider

to - the end of the range we want to consider

sortBy - an optional (null if no sorting is required) String of comma (,) separated property names on which ordering should be performed, ordering elements according to the property order in the String, considering each in turn and moving on to the next one in case of equality of all preceding ones. Each property name is optionally followed by a column (:) and an order specifier: asc or desc.

clazz - the Item subclass of the items we want to retrieve

offset - zero or a positive integer specifying the position of the first item in the total ordered collection of matching items

size - a positive integer specifying how many matching items should be retrieved or -1 if all of them should be retrieved

Returns:

a PartialList of items matching the specified criteria

getSingleValuesMetrics

Map<String,Double> getSingleValuesMetrics(Condition condition,
                                          String[] metrics,
                                          String field,
                                          String type)

Retrieves the specified metrics for the specified field of items of the specified type as defined by the Item subclass public field ITEM_TYPE and matching the specified Condition.

Parameters:

condition - the condition the items must satisfy

metrics - a String array which metrics should be computed (possible values: sum for the sum of the values, avg for the average of the values, min for the minimum value and max for the maximum value)

field - the name of the field for which the metrics should be computed

type - the String representation of the item type we want to retrieve the count of, as defined by its class' ITEM_TYPE field

Returns:

a Map associating computed metric name as key to its associated value

createIndex

boolean createIndex(String itemType)

Creates an index with for the specified item type in the persistence engine.

TODO: remove from API?

Parameters:

itemType - the item type

Returns:

true if the operation was successful, false otherwise

removeIndex

boolean removeIndex(String itemType)

Removes the index for the specified item type.

TODO: remove from API?

Parameters:

itemType - the item type

Returns:

true if the operation was successful, false otherwise

purge

void purge(String scope)

Removes all data associated with the provided scope.

Parameters:

scope - the scope for which we want to remove data