Reusable.java

/*
 * Javolution - Java(TM) Solution for Real-Time and Embedded Systems
 * Copyright (C) 2006 - Javolution (http://javolution.org/)
 * All rights reserved.
 * 
 * Permission to use, copy, modify, and distribute this software is
 * freely granted, provided that this notice is preserved.
 */
package javolution.lang;

/**
 * <p> This interfaces identifies mutable objects capable of being used again
 *     or repeatedly; once {@link #reset reset}, reusable objects behave as if
 *     they were brand-new.</p>
 *      
 * <p> Reusable instances should not allocate new internal objects after  
 *     creation except for the purpose of increasing their internal capacities. 
 *     In such case the new allocations have to be performed in the same memory
 *     areas as the reusable objects themselves (necessary to avoid memory leaks
 *     or memory clashes when running on 
 *     <a href="https://rtsj.dev.java.net/">RTSJ</a> VMs). For example:[code]
 *     import javax.realtime.MemoryArea;
 *     public class Targets implements Reusable {
 *         private Target[] _targets = new Target[32];
 *         private int _count;
 *         public void add(Target target) {
 *             if (_count >= _targets.length) capacityOverflow(); 
 *             _targets[_count++] = target;
 *         }
 *         private void capacityOverflow() {
 *              MemoryArea.getMemoryArea(this).executeInArea(new Runnable() {
 *                  public void run() {
 *                       Target[] tmp = new Target[_targets.length * 2];
 *                       System.arraycopy(_targets, 0, tmp, 0, _count);
 *                       _targets = tmp;
 *                  }
 *              });
 *         }
 *         ...
 *     }[/code]</p>
 *     
 * <p> Instances of this class can safely reside in permanent memory 
 *     (e.g. <code>static</code> members) or be an integral part of a
 *     higher level component. For example:[code]
 *     public class XMLFormat {
 *          // RTSJ Unsafe! Memory leaks (when entries removed) or IllegalAssignmentError (when new entries while in ScopedArea).   
 *          static HashMap<Class, XMLFormat> ClassToFormat = HashMap<Class, XMLFormat>();
 *             
 *          // RTSJ safe! FastMap is Reusable. Removed entries are internally recycled, new entries are in ImmortalMemory.
 *          static FastMap<Class, XMLFormat> ClassToFormat = FastMap<Class, XMLFormat>();
 *     }[/code]</p>
 *     
 * <p> Reusable objects can also be allocated from {@link javolution.context.ObjectFactory}
 *     in which case the {@link javolution.context.ObjectFactory#cleanup(java.lang.Object) cleanup}
 *     method is automatically called when the object is recycled. For example:[code]
 *     public class Foo implements Reusable {
 *         private static final ObjectFactory<Foo> FACTORY = new ObjectFactory<Foo>() {
 *             protected Foo create() {
 *                 return new Foo();
 *             }
 *             // No need to override cleanup, it is automatically called.
 *         };
 *         public static Foo newInstance() {
 *             return FACTORY.object(); // On the "stack" when executing in a StackContext.
 *         } 
 *         ...
 *     }[/code]</p>
 *        
 * @author  <a href="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
 * @version 3.7, January 1, 2006
 */
public interface Reusable {

    /**
     * Resets the internal state of this object to its default values.
     */
    void reset();

}