Class PersistenceExtensions


  • public class PersistenceExtensions
    extends Object
    This class provides static methods that can be used in automation rules for using persistence services
    Author:
    Kai Kreuzer - Initial contribution, Thomas Eichstaedt-Engelen - Initial contribution, Chris Jackson - Initial contribution, Gaƫl L'hopital - Add deltaSince, lastUpdate, evolutionRate, Jan N. Klug - Added sumSince, John Cocula - Added sumSince
    • Constructor Detail

      • PersistenceExtensions

        public PersistenceExtensions()
    • Method Detail

      • setTimeZoneProvider

        protected void setTimeZoneProvider​(TimeZoneProvider timeZoneProvider)
      • unsetTimeZoneProvider

        protected void unsetTimeZoneProvider​(TimeZoneProvider timeZoneProvider)
      • persist

        public static void persist​(Item item,
                                   String serviceId)
        Persists the state of a given item through a PersistenceService identified by the serviceId.
        Parameters:
        item - the item to store
        serviceId - the name of the PersistenceService to use
      • persist

        public static void persist​(Item item)
        Persists the state of a given item through the default persistence service.
        Parameters:
        item - the item to store
      • historicState

        public static HistoricItem historicState​(Item item,
                                                 org.joda.time.base.AbstractInstant timestamp)
        Retrieves the historic item for a given item at a certain point in time through the default persistence service.
        Parameters:
        item - the item for which to retrieve the historic item
        timestamp - the point in time for which the historic item should be retrieved
        Returns:
        the historic item at the given point in time, or null if no historic item could be found, the default persistence service is not available or does not refer to a QueryablePersistenceService
      • historicState

        public static HistoricItem historicState​(Item item,
                                                 org.joda.time.base.AbstractInstant timestamp,
                                                 String serviceId)
        Retrieves the historic item for a given item at a certain point in time through a PersistenceService identified by the serviceId.
        Parameters:
        item - the item for which to retrieve the historic item
        timestamp - the point in time for which the historic item should be retrieved
        serviceId - the name of the PersistenceService to use
        Returns:
        the historic item at the given point in time, or null if no historic item could be found or if the provided serviceId does not refer to an available QueryablePersistenceService
      • changedSince

        public static Boolean changedSince​(Item item,
                                           org.joda.time.base.AbstractInstant timestamp)
        Checks if the state of a given item has changed since a certain point in time. The default persistence service is used.
        Parameters:
        item - the item to check for state changes
        timestamp - the point in time to start the check
        Returns:
        true if item state had changed, false if it hasn't or if the default persistence service does not refer to a QueryablePersistenceService, or null if the default persistence service is not available
      • changedSince

        public static Boolean changedSince​(Item item,
                                           org.joda.time.base.AbstractInstant timestamp,
                                           String serviceId)
        Checks if the state of a given item has changed since a certain point in time. The PersistenceService identified by the serviceId is used.
        Parameters:
        item - the item to check for state changes
        timestamp - the point in time to start the check
        serviceId - the name of the PersistenceService to use
        Returns:
        true if item state has changed, or false if it hasn't or if the given serviceId does not refer to an available QueryablePersistenceService
      • updatedSince

        public static Boolean updatedSince​(Item item,
                                           org.joda.time.base.AbstractInstant timestamp)
        Checks if the state of a given item has been updated since a certain point in time. The default persistence service is used.
        Parameters:
        item - the item to check for state updates
        timestamp - the point in time to start the check
        Returns:
        true if item state was updated, false if either item has not been updated since timestamp or if the default persistence does not refer to a QueryablePersistenceService, or null if the default persistence service is not available
      • updatedSince

        public static Boolean updatedSince​(Item item,
                                           org.joda.time.base.AbstractInstant timestamp,
                                           String serviceId)
        Checks if the state of a given item has changed since a certain point in time. The PersistenceService identified by the serviceId is used.
        Parameters:
        item - the item to check for state changes
        timestamp - the point in time to start the check
        serviceId - the name of the PersistenceService to use
        Returns:
        true if item state was updated or false if either the item has not been updated since timestamp or if the given serviceId does not refer to a QueryablePersistenceService
      • maximumSince

        public static HistoricItem maximumSince​(Item item,
                                                org.joda.time.base.AbstractInstant timestamp)
        Gets the historic item with the maximum value of the state of a given item since a certain point in time. The default persistence service is used.
        Parameters:
        item - the item to get the maximum state value for
        timestamp - the point in time to start the check
        Returns:
        a historic item with the maximum state value since the given point in time, or null if the default persistence service is not available, or a HistoricItem constructed from the item if the default persistence service does not refer to a QueryablePersistenceService
      • maximumSince

        public static HistoricItem maximumSince​(Item item,
                                                org.joda.time.base.AbstractInstant timestamp,
                                                String serviceId)
        Gets the historic item with the maximum value of the state of a given item since a certain point in time. The PersistenceService identified by the serviceId is used.
        Parameters:
        item - the item to get the maximum state value for
        timestamp - the point in time to start the check
        serviceId - the name of the PersistenceService to use
        Returns:
        a HistoricItem with the maximum state value since the given point in time, or a HistoricItem constructed from the item's state if item's state is the maximum value or if the given serviceId does not refer to an available QueryablePersistenceService
      • minimumSince

        public static HistoricItem minimumSince​(Item item,
                                                org.joda.time.base.AbstractInstant timestamp)
        Gets the historic item with the minimum value of the state of a given item since a certain point in time. The default persistence service is used.
        Parameters:
        item - the item to get the minimum state value for
        timestamp - the point in time from which to search for the minimum state value
        Returns:
        the historic item with the minimum state value since the given point in time, null if the default persistence service is not available, or a HistoricItem constructed from the item's state if item's state is the minimum value or if the default persistence service does not refer to an available QueryablePersistenceService
      • minimumSince

        public static HistoricItem minimumSince​(Item item,
                                                org.joda.time.base.AbstractInstant timestamp,
                                                String serviceId)
        Gets the historic item with the minimum value of the state of a given item since a certain point in time. The PersistenceService identified by the serviceId is used.
        Parameters:
        item - the item to get the minimum state value for
        timestamp - the point in time from which to search for the minimum state value
        serviceId - the name of the PersistenceService to use
        Returns:
        the historic item with the minimum state value since the given point in time, or a HistoricItem constructed from the item's state if item's state is the minimum value or if the given serviceId does not refer to an available QueryablePersistenceService
      • averageSince

        public static DecimalType averageSince​(Item item,
                                               org.joda.time.base.AbstractInstant timestamp)
        Gets the average value of the state of a given item since a certain point in time. The default persistence service is used.
        Parameters:
        item - the item to get the average state value for
        timestamp - the point in time from which to search for the average state value
        Returns:
        the average state values since timestamp, null if the default persistence service is not available, or the state of the given item if no previous states could be found or if the default persistence service does not refer to an available QueryablePersistenceService
      • averageSince

        public static DecimalType averageSince​(Item item,
                                               org.joda.time.base.AbstractInstant timestamp,
                                               String serviceId)
        Gets the average value of the state of a given item since a certain point in time. The PersistenceService identified by the serviceId is used.
        Parameters:
        item - the item to get the average state value for
        timestamp - the point in time from which to search for the average state value
        serviceId - the name of the PersistenceService to use
        Returns:
        the average state values since timestamp, or the state of the given item if no previous states could be found or if the persistence service given by serviceId does not refer to an available QueryablePersistenceService
      • sumSince

        public static DecimalType sumSince​(Item item,
                                           org.joda.time.base.AbstractInstant timestamp)
        Gets the sum of the state of a given item since a certain point in time. The default persistence service is used.
        Parameters:
        item - the item for which we will sum its persisted state values since timestamp
        timestamp - the point in time from which to start the summation
        Returns:
        the sum of the state values since timestamp, null if the default persistence service is not available, or DecimalType.ZERO if no historic states could be found or if the default persistence service does not refer to a QueryablePersistenceService
      • sumSince

        public static DecimalType sumSince​(Item item,
                                           org.joda.time.base.AbstractInstant timestamp,
                                           String serviceId)
        Gets the sum of the state of a given item since a certain point in time. The PersistenceService identified by the serviceId is used.
        Parameters:
        item - the item for which we will sum its persisted state values since timestamp
        timestamp - the point in time from which to start the summation
        serviceId - the name of the PersistenceService to use
        Returns:
        the sum of the state values since the given point in time, or DecimalType.ZERO if no historic states could be found for the item or if serviceId does no refer to a QueryablePersistenceService
      • lastUpdate

        public static org.joda.time.base.AbstractInstant lastUpdate​(Item item)
        Query the last update time of a given item. The default persistence service is used.
        Parameters:
        item - the item for which the last update time is to be returned
        Returns:
        point in time of the last update to item, or null if there are no previously persisted updates or the default persistence service is not available or a QueryablePersistenceService
      • lastUpdate

        public static org.joda.time.base.AbstractInstant lastUpdate​(Item item,
                                                                    String serviceId)
        Query for the last update time of a given item.
        Parameters:
        item - the item for which the last update time is to be returned
        serviceId - the name of the PersistenceService to use
        Returns:
        last time item was updated, or null if there are no previously persisted updates or if persistence service given by serviceId does not refer to an available QueryablePersistenceService
      • deltaSince

        public static DecimalType deltaSince​(Item item,
                                             org.joda.time.base.AbstractInstant timestamp)
        Gets the difference value of the state of a given item since a certain point in time. The default persistence service is used.
        Parameters:
        item - the item to get the average state value for
        timestamp - the point in time from which to compute the delta
        Returns:
        the difference between now and then, or null if there is no default persistence service available, the default persistence service is not a QueryablePersistenceService, or if there is no persisted state for the given item at the given timestamp available in the default persistence service
      • deltaSince

        public static DecimalType deltaSince​(Item item,
                                             org.joda.time.base.AbstractInstant timestamp,
                                             String serviceId)
        Gets the difference value of the state of a given item since a certain point in time. The PersistenceService identified by the serviceId is used.
        Parameters:
        item - the item to get the average state value for
        timestamp - the point in time from which to compute the delta
        serviceId - the name of the PersistenceService to use
        Returns:
        the difference between now and then, or null if the given serviceId does not refer to an available QueryablePersistenceService, or if there is no persisted state for the given item at the given timestamp using the persistence service named serviceId
      • evolutionRate

        public static DecimalType evolutionRate​(Item item,
                                                org.joda.time.base.AbstractInstant timestamp)
        Gets the evolution rate of the state of a given item since a certain point in time. The PersistenceService identified by the serviceId is used.
        Parameters:
        item - the item to get the evolution rate value for
        timestamp - the point in time from which to compute the evolution rate
        serviceId - the name of the PersistenceService to use
        Returns:
        the evolution rate in percent (positive and negative) between now and then, or null if there is no default persistence service available, the default persistence service is not a QueryablePersistenceService, or if there is no persisted state for the given item at the given timestamp, or if there is a state but it is zero (which would cause a divide-by-zero error)
      • evolutionRate

        public static DecimalType evolutionRate​(Item item,
                                                org.joda.time.base.AbstractInstant timestamp,
                                                String serviceId)
        Gets the evolution rate of the state of a given item since a certain point in time. The PersistenceService identified by the serviceId is used.
        Parameters:
        item - the item to get the evolution rate value for
        timestamp - the point in time from which to compute the evolution rate
        serviceId - the name of the PersistenceService to use
        Returns:
        the evolution rate in percent (positive and negative) between now and then, or null if the persistence service given by serviceId is not available or is not a QueryablePersistenceService, or if there is no persisted state for the given item at the given timestamp using the persistence service given by serviceId, or if there is a state but it is zero (which would cause a divide-by-zero error)
      • previousState

        public static HistoricItem previousState​(Item item)
        Returns the previous state of a given item.
        Parameters:
        item - the item to get the previous state value for
        Returns:
        the previous state or null if no previous state could be found, or if the default persistence service is not configured or does not refer to a QueryablePersistenceService
      • previousState

        public static HistoricItem previousState​(Item item,
                                                 boolean skipEqual)
        Returns the previous state of a given item.
        Parameters:
        item - the item to get the previous state value for
        skipEqual - if true, skips equal state values and searches the first state not equal the current state
        Returns:
        the previous state or null if no previous state could be found, or if the default persistence service is not configured or does not refer to a QueryablePersistenceService
      • previousState

        public static HistoricItem previousState​(Item item,
                                                 boolean skipEqual,
                                                 String serviceId)
        Returns the previous state of a given item. The PersistenceService identified by the serviceId is used.
        Parameters:
        item - the item to get the previous state value for
        skipEqual - if true, skips equal state values and searches the first state not equal the current state
        serviceId - the name of the PersistenceService to use
        Returns:
        the previous state or null if no previous state could be found, or if the given serviceId is not available or does not refer to a QueryablePersistenceService