git.gag.com Git - debian/openrocket/blob - core/src/net/sf/openrocket/util/Monitorable.java

   1 package net.sf.openrocket.util;
   2
   3 /**
   4  * Interface describing objects whose state changes can be monitored based on
   5  * a modification ID number.  If a specific object has the same modification ID
   6  * at two different points in time, the object state is guaranteed to be the same.
   7  * This does not necessarily hold between two different instances of an object type.
   8  *
   9  * @author Sampo Niskanen <sampo.niskanen@iki.fi>
  10  */
  11 public interface Monitorable {
  12
  13         /**
  14          * Return a modification ID unique to the current state of this object and contained objects.
  15          * The general contract is that if a specific object has the same modification ID at two moments
  16          * in time, then the state of the object has not changed in between.  Additionally the
  17          * modification ID value must be monotonically increasing.  This value can be used as a monitor
  18          * to whether an object has been changed between two points of time.
  19          * <p>
  20          * Implementations may optionally fulfill the stronger requirement that any two objects of the same
  21          * type that have the same modification ID will be equal, though for complex objects guaranteeing
  22          * this may be impractical.
  23          * <p>
  24          * Objects that contain only primitive types or immutable objects can implement this method by
  25          * increasing a modification counter or retrieving a new unique ID every time a value is set.
  26          * <p>
  27          * Objects that contain other objects with a mutable state may for example return the sum of the
  28          * object's own modification ID, a modification ID counter (initially zero) and the modification IDs
  29          * of the contained objects.  When a mutable object is set, the modification counter is increased by
  30          * the modification ID of the current object in order to preserve monotonicity.
  31          * <p>
  32          * If an object does not have any fields, this method can simply return zero.
  33          * <p>
  34          * Cloned objects may or may not have the same modification ID as the original object.
  35          *
  36          * @return              a modification ID value for this object.
  37          * @see                 UniqueID#next()
  38          */
  39         public int getModID();
  40
  41 }