KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javolution > lang > Reusable


1 /*
2  * Javolution - Java(TM) Solution for Real-Time and Embedded Systems
3  * Copyright (C) 2006 - Javolution (http://javolution.org/)
4  * All rights reserved.
5  *
6  * Permission to use, copy, modify, and distribute this software is
7  * freely granted, provided that this notice is preserved.
8  */
9 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 extends RealtimeObject implements Reusable {
57  * private static final Factory<Foo> FACTORY = new Factory<Foo>() {
58  * public Foo create() {
59  * return new Foo();
60  * }
61  * public void cleanup(Foo obj) {
62  * obj.reset();
63  * }
64  * };
65  * public static Foo newInstance() {
66  * return FACTORY.object();
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 }
Popular Tags