Package google.registry.model.common

Class TimedTransitionProperty<V,​T extends TimedTransitionProperty.TimedTransition<V>>

  • All Implemented Interfaces:
    java.util.Map<org.joda.time.DateTime,​T>
    public class TimedTransitionProperty<V,​T extends TimedTransitionProperty.TimedTransition<V>>
extends com.google.common.collect.ForwardingMap<org.joda.time.DateTime,​T>
    An entity property whose value transitions over time. Each value it takes on becomes active at a corresponding instant, and remains active until the next transition occurs. At least one "start of time" value (corresponding to START_OF_TIME, i.e. the Unix epoch) must be provided so that the property will have a value for all possible times.

    This concept is naturally represented by a sorted map of DateTime to V, but the App Engine Datastore cannot natively represent a map keyed on non-strings. Instead, we store an ordered list of transitions and use Objectify's @Mapify annotation to automatically recreate the sorted map on load from Datastore, which is used as a backing map for this property; the property itself also implements Map by way of extending ForwardingMap, so that this property can stored directly as the @Mapify field in the entity.

    The type parameter T specifies a user-defined subclass of TimedTransition<V> to use for storing the list of transitions. The user is given this choice of subclass so that the field of the value type stored in the transition can be given a customized name.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  TimedTransitionProperty.TimedTransition<V>
      A transition to a value of type V at a certain time.
      static class  TimedTransitionProperty.TimeMapper
      Mapper used with @Mapify extracting time from TimedTransition to use as key.

      • Nested classes/interfaces inherited from class com.google.common.collect.ForwardingMap

        com.google.common.collect.ForwardingMap.StandardEntrySet, com.google.common.collect.ForwardingMap.StandardKeySet, com.google.common.collect.ForwardingMap.StandardValues

      • Nested classes/interfaces inherited from interface java.util.Map

        java.util.Map.Entry<K extends java.lang.Object,​V extends java.lang.Object>

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void checkValidity()
      Checks whether this TimedTransitionProperty is in a valid state, i.e.
      TimedTransitionProperty<V,​T> copyUntilJustBefore​(org.joda.time.DateTime asOfDate)
      Returns a new immutable TimedTransitionProperty containing the same transitions as the current object, up to but not including the desired date.
      TimedTransitionProperty<V,​T> copyWithAddedTransition​(org.joda.time.DateTime transitionTime, V transitionValue, java.lang.Class<T> transitionClass, com.google.common.collect.ImmutableMultimap<V,​V> allowedTransitions, java.lang.String allowedTransitionMapName)
      Returns a new immutable TimedTransitionProperty containing the same transitions as the current object, plus the additional specified transition.
      protected java.util.NavigableMap<org.joda.time.DateTime,​T> delegate()  
      static <V,​T extends TimedTransitionProperty.TimedTransition<V>>
      TimedTransitionProperty<V,​T>      		 forMapify​(com.google.common.collect.ImmutableSortedMap<org.joda.time.DateTime,​V> valueMap, java.lang.Class<T> timedTransitionSubclass)
      Returns a new mutable TimedTransitionProperty representing the given map of DateTime to value, with transitions constructed using the given TimedTransition subclass.
      static <V,​T extends TimedTransitionProperty.TimedTransition<V>>
      TimedTransitionProperty<V,​T>      		 forMapify​(V valueAtStartOfTime, java.lang.Class<T> timedTransitionSubclass)
      Returns a new mutable TimedTransitionProperty representing the given value being set at start of time, constructed using the given TimedTransition subclass.
      static <V,​T extends TimedTransitionProperty.TimedTransition<V>>
      TimedTransitionProperty<V,​T>      		 fromValueMap​(com.google.common.collect.ImmutableSortedMap<org.joda.time.DateTime,​V> valueMap, java.lang.Class<T> timedTransitionSubclass)
      Returns a new immutable TimedTransitionProperty representing the given map of DateTime to value, with transitions constructed using the given TimedTransition subclass.
      org.joda.time.DateTime getNextTransitionAfter​(org.joda.time.DateTime time)
      Returns the time of the next transition.
      V getValueAtTime​(org.joda.time.DateTime time)
      Returns the value of the property that is active at the specified time.
      static <V,​T extends TimedTransitionProperty.TimedTransition<V>>
      TimedTransitionProperty<V,​T>      		 make​(com.google.common.collect.ImmutableSortedMap<org.joda.time.DateTime,​V> newTransitions, java.lang.Class<T> transitionClass, com.google.common.collect.ImmutableMultimap<V,​V> allowedTransitions, java.lang.String allowedTransitionMapName, V initialValue, java.lang.String badInitialValueErrorMessage)
      Validates a new set of transitions and returns the resulting TimedTransitionProperty map.
      com.google.common.collect.ImmutableSortedMap<org.joda.time.DateTime,​V> toValueMap()
      Returns the map of DateTime to value that is the "natural" representation of this property.
      static <V,​T extends TimedTransitionProperty.TimedTransition<V>>
      void      		 validateTimedTransitionMap​(java.util.NavigableMap<org.joda.time.DateTime,​V> transitionMap, com.google.common.collect.ImmutableMultimap<V,​V> allowedTransitions, java.lang.String mapName)
      Validates that a transition map is not null or empty, starts at START_OF_TIME, and has transitions which move from one value to another in allowed ways.

      • Methods inherited from class com.google.common.collect.ForwardingMap

        clear, containsKey, containsValue, entrySet, equals, get, hashCode, isEmpty, keySet, put, putAll, remove, size, standardClear, standardContainsKey, standardContainsValue, standardEquals, standardHashCode, standardIsEmpty, standardPutAll, standardRemove, standardToString, values

      • Methods inherited from class com.google.common.collect.ForwardingObject

        toString

      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait

      • Methods inherited from interface java.util.Map

        compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, remove, replace, replace, replaceAll

    • Method Detail

      • fromValueMap

        public static <V,​T extends TimedTransitionProperty.TimedTransition<V>> TimedTransitionProperty<V,​T> fromValueMap​(com.google.common.collect.ImmutableSortedMap<org.joda.time.DateTime,​V> valueMap,
                                                                                                                             java.lang.Class<T> timedTransitionSubclass)
        Returns a new immutable TimedTransitionProperty representing the given map of DateTime to value, with transitions constructed using the given TimedTransition subclass.

        This method should be the normal method for constructing a TimedTransitionProperty.

      • copyUntilJustBefore

        public TimedTransitionProperty<V,​T> copyUntilJustBefore​(org.joda.time.DateTime asOfDate)
        Returns a new immutable TimedTransitionProperty containing the same transitions as the current object, up to but not including the desired date. All transitions on or after that date will be deleted.
        Parameters:
        asOfDate - the date before which transitions should be retained

      • copyWithAddedTransition

        public TimedTransitionProperty<V,​T> copyWithAddedTransition​(org.joda.time.DateTime transitionTime,
                                                                  V transitionValue,
                                                                  java.lang.Class<T> transitionClass,
                                                                  com.google.common.collect.ImmutableMultimap<V,​V> allowedTransitions,
                                                                  java.lang.String allowedTransitionMapName)
        Returns a new immutable TimedTransitionProperty containing the same transitions as the current object, plus the additional specified transition.
        Parameters:
        transitionTime - the time of the new transition
        transitionValue - the value of the new transition
        transitionClass - the class of transitions in this map
        allowedTransitions - map of all possible state-to-state transitions
        allowedTransitionMapName - transition map description string for error messages

      • make

        public static <V,​T extends TimedTransitionProperty.TimedTransition<V>> TimedTransitionProperty<V,​T> make​(com.google.common.collect.ImmutableSortedMap<org.joda.time.DateTime,​V> newTransitions,
                                                                                                                     java.lang.Class<T> transitionClass,
                                                                                                                     com.google.common.collect.ImmutableMultimap<V,​V> allowedTransitions,
                                                                                                                     java.lang.String allowedTransitionMapName,
                                                                                                                     V initialValue,
                                                                                                                     java.lang.String badInitialValueErrorMessage)
        Validates a new set of transitions and returns the resulting TimedTransitionProperty map.
        Parameters:
        newTransitions - map from date time to transition value
        transitionClass - the class of transitions in this map
        allowedTransitions - optional map of all possible state-to-state transitions
        allowedTransitionMapName - optional transition map description string for error messages
        initialValue - optional initial value; if present, the first transition must have this value
        badInitialValueErrorMessage - option error message string if the initial value is wrong

      • validateTimedTransitionMap

        public static <V,​T extends TimedTransitionProperty.TimedTransition<V>> void validateTimedTransitionMap​(@Nullable
                                                                                                             java.util.NavigableMap<org.joda.time.DateTime,​V> transitionMap,
                                                                                                             com.google.common.collect.ImmutableMultimap<V,​V> allowedTransitions,
                                                                                                             java.lang.String mapName)
        Validates that a transition map is not null or empty, starts at START_OF_TIME, and has transitions which move from one value to another in allowed ways.

      • forMapify

        public static <V,​T extends TimedTransitionProperty.TimedTransition<V>> TimedTransitionProperty<V,​T> forMapify​(com.google.common.collect.ImmutableSortedMap<org.joda.time.DateTime,​V> valueMap,
                                                                                                                          java.lang.Class<T> timedTransitionSubclass)
        Returns a new mutable TimedTransitionProperty representing the given map of DateTime to value, with transitions constructed using the given TimedTransition subclass.

        This method should only be used for initializing fields that are declared with the @Mapify annotation. The map for those fields must be mutable so that Objectify can load values from Datastore into the map, but clients should still never mutate the field's map directly.

      • forMapify

        public static <V,​T extends TimedTransitionProperty.TimedTransition<V>> TimedTransitionProperty<V,​T> forMapify​(V valueAtStartOfTime,
                                                                                                                          java.lang.Class<T> timedTransitionSubclass)
        Returns a new mutable TimedTransitionProperty representing the given value being set at start of time, constructed using the given TimedTransition subclass.

        This method should only be used for initializing fields that are declared with the @Mapify annotation. The map for those fields must be mutable so that Objectify can load values from Datastore into the map, but clients should still never mutate the field's map directly.

      • checkValidity

        public void checkValidity()
        Checks whether this TimedTransitionProperty is in a valid state, i.e. whether it has a transition entry for START_OF_TIME, and throws IllegalStateException if not.

      • delegate

        protected java.util.NavigableMap<org.joda.time.DateTime,​T> delegate()
        Specified by:
        delegate in class com.google.common.collect.ForwardingMap<org.joda.time.DateTime,​T extends TimedTransitionProperty.TimedTransition<V>>

      • toValueMap

        public com.google.common.collect.ImmutableSortedMap<org.joda.time.DateTime,​V> toValueMap()
        Returns the map of DateTime to value that is the "natural" representation of this property.

      • getValueAtTime

        public V getValueAtTime​(org.joda.time.DateTime time)
        Returns the value of the property that is active at the specified time. The active value for a time before START_OF_TIME is extrapolated to be the value that is active at START_OF_TIME.

      • getNextTransitionAfter

        @Nullable
public org.joda.time.DateTime getNextTransitionAfter​(org.joda.time.DateTime time)
        Returns the time of the next transition. Returns null if there is no subsequent transition.