Package one.microstream.reference

Interface Lazy<T>

Type Parameters:
T - the type of the lazily referenced element
All Superinterfaces:
Referencing<T>
All Known Subinterfaces:
ControlledLazyReference<T>
All Known Implementing Classes:
ControlledLazyReference.Default, Lazy.Default
public interface Lazy<T>
extends Referencing<T>
A reference providing generic lazy-loading functionality.

Note that the shortened name has been chosen intentionally to optimize readability in class design.

Also note that a type like this is strongly required in order to implement lazy loading behavior in an application in an architecturally clean and proper way. I.e. the application's data model design has to define that a certain reference is meant to be capable of lazy-loading. If such a definition is not done, a loading logic is strictly required to always load the encountered reference, as it is defined by the "normal" way of how references work. Any "tricks" of whatever framework to "sneak in" lazy loading behavior where it hasn't actually been defined are nothing more than dirty hacks and mess up if not destroy the program's consistency of state (e.g. antipatterns like secretly replacing a well-defined collection instance with a framework-proprietary proxy instance of a "similar" collection implementation). In proper architectured software, if a reference does not define lazy loading capacity, it is not wanted to have that capacity on the business logical level by design in the first place. Any attempts of saying "but I want it anyway in a sneaky 'transparent' way" indicate ambivalent conflicting design errors and thus in the end poor design.

  • Nested Class Summary

    Nested Classes 
    Modifier and Type Interface Description
    static interface  Lazy.Check  
    static interface  Lazy.Checker  
    static interface  Lazy.ClearingEvaluator
    Simple functional evaluator which decides if lazy references should be cleared.
    static class  Lazy.Default<T>  

  • Method Summary

    Modifier and Type Method Description
    static Lazy.Checker Checker()  
    static Lazy.Checker Checker​(double memoryQuota)  
    static Lazy.Checker Checker​(long millisecondTimeout)  
    static Lazy.Checker Checker​(long millisecondTimeout, double memoryQuota)  
    static Lazy.Checker Checker​(long millisecondTimeout, double memoryQuota, Lazy.Check customCheck, LazyReferenceManager.CycleEvaluator cycleEvaluator)  
    static Lazy.Checker Checker​(Lazy.Check customCheck)  
    static Lazy.Checker CheckerMemory​(double memoryQuota)  
    static Lazy.Checker CheckerTimeout​(long millisecondTimeout)  
    T clear()
    Clears the reference, leaving the option to re-load it again intact, and returns the subject that was referenced prior to clearing.
    boolean clear​(Lazy.ClearingEvaluator clearingEvaluator)
    Clears the reference if the clearingEvaluator decides to, leaving the option to re-load it again intact, and returns the subject that was referenced prior to clearing.
    static void clear​(Lazy<?> reference)
    Static helper method to call the clear() method of the given reference containing a null-check.
    T get()
    Returns the original subject referenced by this reference instance.
    static <T> T get​(Lazy<T> reference)
    Static helper method to call the get() method of the given reference containing a null-check.
    boolean isLoaded()
    Returns if this lazy reference is loaded.
    static boolean isLoaded​(Lazy<?> reference)
    Static helper method to call the isLoaded() method of the given reference containing a null-check.
    boolean isStored()
    Returns if this lazy reference was persisted before.
    static boolean isStored​(Lazy<?> reference)
    Static helper method to call the isStored() method of the given reference containing a null-check.
    long lastTouched()
    Returns the timestamp (corresponding to System.currentTimeMillis()) when this instance has last been "touched", meaning having its reference modified or queried.
    static <T> Lazy<T> New​(long objectId)  
    static <T> Lazy<T> New​(long objectId, ObjectSwizzling loader)  
    static <T> Lazy<T> New​(T subject, long objectId, ObjectSwizzling loader)  
    T peek()
    Returns the local reference without loading the referenced object if it is not present.
    static <T> T peek​(Lazy<T> reference)
    Static helper method to call the peek() method of the given reference containing a null-check.
    static <T> Lazy<T> Reference​(T subject)
    Pseudo-constructor method to create an register a new lazy reference wrapping the given subject.
    static <T,​ L extends Lazy<T>>
    L    		 register​(L lazyReference)
    Registers the given lazy reference with the current LazyReferenceManager.
    static <T> Lazy<T> UnregisteredReference​(T subject)
    Create a new Lazy reference that is not registered to the LazyReferenceManager

  • Method Details

    • get

      T get()
      Returns the original subject referenced by this reference instance. If the subject has (lazily) not been loaded, an attempt to do so now is made. Any exception occurring during the loading attempt will be passed along without corrupting this reference instance's internal state.
      Specified by:
      get in interface Referencing<T>
      Returns:
      the originally referenced subject, either already-known or lazy-loaded.

    • peek

      T peek()
      Returns the local reference without loading the referenced object if it is not present. The value returned by lastTouched() will not be changed by calling this method.
      Returns:
      the currently present reference.

    • clear

      T clear()
      Clears the reference, leaving the option to re-load it again intact, and returns the subject that was referenced prior to clearing.
      Returns:
      the subject referenced prior to clearing the reference.
      See Also:
      clear(ClearingEvaluator)

    • isStored

      boolean isStored()
      Returns if this lazy reference was persisted before.
      Returns:
      true if this lazy reference was persisted, false otherwise

    • isLoaded

      boolean isLoaded()
      Returns if this lazy reference is loaded. There are three cases in which this applies:
      • It is not yet persisted, meaning it is implicitly always "loaded".
      • A null-reference is always "loaded".
      • Otherwise, the subject must be present, truly a state of having been "loaded".
      Returns:
      true if this lazy reference is loaded, false otherwise

    • lastTouched

      long lastTouched()
      Returns the timestamp (corresponding to System.currentTimeMillis()) when this instance has last been "touched", meaning having its reference modified or queried.
      Returns:
      the time this instance has last been significantly used.

    • clear

      boolean clear​(Lazy.ClearingEvaluator clearingEvaluator)
      Clears the reference if the clearingEvaluator decides to, leaving the option to re-load it again intact, and returns the subject that was referenced prior to clearing.
      Parameters:
      clearingEvaluator - evaluator which decides if the reference should be cleared
      Returns:
      if this lazy references was cleared
      See Also:
      clear()

    • get

      static <T> T get​(Lazy<T> reference)
      Static helper method to call the get() method of the given reference containing a null-check.

      If reference is null, null is returned, otherwise the value of reference.get().

      Type Parameters:
      T - the type of the lazily referenced element
      Parameters:
      reference - the lazy reference to call the get method on
      Returns:
      null or the original return value
      See Also:
      get()

    • peek

      static <T> T peek​(Lazy<T> reference)
      Static helper method to call the peek() method of the given reference containing a null-check.

      If reference is null, null is returned, otherwise the value of reference.peek().

      Type Parameters:
      T - the type of the lazily referenced element
      Parameters:
      reference - the lazy reference to call the peek method on
      Returns:
      null or the original return value
      See Also:
      peek()

    • clear

      static void clear​(Lazy<?> reference)
      Static helper method to call the clear() method of the given reference containing a null-check.

      If reference is null, it's a no-op, otherwise reference.clear() is called.

      Parameters:
      reference - the lazy reference to call the clear method on
      See Also:
      clear()

    • isStored

      static boolean isStored​(Lazy<?> reference)
      Static helper method to call the isStored() method of the given reference containing a null-check.

      If reference is null, false is returned, otherwise the value of reference.isStored().

      Parameters:
      reference - the lazy reference to call the isStored method on
      Returns:
      false or the original return value
      See Also:
      isStored()

    • isLoaded

      static boolean isLoaded​(Lazy<?> reference)
      Static helper method to call the isLoaded() method of the given reference containing a null-check.

      If reference is null, false is returned, otherwise the value of reference.isLoaded().

      Parameters:
      reference - the lazy reference to call the isLoaded method on
      Returns:
      false or the original return value
      See Also:
      get()

    • Reference

      static <T> Lazy<T> Reference​(T subject)
      Pseudo-constructor method to create an register a new lazy reference wrapping the given subject.
      Type Parameters:
      T - the type of the lazily referenced element
      Parameters:
      subject - the subject to reference
      Returns:
      a new Lazy instance
      See Also:
      register(Lazy)

    • UnregisteredReference

      static <T> Lazy<T> UnregisteredReference​(T subject)
      Create a new Lazy reference that is not registered to the LazyReferenceManager
      Type Parameters:
      T - type parameter
      Parameters:
      subject - lazy referenced object
      Returns:
      a new Lazy reference

    • New

      static <T> Lazy<T> New​(long objectId)

    • New

      static <T> Lazy<T> New​(long objectId, ObjectSwizzling loader)

    • New

      static <T> Lazy<T> New​(T subject, long objectId, ObjectSwizzling loader)

    • register

      static <T,​ L extends Lazy<T>> L register​(L lazyReference)
      Registers the given lazy reference with the current LazyReferenceManager.
      Type Parameters:
      T - the type of the lazily referenced element
      L - the lazy type
      Parameters:
      lazyReference - the reference to register
      Returns:
      the lazyReference

    • Checker

      static Lazy.Checker Checker()

    • Checker

      static Lazy.Checker Checker​(long millisecondTimeout)

    • Checker

      static Lazy.Checker Checker​(double memoryQuota)

    • Checker

      static Lazy.Checker Checker​(long millisecondTimeout, double memoryQuota)

    • Checker

      static Lazy.Checker Checker​(Lazy.Check customCheck)

    • Checker

      static Lazy.Checker Checker​(long millisecondTimeout, double memoryQuota, Lazy.Check customCheck, LazyReferenceManager.CycleEvaluator cycleEvaluator)

    • CheckerTimeout

      static Lazy.Checker CheckerTimeout​(long millisecondTimeout)

    • CheckerMemory

      static Lazy.Checker CheckerMemory​(double memoryQuota)