javolution.context

Class ObjectFactory<T>

java.lang.Object

javolution.context.ObjectFactory<T>

public abstract class ObjectFactory<T>
extends java.lang.Object

This class represents an object factory; it allows for object recycling, pre-allocation and stack allocations.

Object factories are recommended over class constructors (ref. "new" keyword) to allows for custom allocation policy (see AllocatorContext). For example:

     static ObjectFactory<int[][]> BOARD_FACTORY = new ObjectFactory<int[][]>() {
         protected int[][] create() {
             return new int[8][8];
         }
     };
     ...
     int[][] board = BOARD_FACTORY.object();
         // The board object might have been preallocated at start-up,
         // it might also be on the thread "stack/pool" for threads
         // executing in a StackContext.
     ...
     BOARD_FACTORY.recycle(board); // Immediate recycling of the board object (optional).
     

For arrays of variable length ArrayFactory is recommended.

For convenience, this class provides a static getInstance(java.lang.Class<T>) method to retrieve a factory implementation for any given class. For example:

        ObjectFactory<ArrayList> listFactory = ObjectFactory.getInstance(ArrayList.class);
        ArrayList list = listFactory.object();
        ... // Do something.
        listFactory.recycle(list); // Optional.
    

Version:

5.2, August 14, 2007

Author:

Jean-Marie Dautelle

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ObjectFactory() Default constructor.

Method Summary

Modifier and Type	Method and Description
protected void	cleanup(T obj) Cleans-up this factory's objects for future reuse.
protected abstract T	create() Constructs a new object for this factory (using the new keyword).
Allocator<T>	currentAllocator() Returns the factory allocator for the current thread (equivalent to AllocatorContext.current().getAllocator(this)).
protected boolean	doCleanup() Indicates if this factory requires cleanup.
static <T> ObjectFactory<T>	getInstance(java.lang.Class<T> forClass) Returns a factory implementation producing instances of the specified class.
T	object() Returns a factory object possibly recycled or preallocated.
void	recycle(T obj) Recycles the specified object.
static <T> void	setInstance(ObjectFactory<T> factory, java.lang.Class<T> forClass) Sets explicitely the factory to be used for the specified class (see getInstance(java.lang.Class<T>)).

Methods inherited from class java.lang.Object

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

Constructor Detail

ObjectFactory

protected ObjectFactory()

Default constructor.

Method Detail

getInstance

public static <T> ObjectFactory<T> getInstance(java.lang.Class<T> forClass)

Returns a factory implementation producing instances of the specified class. By default this method returns a factory creating new objects using the class public no-arg constructor (through reflection). If that constructor is not accessible, the factory instance can be set explicitly:

 class LogContext {
     public static final Class<LogContext> NULL = Null.class;
     ...
     private static class Null extends LogContext ... // Private.
     static {
          // Allows Null instances to be factory produced (even so the class is not accessible).
          ObjectFactory.setInstance(new ObjectFactory<Null> {
              protected Null create() { return new Null() }},
              Null.class);
     }
  }

Parameters:

forClass - the class for which an object factory is returned.

Returns:

an object factory producing instances of the specified class.

setInstance

public static <T> void setInstance(ObjectFactory<T> factory,
                                   java.lang.Class<T> forClass)

Sets explicitely the factory to be used for the specified class (see getInstance(java.lang.Class<T>)).

Parameters:

factory - the factory to use.

forClass - the associated class.

See Also:

getInstance(Class)

object

public final T object()

Returns a factory object possibly recycled or preallocated. This method is equivalent to currentAllocator().next().

Returns:

a recycled, pre-allocated or new factory object.

recycle

public final void recycle(T obj)

Recycles the specified object. This method is equivalent to getAllocator().recycle(obj).

Parameters:

obj - the object to be recycled.

currentAllocator

public final Allocator<T> currentAllocator()

Returns the factory allocator for the current thread (equivalent to AllocatorContext.current().getAllocator(this)).

Returns:

the current object queue for this factory.

create

protected abstract T create()

Constructs a new object for this factory (using the new keyword).

Returns:

a new factory object.

cleanup

protected void cleanup(T obj)

Cleans-up this factory's objects for future reuse. The default implementation resets reusable instance. For non Reusable, this method can be overriden 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). For example:

     static ObjectFactory<ArrayList> ARRAY_LIST_FACTORY = new ObjectFactory<ArrayList>() {
         protected ArrayList create() {
             return new ArrayList();
         }
         protected void cleanup(ArrayList obj) {
             obj.clear(); // Clears external references.
         }
     };

Parameters:

obj - the factory object being recycled.

doCleanup

protected final boolean doCleanup()

Indicates if this factory requires cleanup.

Returns:

true if cleanup(T) is overriden and cleanup(T) has been called at least once; false otherwise.