01: /*
02: * Javolution - Java(TM) Solution for Real-Time and Embedded Systems
03: * Copyright (C) 2006 - Javolution (http://javolution.org/)
04: * All rights reserved.
05: *
06: * Permission to use, copy, modify, and distribute this software is
07: * freely granted, provided that this notice is preserved.
08: */
09: package javolution.lang;
10:
11: /**
12: * <p> This interfaces identifies mutable objects capable of being used again
13: * or repeatedly; once {@link #reset reset}, reusable objects behave as if
14: * they were brand-new.</p>
15: *
16: * <p> Reusable instances should not allocate new internal objects after
17: * creation except for the purpose of increasing their internal capacities.
18: * In such case the new allocations have to be performed in the same memory
19: * areas as the reusable objects themselves (necessary to avoid memory leaks
20: * or memory clashes when running on
21: * <a href="https://rtsj.dev.java.net/">RTSJ</a> VMs). For example:[code]
22: * import javax.realtime.MemoryArea;
23: * public class Targets implements Reusable {
24: * private Target[] _targets = new Target[32];
25: * private int _count;
26: * public void add(Target target) {
27: * if (_count >= _targets.length) capacityOverflow();
28: * _targets[_count++] = target;
29: * }
30: * private void capacityOverflow() {
31: * MemoryArea.getMemoryArea(this).executeInArea(new Runnable() {
32: * public void run() {
33: * Target[] tmp = new Target[_targets.length * 2];
34: * System.arraycopy(_targets, 0, tmp, 0, _count);
35: * _targets = tmp;
36: * }
37: * });
38: * }
39: * ...
40: * }[/code]</p>
41: *
42: * <p> Instances of this class can safely reside in permanent memory
43: * (e.g. <code>static</code> members) or be an integral part of a
44: * higher level component. For example:[code]
45: * public class XMLFormat {
46: * // RTSJ Unsafe! Memory leaks (when entries removed) or IllegalAssignmentError (when new entries while in ScopedArea).
47: * static HashMap<Class, XMLFormat> ClassToFormat = HashMap<Class, XMLFormat>();
48: *
49: * // RTSJ safe! FastMap is Reusable. Removed entries are internally recycled, new entries are in ImmortalMemory.
50: * static FastMap<Class, XMLFormat> ClassToFormat = FastMap<Class, XMLFormat>();
51: * }[/code]</p>
52: *
53: * <p> Reusable objects can also be allocated on the stack providing that
54: * their {@link javolution.context.ObjectFactory factory} cleanup
55: * method calls the {@link #reset reset} method. For example:[code]
56: * public class Foo implements Reusable {
57: * private static final ObjectFactory<Foo> FACTORY = new ObjectFactory<Foo>() {
58: * protected Foo create() {
59: * return new Foo();
60: * }
61: * protected void cleanup(Foo obj) {
62: * obj.reset();
63: * }
64: * };
65: * public static Foo newInstance() {
66: * return FACTORY.object(); // On the "stack" when executing in a StackContext.
67: * }
68: * ...
69: * }[/code]</p>
70: *
71: * @author <a href="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
72: * @version 3.7, January 1, 2006
73: */
74: public interface Reusable {
75:
76: /**
77: * Resets the internal state of this object to its default values.
78: */
79: void reset();
80:
81: }
|