com.dautelle.realtime
Class ObjectFactory

java.lang.Object
  com.dautelle.realtime.ObjectFactory

Direct Known Subclasses:

RealtimeNumber.Factory, RealtimeObject.Factory

public abstract class ObjectFactory

extends java.lang.Object

This class represents an object factory. How and when a factory allocates its objects depends upon its real-time context. The default context (HeapContext) allocates objects on-demand (from the heap) and recycling is done through garbage collection.

Object factories should be used preferably to class constructors (ref. "new" keyword) to allow for "stack" allocation when the current thread executes in a PoolContext:

     // Unlike toString() the following avoids heap allocation.
     public CharSequence toChars() {  
         StringBuffer sb 
              = (StringBuffer) STRING_BUFFER_FACTORY.object();
         ... // Formats this object into sb 
         ... // (e.g. using TypeFormat)
         return sb; // On the "stack" when executing in a PoolContext.
     }
     static final ObjectFactory STRING_BUFFER_FACTORY = new ObjectFactory() {
         public Object create() {
             return new StringBuffer(26);
         }
     };

It is also possible to cleanup factories' objects for future reuse (e.g. to release system resources or to clear external references immediately after usage):

     static final ObjectFactory FACTORY = new ObjectFactory() {
         public Object create() {
              return new ArrayList(256);
         }
         public void cleanup(Object obj) {
             // Ensures that list objects can be garbage collected.
             ((ArrayList)obj).clear(); 
         }  
     };

Finally, this class serves to the implementation of Realtime base classes such as RealtimeObject or RealtimeNumber (see implementation code for details).

The number of instances of this class is voluntarely limited (see JADE's Configuration for details). Instances of this class should be either static or member of persistent objects.

Version:

6.0, May 16, 2004

Author:

Jean-Marie Dautelle

Field Summary

static int

MAX Holds the maximum number of ObjectFactory (system property "jade.factories", default 1024).

Constructor Summary

protected

ObjectFactory() Default constructor.

Method Summary

void	cleanup(java.lang.Object obj) Cleans-up this factory's objects for future reuse.
abstract java.lang.Object	create() Allocates a new object from this factory on the heap (using the new keyword).
ObjectPool	currentPool() Returns the pool for the current thread.
ObjectPool	heapPool() Returns a pool from this factory which represents the heap.
protected ObjectPool	newPool() Creates a new pool for this object factory.
java.lang.Object	object() Returns a new or recycled object from this factory.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MAX

public static final int MAX

Holds the maximum number of ObjectFactory (system property "jade.factories", default 1024).

Constructor Detail

ObjectFactory

protected ObjectFactory()

Default constructor.

Throws:

java.lang.UnsupportedOperationException - if already MAX factories exist.

Method Detail

create

public abstract java.lang.Object create()

Allocates a new object from this factory on the heap (using the new keyword).

Returns:

a new object allocated on the heap.

object

public java.lang.Object object()

Returns a new or recycled object from this factory. Sub-classes may override this method to provide more efficient implementations.

Returns:

this.currentPool().next()

cleanup

public void cleanup(java.lang.Object obj)

Cleans-up this factory's objects for future reuse. When overriden, this method is called on objects being recycled to dispose of system resources or to clear references to external objects potentially on the heap (it allows these external objects to be garbage collected immediately and therefore reduces the memory footprint).

Note: Whether or not this method should be overriden depends mostly on the association types that the factory's objects have with other objects. For composition associations (containment per value), there is usually no need to cleanup. For other types of relationship cleaning up is recommended.

Parameters:

obj - the object product of this factory being recycled.

Throws:

java.lang.UnsupportedOperationException - if this factory does not support object clean-up (default).

currentPool

public final ObjectPool currentPool()

Returns the pool for the current thread. If the current thread is not executing in a PoolContext, then heapPool() is returned.

Returns:

the pool for the current thread or heapPool() when the current thread executes in a HeapContext.

heapPool

public final ObjectPool heapPool()

Returns a pool from this factory which represents the heap. Allocating from this pool always calls create().

Returns:

a pool for which recycling is performed through garbage collection exclusively.

newPool

protected ObjectPool newPool()

Creates a new pool for this object factory. Sub-classes may override this method in order to use custom pools.

Returns:

a default implementation for ObjectPool.