org.apache.unomi.persistence.spi.PersistenceService Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.unomi.persistence.spi;
import org.apache.unomi.api.CustomItem;
import org.apache.unomi.api.Item;
import org.apache.unomi.api.PartialList;
import org.apache.unomi.api.PropertyType;
import org.apache.unomi.api.conditions.Condition;
import org.apache.unomi.persistence.spi.aggregate.BaseAggregate;
import java.util.Date;
import java.util.List;
import java.util.Map;
import java.util.function.Consumer;
/**
* A service to provide persistence and retrieval of context server entities.
*/
public interface PersistenceService {
/**
* Retrieves all known items of the specified class.
* WARNING: this method can be quite computationally intensive and calling the paged version {@link #getAllItems(Class, int, int, String)} is preferred.
*
* @param the type of the {@link Item}s we want to retrieve
* @param clazz the {@link Item} subclass of entities we want to retrieve
* @return a list of all known items with the given type
*/
List getAllItems(Class clazz);
/**
* Retrieves all known items of the specified class, ordered according to the specified {@code sortBy} String and and paged: only {@code size} of them are retrieved,
* starting with the {@code offset}-th one.
*
* TODO: use a Query object instead of distinct parameters?
*
* @param the type of the {@link Item}s we want to retrieve
* @param clazz the {@link Item} subclass of entities we want to retrieve
* @param offset zero or a positive integer specifying the position of the first item in the total ordered collection of matching items
* @param size a positive integer specifying how many matching items should be retrieved or {@code -1} if all of them should be retrieved
* @param sortBy an optional ({@code null} if no sorting is required) String of comma ({@code ,}) 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 ({@code :}) and an order specifier: {@code asc} or {@code desc}.
* @return a {@link PartialList} of pages items with the given type
*/
PartialList getAllItems(Class clazz, int offset, int size, String sortBy);
/**
* Retrieves all known items of the specified class, ordered according to the specified {@code sortBy} String and and paged: only {@code size} of them are retrieved,
* starting with the {@code offset}-th one.
*
* TODO: use a Query object instead of distinct parameters?
*
* @param the type of the {@link Item}s we want to retrieve
* @param clazz the {@link Item} subclass of entities we want to retrieve
* @param offset zero or a positive integer specifying the position of the first item in the total ordered collection of matching items
* @param size a positive integer specifying how many matching items should be retrieved or {@code -1} if all of them should be retrieved
* @param sortBy an optional ({@code null} if no sorting is required) String of comma ({@code ,}) 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 ({@code :}) and an order specifier: {@code asc} or {@code desc}.
* @param 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
* @return a {@link PartialList} of pages items with the given type
*/
PartialList getAllItems(final Class clazz, int offset, int size, String sortBy, String scrollTimeValidity);
/**
* Return true if the item which is saved in the persistence service is consistent
*
* @param item the item to the check if consistent
* @return {@code true} if the item is consistent, false otherwise
*/
boolean isConsistent(Item item);
/**
* Persists the specified Item in the context server.
*
* @param item the item to persist
* @return {@code true} if the item was properly persisted, {@code false} otherwise
*/
boolean save(Item item);
/**
* Persists the specified Item in the context server.
*
* @param item the item to persist
* @param 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.
* @return {@code true} if the item was properly persisted, {@code false} otherwise
*/
boolean save(Item item, boolean useBatching);
/**
* Persists the specified Item in the context server.
*
* @param item the item to persist
* @param 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
* @param alwaysOverwrite whether to overwrite a document even if we are holding an old item when saving
* @return {@code true} if the item was properly persisted, {@code false} otherwise
*/
boolean save(Item item, Boolean useBatching, 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.
*
* @param item the item we want to update
* @param clazz the Item subclass of the item to update
* @param source a Map with entries specifying as key the property name to update and as value its new value
* @return {@code true} if the update was successful, {@code false} otherwise
*/
default boolean update(Item item, Class clazz, Map source) {
return update(item, null, clazz, source);
}
/**
* @deprecated use {@link #update(Item, Class, Map)}
*/
@Deprecated
boolean update(Item item, Date dateHint, Class clazz, Map source);
/**
* 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
* {@code update(itemId, clazz, Collections.singletonMap(propertyName, propertyValue))}
*
* @param item the item we want to update
* @param clazz the Item subclass of the item to update
* @param propertyName the name of the property to update
* @param propertyValue the new value of the property
* @return {@code true} if the update was successful, {@code false} otherwise
*/
default boolean update(Item item, Class clazz, String propertyName, Object propertyValue) {
return update(item, null, clazz, propertyName, propertyValue);
}
/**
* @deprecated use {@link #update(Item, Class, String, Object)}
*/
@Deprecated
boolean update(Item item, Date dateHint, Class clazz, String propertyName, Object propertyValue);
/**
* 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.
*
* @param item the item we want to update
* @param clazz the Item subclass of the item to update
* @param source a Map with entries specifying as key the property name to update and as value its new value
* @param alwaysOverwrite whether to overwrite a document even if we are holding an old item when saving
* @return {@code true} if the update was successful, {@code false} otherwise
*/
default boolean update(Item item, Class clazz, Map source, final boolean alwaysOverwrite) {
return update(item, null, clazz, source, alwaysOverwrite);
}
/**
* @deprecated use {@link #update(Item, Class, Map, boolean)}
*/
@Deprecated
boolean update(Item item, Date dateHint, Class clazz, Map source, final boolean alwaysOverwrite);
/**
* 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
* {@code update(itemId, clazz, Collections.singletonMap(propertyName, propertyValue))}
*
* @param items A map the consist of item (key) and properties to update (value)
* @param clazz the Item subclass of the item to update
* @return List of failed Items Ids, if all succesful then returns an empty list. if the whole operation failed then will return null
*/
default List update(Map items, Class clazz) {
return update(items, null, clazz);
}
/**
* @deprecated use {@link #update(Map, Class)}
*/
@Deprecated
List update(Map items, Date dateHint, Class clazz);
/**
* 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
* {@code update(itemId, clazz, Collections.singletonMap(propertyName, propertyValue))}
*
* @param item the item we want to update
* @param clazz the Item subclass of the item to update
* @param script inline script
* @param scriptParams script params
* @return {@code true} if the update was successful, {@code false} otherwise
*/
default boolean updateWithScript(Item item, Class clazz, String script, Map scriptParams) {
return updateWithScript(item, null, clazz, script, scriptParams);
}
/**
* @deprecated use {@link #updateWithScript(Item, Class, String, Map)}
*/
@Deprecated
boolean updateWithScript(Item item, Date dateHint, Class clazz, String script, Map scriptParams);
/**
* 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
*
* @param clazz the Item subclass of the item to update
* @param scripts inline scripts array
* @param scriptParams script params array
* @param conditions conditions array
* @return {@code true} if the update was successful, {@code false} otherwise
*/
default boolean updateWithQueryAndScript(Class clazz, String[] scripts, Map[] scriptParams, Condition[] conditions) {
return updateWithQueryAndScript(null, clazz, scripts, scriptParams, conditions);
}
/**
* @deprecated use {@link #updateWithQueryAndScript(Class, String[], Map[], Condition[])}
*/
@Deprecated
boolean updateWithQueryAndScript(Date dateHint, Class clazz, String[] scripts, Map[] 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
*
* @param clazz the Item subclass of the item to update
* @param scripts Stored scripts name
* @param scriptParams script params array
* @param conditions conditions array
* @return {@code true} if the update was successful, {@code false} otherwise
*/
default boolean updateWithQueryAndStoredScript(Class clazz, String[] scripts, Map[] scriptParams, Condition[] conditions) {
return updateWithQueryAndStoredScript(null, clazz, scripts, scriptParams, 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,
* This one is able to perform an update on multiple types in a single run, be careful with your query as it will be performed on all of them.
*
* @param classes classes of items to update, be careful all of them will be submitted to update for all scripts/conditions
* @param scripts Stored scripts name
* @param scriptParams script params array
* @param conditions conditions array
* @param waitForComplete if true, wait for the ES execution to be complete
* @return {@code true} if the update was successful, {@code false} otherwise
*/
boolean updateWithQueryAndStoredScript(Class[] classes, String[] scripts, Map[] scriptParams, Condition[] conditions, boolean waitForComplete);
/**
* @deprecated use {@link #updateWithQueryAndStoredScript(Class, String[], Map[], Condition[])}
*/
@Deprecated
boolean updateWithQueryAndStoredScript(Date dateHint, Class clazz, String[] scripts, Map[] scriptParams, Condition[] conditions);
/**
* Store script in the Database for later usage with updateWithQueryAndStoredScript function for example.
*
* @param scripts inline scripts map indexed by id
* @return {@code true} if the update was successful, {@code false} otherwise
*/
boolean storeScripts(Map scripts);
/**
* Retrieves the item identified with the specified identifier and with the specified Item subclass if it exists.
*
* @param the type of the Item subclass we want to retrieve
* @param itemId the identifier of the item we want to retrieve
* @param clazz the {@link Item} subclass of the item we want to retrieve
* @return the item identified with the specified identifier and with the specified Item subclass if it exists, {@code null} otherwise
*/
T load(String itemId, Class clazz);
/**
* @deprecated use {@link #load(String, Class)}
*/
@Deprecated
T load(String itemId, Date dateHint, Class clazz);
/**
* Load a custom item type identified by an identifier, an optional date hint and the identifier of the custom item type
*
* @param itemId the identifier of the custom type we want to retrieve
* @param customItemType an identifier of the custom item type to load
* @return the CustomItem instance with the specified identifier and the custom item type if it exists, {@code null} otherwise
*/
default CustomItem loadCustomItem(String itemId, String customItemType) {
return loadCustomItem(itemId, null, customItemType);
}
/**
* @deprecated use {@link #loadCustomItem(String, String)}
*/
@Deprecated
CustomItem loadCustomItem(String itemId, Date dateHint, String customItemType);
/**
* Deletes the item identified with the specified identifier and with the specified Item subclass if it exists.
*
* @param the type of the Item subclass we want to delete
* @param itemId the identifier of the item we want to delete
* @param clazz the {@link Item} subclass of the item we want to delete
* @return {@code true} if the deletion was successful, {@code false} otherwise
*/
boolean remove(String itemId, Class clazz);
/**
* Remove a custom item identified by the custom item identifier and the custom item type identifier
*
* @param itemId the identifier of the custom item to be removed
* @param customItemType the name of the custom item type
* @return {@code true} if the deletion was successful, {@code false} otherwise
*/
boolean removeCustomItem(String itemId, String customItemType);
/**
* Deletes items with the specified Item subclass matching the specified {@link Condition}.
*
* @param the type of the Item subclass we want to delete
* @param query a {@link Condition} identifying which elements we want to delete
* @param clazz the {@link Item} subclass of the items we want to delete
* @return {@code true} if the deletion was successful, {@code false} otherwise
*/
boolean removeByQuery(Condition query, Class clazz);
/**
* Persists the specified query under the specified name.
*
* @param queryName the name under which the specified query should be recorded
* @param query the query to be recorded
* @return {@code true} if the query was properly saved, {@code false} otherwise
*/
boolean saveQuery(String queryName, Condition query);
/**
* Deletes the query identified by the specified name.
*
* @param queryName the name under which the specified query was recorded
* @return {@code true} if the deletion was successful, {@code false} otherwise
*/
boolean removeQuery(String queryName);
/**
* 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
*
* @param itemType the itemType we want to retrieve the mappings for
* @return properties mapping
*/
Map> getPropertiesMapping(String itemType);
/**
* Retrieve the mapping for one specific property for a given type.
*
* @param property the property name (can use nested dot notation)
* @param itemType the itemType we want to retrieve the mappings for
* @return property mapping
*/
Map getPropertyMapping(String property, String itemType);
/**
* Create the persistence mapping for specific property for a given type.
*
* @param property the PropertyType to create mapping for
* @param itemType the itemType we want to retrieve the mappings for
*/
void setPropertyMapping(PropertyType property, String itemType);
/**
* Create mapping
*
* @param type the type
* @param source the source
*/
void createMapping(String type, String source);
/**
* Checks whether the specified item satisfies the provided condition.
*
* TODO: rename to isMatching?
*
* @param query the condition we're testing the specified item against
* @param item the item we're checking against the specified condition
* @return {@code true} if the item satisfies the condition, {@code false} otherwise
*/
boolean testMatch(Condition query, Item item);
/**
* validates if a condition throws exception at query build.
*
* @param condition the condition we're testing the specified item against
* @param item the item we're checking against the specified condition
* @return {@code true} if the item satisfies the condition, {@code false} otherwise
*/
boolean isValidCondition(Condition condition, Item item);
/**
* Same as {@code query(fieldName, fieldValue, sortBy, clazz, 0, -1).getList()}
*
* @param the type of the Item subclass we want to retrieve
* @param fieldName the name of the field which we want items to have the specified values
* @param fieldValue the value the items to retrieve should have for the specified field
* @param sortBy an optional ({@code null} if no sorting is required) String of comma ({@code ,}) 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 ({@code :}) and an order specifier: {@code asc} or {@code desc}.
* @param clazz the {@link Item} subclass of the items we want to retrieve
* @return a list of items matching the specified criteria
* @see #query(Condition, String, Class, int, int)
*/
List query(String fieldName, String fieldValue, String sortBy, Class clazz);
/**
* Retrieves a list of items with the specified field having the specified values.
*
* @param the type of the Item subclass we want to retrieve
* @param fieldName the name of the field which we want items to have the specified values
* @param fieldValues the values the items to retrieve should have for the specified field
* @param sortBy an optional ({@code null} if no sorting is required) String of comma ({@code ,}) 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 ({@code :}) and an order specifier: {@code asc} or {@code desc}.
* @param clazz the {@link Item} subclass of the items we want to retrieve
* @return a list of items matching the specified criteria
*/
List query(String fieldName, String[] fieldValues, String sortBy, Class clazz);
/**
* Retrieves a list of items with the specified field having the specified value.
*
* @param the type of the Item subclass we want to retrieve
* @param fieldName the name of the field which we want items to have the specified value
* @param fieldValue the value the items to retrieve should have for the specified field
* @param sortBy an optional ({@code null} if no sorting is required) String of comma ({@code ,}) 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 ({@code :}) and an order specifier: {@code asc} or {@code desc}.
* @param clazz the {@link Item} subclass of the items we want to retrieve
* @param offset zero or a positive integer specifying the position of the first item in the total ordered collection of matching items
* @param size a positive integer specifying how many matching items should be retrieved or {@code -1} if all of them should be retrieved
* @return a {@link PartialList} of items matching the specified criteria
*/
PartialList query(String fieldName, String fieldValue, String sortBy, Class 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 {@code sortBy} String and and paged: only {@code size} of them are retrieved, starting with the {@code offset}-th one.
*
* @param the type of the Item subclass we want to retrieve
* @param fieldName the name of the field which we want items to have the specified value
* @param fieldValue the value the items to retrieve should have for the specified field
* @param fulltext the text that the item must have in one of its fields to be considered a match
* @param sortBy an optional ({@code null} if no sorting is required) String of comma ({@code ,}) 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 ({@code :}) and an order specifier: {@code asc} or {@code desc}.
* @param clazz the {@link Item} subclass of the items we want to retrieve
* @param offset zero or a positive integer specifying the position of the first item in the total ordered collection of matching items
* @param size a positive integer specifying how many matching items should be retrieved or {@code -1} if all of them should be retrieved
* @return a {@link PartialList} of items matching the specified criteria
*/
PartialList queryFullText(String fieldName, String fieldValue, String fulltext, String sortBy, Class 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 {@code sortBy} String and and paged: only
* {@code size} of them are retrieved, starting with the {@code offset}-th one.
*
* @param the type of the Item subclass we want to retrieve
* @param fulltext the text that the item must have in one of its fields to be considered a match
* @param sortBy an optional ({@code null} if no sorting is required) String of comma ({@code ,}) 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 ({@code :}) and an order specifier: {@code asc} or {@code desc}.
* @param clazz the {@link Item} subclass of the items we want to retrieve
* @param offset zero or a positive integer specifying the position of the first item in the total ordered collection of matching items
* @param size a positive integer specifying how many matching items should be retrieved or {@code -1} if all of them should be retrieved
* @return a {@link PartialList} of items matching the specified criteria
*/
PartialList queryFullText(String fulltext, String sortBy, Class clazz, int offset, int size);
/**
* Same as {@code query(query, sortBy, clazz, 0, -1).getList()}
*
* @param the type of the Item subclass we want to retrieve
* @param query the {@link Condition} the items must satisfy to be retrieved
* @param sortBy an optional ({@code null} if no sorting is required) String of comma ({@code ,}) 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 ({@code :}) and an order specifier: {@code asc} or {@code desc}.
* @param clazz the {@link Item} subclass of the items we want to retrieve
* @return a {@link PartialList} of items matching the specified criteria
* @see #query(Condition, String, Class, int, int)
*/
List query(Condition query, String sortBy, Class clazz);
/**
* Retrieves a list of items satisfying the specified {@link Condition}, ordered according to the specified {@code sortBy} String and and paged: only {@code size} of them
* are retrieved, starting with the {@code offset}-th one.
*
* @param the type of the Item subclass we want to retrieve
* @param query the {@link Condition} the items must satisfy to be retrieved
* @param sortBy an optional ({@code null} if no sorting is required) String of comma ({@code ,}) 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 ({@code :}) and an order specifier: {@code asc} or {@code desc}.
* @param clazz the {@link Item} subclass of the items we want to retrieve
* @param offset zero or a positive integer specifying the position of the first item in the total ordered collection of matching items
* @param size a positive integer specifying how many matching items should be retrieved or {@code -1} if all of them should be retrieved
* @return a {@link PartialList} of items matching the specified criteria
*/
PartialList query(Condition query, String sortBy, Class clazz, int offset, int size);
/**
* Retrieves a list of items satisfying the specified {@link Condition}, ordered according to the specified {@code sortBy} String and and paged: only {@code size} of them
* are retrieved, starting with the {@code 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.
*
* @param the type of the Item subclass we want to retrieve
* @param query the {@link Condition} the items must satisfy to be retrieved
* @param sortBy an optional ({@code null} if no sorting is required) String of comma ({@code ,}) 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 ({@code :}) and an order specifier: {@code asc} or {@code desc}.
* @param clazz the {@link Item} subclass of the items we want to retrieve
* @param offset zero or a positive integer specifying the position of the first item in the total ordered collection of matching items
* @param size a positive integer specifying how many matching items should be retrieved or {@code -1} if all of them should be retrieved. In the case of a scroll query
* this will be used as the scrolling window size.
* @param 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
* @return a {@link PartialList} of items matching the specified criteria, with an scroll identifier and the scroll validity used if a scroll query was requested.
*/
PartialList query(Condition query, String sortBy, Class clazz, int offset, int size, 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.
*
* @param clazz the {@link Item} subclass of the items we want to retrieve
* @param scrollIdentifier a scroll identifier obtained by the execution of a first query and returned in the {@link PartialList} object
* @param 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
* @param the type of the Item subclass we want to retrieve
* @return a {@link 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.
*/
PartialList continueScrollQuery(Class clazz, String scrollIdentifier, String scrollTimeValidity);
/**
* Retrieves a list of items satisfying the specified {@link Condition}, ordered according to the specified
* {@code sortBy} String and paged: only {@code size} of them are retrieved, starting with the
* {@code 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.
*
* @param query the {@link Condition} the items must satisfy to be retrieved
* @param sortBy an optional ({@code null} if no sorting is required) String of comma ({@code ,}) 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 ({@code :}) and an order specifier: {@code asc} or {@code desc}.
* @param customItemType the identifier of the custom item type we want to query
* @param offset zero or a positive integer specifying the position of the first item in the total ordered collection of matching items
* @param size a positive integer specifying how many matching items should be retrieved or {@code -1} if all of them should be retrieved. In the case of a scroll query
* this will be used as the scrolling window size.
* @param 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
* @return a {@link PartialList} of items matching the specified criteria, with an scroll identifier and the scroll validity used if a scroll query was requested.
*/
PartialList queryCustomItem(Condition query, String sortBy, String customItemType, int offset, int size, 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.
*
* @param customItemType the identifier of the custom item type we want to continue querying
* @param scrollIdentifier a scroll identifier obtained by the execution of a first query and returned in the {@link PartialList} object
* @param 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
* @return a {@link 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.
*/
PartialList continueCustomItemScrollQuery(String customItemType, String scrollIdentifier, String scrollTimeValidity);
/**
* Retrieves the same items as {@code 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.
*
* @param the type of the Item subclass we want to retrieve
* @param fulltext the text that the item must have in one of its fields to be considered a match
* @param query the {@link Condition} the items must satisfy to be retrieved
* @param sortBy an optional ({@code null} if no sorting is required) String of comma ({@code ,}) 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 ({@code :}) and an order specifier: {@code asc} or {@code desc}.
* @param clazz the {@link Item} subclass of the items we want to retrieve
* @param offset zero or a positive integer specifying the position of the first item in the total ordered collection of matching items
* @param size a positive integer specifying how many matching items should be retrieved or {@code -1} if all of them should be retrieved
* @return a {@link PartialList} of items matching the specified criteria
*/
PartialList queryFullText(String fulltext, Condition query, String sortBy, Class clazz, int offset, int size);
/**
* Retrieves the number of items of the specified type as defined by the Item subclass public field {@code ITEM_TYPE} and matching the specified {@link Condition}.
*
* @param query the condition the items must satisfy
* @param itemType the String representation of the item type we want to retrieve the count of, as defined by its class' {@code ITEM_TYPE} field
* @return the number of items of the specified type
* @see Item Item for a discussion of {@code ITEM_TYPE}
*/
long queryCount(Condition query, String itemType);
/**
* Retrieves the number of items with the specified type as defined by the Item subclass public field {@code ITEM_TYPE}.
*
* @param itemType the String representation of the item type we want to retrieve the count of, as defined by its class' {@code ITEM_TYPE} field
* @return the number of items of the specified type
* @see Item Item for a discussion of {@code ITEM_TYPE}
*/
long getAllItemsCount(String itemType);
/**
* Retrieves the number of items with the specified type as defined by the Item subclass public field {@code ITEM_TYPE} matching the optional specified condition and
* aggregated according to the specified {@link BaseAggregate}.
* Also return the global count of document matching the {@code ITEM_TYPE}
*
* @param filter the condition the items must match or {@code null} if no filtering is needed
* @param aggregate an aggregate specifying how matching items must be bundled
* @param itemType the String representation of the item type we want to retrieve the count of, as defined by its class' {@code ITEM_TYPE} field
* @return a Map associating aggregation dimension name as key and cardinality for that dimension as value
* @deprecated As of 1.3.0-incubating, please use {@link #aggregateWithOptimizedQuery(Condition, BaseAggregate, String)} instead
*/
@Deprecated
Map aggregateQuery(Condition filter, BaseAggregate aggregate, String itemType);
/**
* Retrieves the number of items with the specified type as defined by the Item subclass public field {@code ITEM_TYPE} matching the optional specified condition and
* aggregated according to the specified {@link BaseAggregate}.
* This aggregate won't return the global count and should therefore be much faster than {@link #aggregateQuery(Condition, BaseAggregate, String)}
*
* @param filter the condition the items must match or {@code null} if no filtering is needed
* @param aggregate an aggregate specifying how matching items must be bundled
* @param itemType the String representation of the item type we want to retrieve the count of, as defined by its class' {@code ITEM_TYPE} field
* @return a Map associating aggregation dimension name as key and cardinality for that dimension as value
*/
Map aggregateWithOptimizedQuery(Condition filter, BaseAggregate aggregate, String itemType);
/**
* Retrieves the number of items with the specified type as defined by the Item subclass public field {@code ITEM_TYPE} matching the optional specified condition and
* aggregated according to the specified {@link BaseAggregate}.
*
* @param filter the condition the items must match or {@code null} if no filtering is needed
* @param aggregate an aggregate specifying how matching items must be bundled
* @param itemType the String representation of the item type we want to retrieve the count of, as defined by its class' {@code ITEM_TYPE} field
* @param size size of returned buckets in the response
* @return a Map associating aggregation dimension name as key and cardinality for that dimension as value
*/
Map aggregateWithOptimizedQuery(Condition filter, BaseAggregate aggregate, String itemType, int size);
/**
* Updates the persistence's engine indices if needed.
*/
void refresh();
/**
* Updates the persistence's engine specific index.
*
* @param clazz will use an index by class type
* @param a class that extends Item
*/
default void refreshIndex(Class clazz) {
refreshIndex(clazz, null);
}
/**
* @deprecated use {@link #refreshIndex(Class)}
*/
@Deprecated
void refreshIndex(Class clazz, Date dateHint);
/**
* deprecated: (use: purgeTimeBasedItems instead)
*/
@Deprecated
void purge(Date date);
/**
* 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)
*
* @param existsNumberOfDays the number of days
* @param clazz the item type to be purged
*/
void purgeTimeBasedItems(int existsNumberOfDays, Class clazz);
/**
* Retrieves all items of the specified Item subclass which specified ranged property is within the specified bounds, ordered according to the specified {@code sortBy} String
* and and paged: only {@code size} of them are retrieved, starting with the {@code offset}-th one.
*
* @param the type of the Item subclass we want to retrieve
* @param s the name of the range property we want items to retrieve to be included between the specified start and end points
* @param from the beginning of the range we want to consider
* @param to the end of the range we want to consider
* @param sortBy an optional ({@code null} if no sorting is required) String of comma ({@code ,}) 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 ({@code :}) and an order specifier: {@code asc} or {@code desc}.
* @param clazz the {@link Item} subclass of the items we want to retrieve
* @param offset zero or a positive integer specifying the position of the first item in the total ordered collection of matching items
* @param size a positive integer specifying how many matching items should be retrieved or {@code -1} if all of them should be retrieved
* @return a {@link PartialList} of items matching the specified criteria
*/
PartialList rangeQuery(String s, String from, String to, String sortBy, Class clazz, int offset, int size);
/**
* Retrieves the specified metrics for the specified field of items of the specified type as defined by the Item subclass public field {@code ITEM_TYPE} and matching the
* specified {@link Condition}.
*
* @param condition the condition the items must satisfy
* @param metrics a String array which metrics should be computed (possible values: {@code sum} for the sum of the values, {@code avg} for the average of the values, {@code
* min} for the minimum value and {@code max} for the maximum value)
* @param field the name of the field for which the metrics should be computed
* @param type the String representation of the item type we want to retrieve the count of, as defined by its class' {@code ITEM_TYPE} field
* @return a Map associating computed metric name as key to its associated value
*/
Map getSingleValuesMetrics(Condition condition, String[] metrics, String field, String type);
/**
* Creates an index with for the specified item type in the persistence engine.
*
* TODO: remove from API?
*
* @param itemType the item type
* @return {@code true} if the operation was successful, {@code false} otherwise
*/
boolean createIndex(final String itemType);
/**
* Removes the index for the specified item type.
*
* TODO: remove from API?
*
* @param itemType the item type
* @return {@code true} if the operation was successful, {@code false} otherwise
*/
boolean removeIndex(final String itemType);
/**
* Removes all data associated with the provided scope.
*
* @param scope the scope for which we want to remove data
*/
void purge(final String scope);
}