Interface PersistenceService

  • All Known Implementing Classes:
    ElasticSearchPersistenceServiceImpl

    public interface PersistenceService
    A service to provide persistence and retrieval of context server entities.
    • Method Summary

      All Methods Instance Methods Abstract Methods Deprecated Methods 
      Modifier and Type Method 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)
      Retrieves the item identified with the specified identifier and with the specified Item subclass if it exists.
      CustomItem loadCustomItem​(String itemId, Date dateHint, 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​(String scope)
      Removes all data associated with the provided scope.
      void purge​(Date date)
      Purges all data in the context server up to the specified date, not included.
      <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.
      <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.
      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, 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>
      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>
      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.
      <T extends Item>
      void
      refreshIndex​(Class<T> clazz, Date dateHint)
      Updates the persistence's engine specific index.
      <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.
      List<String> update​(Map<Item,​Map> items, Date dateHint, 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.
      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 a new property value for the specified property name.
      boolean update​(Item item, Date dateHint, 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.
      boolean update​(Item item, Date dateHint, 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.
      boolean updateWithQueryAndScript​(Date dateHint, 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 updateWithQueryAndStoredScript​(Date dateHint, 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 updateWithScript​(Item item, Date dateHint, 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.
    • Method Detail

      • getAllItems

        <T extends ItemList<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 ItemPartialList<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 ItemPartialList<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

        boolean update​(Item item,
                       Date dateHint,
                       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
        dateHint - a Date helping in identifying where the item is located
        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

        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 a new property value for the specified property name. Same as update(itemId, dateHint, clazz, Collections.singletonMap(propertyName, propertyValue))
        Parameters:
        item - the item we want to update
        dateHint - a Date helping in identifying where the item is located
        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

        boolean update​(Item item,
                       Date dateHint,
                       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
        dateHint - a Date helping in identifying where the item is located
        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

        List<String> update​(Map<Item,​Map> items,
                            Date dateHint,
                            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, dateHint, clazz, Collections.singletonMap(propertyName, propertyValue))
        Parameters:
        items - A map the consist of item (key) and properties to update (value)
        dateHint - a Date helping in identifying where the item is located
        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
      • updateWithScript

        boolean updateWithScript​(Item item,
                                 Date dateHint,
                                 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, dateHint, clazz, Collections.singletonMap(propertyName, propertyValue))
        Parameters:
        item - the item we want to update
        dateHint - a Date helping in identifying where the item is located
        clazz - the Item subclass of the item to update
        script - inline script
        scriptParams - script params
        Returns:
        true if the update was successful, false otherwise
      • updateWithQueryAndScript

        boolean updateWithQueryAndScript​(Date dateHint,
                                         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:
        dateHint - a Date helping in identifying where the item is located
        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
      • updateWithQueryAndStoredScript

        boolean updateWithQueryAndStoredScript​(Date dateHint,
                                               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:
        dateHint - a Date helping in identifying where the item is located
        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
      • 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

        <T extends Item> T load​(String itemId,
                                Date dateHint,
                                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
        dateHint - a Date helping in identifying where the item is located
        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
      • loadCustomItem

        CustomItem loadCustomItem​(String itemId,
                                  Date dateHint,
                                  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
        dateHint - an optional Date object if the custom item types are stored by date
        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
      • 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 ItemList<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 ItemList<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 ItemPartialList<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 ItemPartialList<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 ItemPartialList<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 ItemList<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 ItemPartialList<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 ItemPartialList<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 ItemPartialList<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 ItemPartialList<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
      • 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
      • 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

        <T extends Item> void refreshIndex​(Class<T> clazz,
                                           Date dateHint)
        Updates the persistence's engine specific index.
        Type Parameters:
        T - a class that extends Item
        Parameters:
        clazz - will use an index by class type
        dateHint - for index with time, can be null
      • purge

        void purge​(Date date)
        Purges all data in the context server up to the specified date, not included.
        Parameters:
        date - the date (not included) before which we want to erase all data
      • rangeQuery

        <T extends ItemPartialList<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