KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javolution > context > Realtime


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.context;
10 import javolution.text.Text;
11
12 /**
13  * <p> This interface identifies classes whose instances can be moved to
14  * different {@link ObjectSpace ObjectSpace} for higher
15  * performance and higher predictability.</p>
16  *
17  * <p> Real-time objects may contain references to external real-time objects.
18  * These referenced objects might have to be moved along when the real-time
19  * object is moved. For example:[code]
20  * public class Person extends RealtimeObject { // Implements Realtime.
21  * private Person _mother; // External.
22  * private Person _father; // External.
23  * private final FastList<Person> _children = new FastList<Person>(); // Internal list.
24  * ...
25  * public boolean move(ObjectSpace os) {
26  * if (super.move(os)) { // Propagates to referenced objects.
27  * _mother.move(os);
28  * _father.move(os);
29  * // The children list itself is part of this object
30  * // and does not require any particular action, but it
31  * // references external objects which need to be moved along.
32  * for (Person child : _children) child.move(os);
33  * return true; // For sub-classes to do their part.
34  * }
35  * return false;
36  * }
37  * }[/code]</p>
38  *
39  * @author <a HREF="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
40  * @version 3.7, January 1, 2006
41  */
42 public interface Realtime {
43
44     /**
45      * Moves this real-time object to the specified object space.
46      *
47      * @param os the object space to move this real-time object to.
48      * @return <code>true</code> if the move has to be propagated to
49      * external real-time references; <code>false</code> otherwise.
50      */
51     boolean move(ObjectSpace os);
52
53     /**
54      * Returns the textual representation of this real-time object
55      * (equivalent to <code>toString</code> except that the returned value
56      * can be allocated from the local context space).
57      *
58      * @return this object's textual representation.
59      */
60     Text toText();
61
62     /**
63      * This class represents an object space which determinates when object
64      * recycling occurs. <ul>
65      * <li>{@link #HEAP}: Associated memory recycled through garbage collection
66      * when the object is not reachable (default).</li>
67      * <li>{@link #STACK}: Recycled when the current thread exits the scope of
68      * the {@link PoolContext} where the object has been
69      * "factory produced".</li>
70      * <li>{@link #HOLD}: Not recycled, moved back to its original space when
71      * internal preserve count drops to zero.</li>
72      * </li>
73      * Applications may create their own object space. Here are few examples
74      * of possible spaces with their defining characteristics.<ul>
75      * <li><b>AGING:</b> Recycling done when the objects are old enough.<br>
76      * <b>Constraint:</b> It assumes that old objects become
77      * obsolete and are not referenced anymore.</li>
78      * <li><b>FLIP:</b> Recycling done when the object space is flipped.<br>
79      * <b>Constraint:</b> Objects from previous period
80      * (before flip) are discarded.</li>
81      * </ul>
82      */
83     public static class ObjectSpace {
84         
85         /**
86          * Identifies the {@link HeapContext heap} space;
87          * objects are accessible by all; they are indirectly recycled
88          * through garbage collection (default space).
89          */
90         public static final ObjectSpace HEAP = new ObjectSpace();
91     
92         /**
93          * Identifies the {@link PoolContext stack} space;
94          * objects are accessible by the current thread only;
95          * they are recycled when the current thread
96          * {@link PoolContext#exit exits} the {@link PoolContext} scope
97          * where the object has been {@link ObjectFactory factory} produced.
98          */
99         public static final ObjectSpace STACK = new ObjectSpace();
100     
101         /**
102          * Identifies the current {@link Context#getOuter() outer} object space;
103          * it is the object space after {@link PoolContext#exit exiting}
104          * the current {@link PoolContext} (typically the {@link #HEAP}
105          * or another {@link #STACK} space).
106          */
107         public static final ObjectSpace OUTER = new ObjectSpace();
108     
109         /**
110          * Identifies the hold space; objects are accessible by all;
111          * they are moved back to their original space when not held
112          * anymore (internal counter).
113          */
114         public static final ObjectSpace HOLD = new ObjectSpace();
115     
116         /**
117          * Default constructor (allows extension).
118          */
119         public ObjectSpace() {}
120     
121     }
122 }
Popular Tags