Class Memorizer

java.lang.Object
org.copalis.jam.memo.Memorizer
public class Memorizer extends Object
A method memoizer that can also determine when methods need to be re-executed as a result of changes to external resources.

The Memorizer creates instances of interfaces and instruments them with a method handler which intercepts calls to default methods.

  • If a cache entry exists for a method call, the result of that earlier call is returned.
  • If there is no cache entry for a method call the method is executed, and its result is stored in the memoizer's cache if it is eligible to be cached

The state of the cache can also be saved and loaded, excluding method calls non-Serializable parameters or return value.

Cache eligibility

  • Methods that do not have return type void are cacheable, and should only perform idempotent actions
  • Methods with void return type are not cacheable, and may be used for logic with side-effects

Staleness checking

The method handler performs staleness checking on cached method calls which return or depend on references to mutable resources such as files. To enable staleness checking, objects which reference resources must implement Mutable. A resource reference object is modified if Mutable.modified() is true.

A cached method call is stale if any of these conditions are met:

  • Its returned value is modified
  • It made a method call which is stale
  • One or more of its parameters are modified
  • It has one or more non-Mutable parameters AND a previous call within the scope of the method calling it returned a modified value
If a cache entry is stale, the method invocation will be executed as though it was not cached.

  • Constructor Details

    • Memorizer

      public Memorizer(Observer observer)
      Creates an instance
      Parameters:
      observer - an invocation observer, must not be null

    • Memorizer

      public Memorizer()
      Creates an instance with no related observer or cache file

  • Method Details

    • load

      public void load(InputStream in) throws IOException, ClassNotFoundException
      Loads the cache
      Parameters:
      in - an input stream the serialized cache contents will be read from
      Throws:
      IOException - if an IO exception occurs
      ClassNotFoundException - if a serialized class cannot be found

    • save

      public void save(OutputStream out) throws IOException
      Writes the contents of the method call cache to an output stream, excluding method calls which are not serializable.
      Parameters:
      out - an output stream the serialized cache contents will be written to
      Throws:
      IOException - if an IO exception occurs

    • entries

      public Stream<Result> entries()
      Gets the cache contents
      Returns:
      a stream of cached method results

    • lookup

      public Result lookup(Invocation invocation)
      Looks up a cache entry
      Parameters:
      invocation - the method call
      Returns:
      a Result or null

    • forget

      public void forget()
      Erases all method call results from the cache

    • instantiate

      public <T> T instantiate(Class<T> t)
      Creates a memoized instance of an interface. The methods declared by the interface must all have a default implementation.
      Type Parameters:
      T - the interface type to instantiate
      Parameters:
      t - the Java class of the interface
      Returns:
      an instance of the interface