javolution37.javolution.lang

Class PersistentReference<T>

java.lang.Object

javolution37.javolution.lang.PersistentReference<T>

All Implemented Interfaces:

java.io.Serializable, Reference<T>

public class PersistentReference<T>
extends java.lang.Object
implements Reference<T>, java.io.Serializable

This class represents a reference over an object which can be kept persistent accross multiple program executions. Instances of this class are typically used to hold global data time consuming to regenerate. For example:

     public class FastMap<K,V> implements Map<K, V> {
         // Provides constructor for persistent maps.
         public FastMap(String id) {
             PersistentReference<FastMap<K,V>> ref = new PersistentReference<FastMap<K,V>>(id);
             FastMap<K,V> persistentMap = ref.get();
             if (persistentMap != null) this.putAll(persistentMap);
             ref.set(this); // Sets this map as the persistent map.
         }
     }
     ...
     // Persistent lookup table for units multiplications.
     static FastMap<Unit, FastMap<Unit, Unit>> UNITS_MULT_LOOKUP 
          =  new FastMap<Unit, FastMap<Unit, Unit>>("UNITS_MULT_LOOKUP").setShared(true);
    

Persistent references may also be used to hold optimum configuration values set from previous executions. For example:

     public Targets {  
          private static PersistentReference<Integer> CAPACITY 
               = new PersistentReference<Integer>(Targets#CAPACITY, 256);
          private Target[] _targets = new Target[CAPACITY.get()];
          private int _count;
          public void add(Target target) {
              if (_count == _targets.length) { // Ooops, resizes.
                  Target[] tmp = new Target[_count * 2];
                  System.arraycopy(_targets, 0, tmp, 0, _count);
                  _targets = tmp;
                  CAPACITY.setMinimum(_targets.length); // Persists. 
              }
              _targets[_count++] target;
         }
     }

How persistent references are loaded/saved is application specific. Although, the simplest way is to use Javolution xml serialization facility. For example:

      import javolution.xml.ObjectReader;
      import javolution.xml.ObjectWriter;
      public void main(String[]) {
           // Loads persistent reference values at start-up.
           Map values  = new ObjectReader<Map>().read(
                new FileInputStream("C:/persistent.xml"));
           PersistentReference.putAll(values)
           ... 
           new ObjectWriter<Map>().write(PersistentReference.values(),
                new FileOutputStream("C:/persistent.xml"));
      }

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
PersistentReference(java.lang.String id) Creates a persistent reference having the specified unique identifier.
PersistentReference(java.lang.String id, T defaultValue) Creates a persistent reference having the specified unique identifier and default value if not set.

Method Summary

Modifier and Type	Method and Description
T	get() Returns the value this reference referes to.
java.lang.String	id() Returns the unique identifier for this persistent reference.
static void	put(java.lang.String id, java.lang.Object value) Sets the value of the referenced object associated to the specified id.
static void	putAll(java.util.Map values) Overwrites the current values with the ones specified (equivalent to put(id, value) for each entry of the specified map).
void	set(T value) Sets the value this reference referes to.
void	setMaximum(T value) Sets this reference to the specified value only if (value.compareTo(this.get()) < 0).
void	setMinimum(T value) Sets this reference to the specified value only if (value.compareTo(this.get()) > 0).
java.lang.String	toString() Returns the string representation of the current value of this reference.
static java.util.Map	values() Returns a thread-safe, unmodifiable view over the persistent references values (id to value mapping).

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

PersistentReference

public PersistentReference(java.lang.String id)

Creates a persistent reference having the specified unique identifier.

Parameters:

id - the unique identifier.

Throws:

java.lang.IllegalArgumentException - if the identifier is not unique.

PersistentReference

public PersistentReference(java.lang.String id,
                           T defaultValue)

Creates a persistent reference having the specified unique identifier and default value if not set.

Parameters:

id - the unique identifier.

defaultValue - the default value if not set.

Throws:

java.lang.IllegalArgumentException - if the identifier is not unique.

Method Detail

id

public final java.lang.String id()

Returns the unique identifier for this persistent reference.

Returns:

this reference identifier.

get

public T get()

Description copied from interface: Reference

Returns the value this reference referes to.

Specified by:

get in interface Reference<T>

Returns:

the referent or null if not set.

set

public void set(T value)

Description copied from interface: Reference

Sets the value this reference referes to.

Specified by:

set in interface Reference<T>

Parameters:

value - the reference value.

setMinimum

public void setMinimum(T value)

Sets this reference to the specified value only if (value.compareTo(this.get()) > 0).

Parameters:

value - the minimum value for this reference.

Throws:

java.lang.IllegalArgumentException - if the specified value is not Comparable or an Integer instance (J2ME).

setMaximum

public void setMaximum(T value)

Sets this reference to the specified value only if (value.compareTo(this.get()) < 0).

Parameters:

value - the maximum value for this reference.

Throws:

java.lang.IllegalArgumentException - if the specified value is not Comparable or an Integer instance (J2ME).

values

public static java.util.Map values()

Returns a thread-safe, unmodifiable view over the persistent references values (id to value mapping).

Returns:

a view over the references mapping.

put

public static void put(java.lang.String id,
                       java.lang.Object value)

Sets the value of the referenced object associated to the specified id.

Parameters:

id - the object identifier.

value - the value to use instead of the current value.

putAll

public static void putAll(java.util.Map values)

Overwrites the current values with the ones specified (equivalent to put(id, value) for each entry of the specified map).

Parameters:

values - the new values (id to value mapping).

toString

public java.lang.String toString()

Returns the string representation of the current value of this reference.

Overrides:

toString in class java.lang.Object

Returns:

String.valueOf(this.get())