001: /* ====================================================================
002: The Jicarilla Software License
003:
004: Copyright (c) 2003 Leo Simons.
005: All rights reserved.
006:
007: Permission is hereby granted, free of charge, to any person obtaining
008: a copy of this software and associated documentation files (the
009: "Software"), to deal in the Software without restriction, including
010: without limitation the rights to use, copy, modify, merge, publish,
011: distribute, sublicense, and/or sell copies of the Software, and to
012: permit persons to whom the Software is furnished to do so, subject to
013: the following conditions:
014:
015: The above copyright notice and this permission notice shall be
016: included in all copies or substantial portions of the Software.
017:
018: THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
019: EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
020: MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
021: IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
022: CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
023: TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
024: SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
025: ==================================================================== */
026: package org.jicarilla.lang;
027:
028: /**
029: * <p>An interface implemented by objects which need to do some kind of
030: * post-construction initialization before they can be used (like the creation
031: * of worker threads).</p>
032: *
033: * <div style="float: right; border: 1px solid #003399; padding: 10px"
034: * class="toc"> <b>Table of contents</b> <ul> <li>Documentation <ul> <li><a
035: * href="#TheActiveContract">The <code>Active</code> Contract</a></li> <li><a
036: * href="#StateDefinitions">State Definitions</a></li> <li><a
037: * href="#TheContractInReadableEnglish">The Contract In Readable
038: * English</a></li> <li><a href="#SomeNotesOnLifecycleManagement">Some Notes On
039: * Lifecycle Management</a></li> <li><a href="#EnforcingTheActiveContract">Enforcing
040: * The <code>Active</code> Contract</a></li> <li><a href="#ActiveComponentsAndThreadSafety"><code>Active</code>
041: * Components And Thread Safety</a></li>
042: *
043: * </ul></li> <li>API <ul> <!--<li>Fields: <a href="#field_summary">Summary</a>
044: * | <a href="#field_detail">Details</a></li> <li>Constructors: <a
045: * href="#constructor_summary">Summary</a> | <a href="#constructor_detail">Details</a></li>-->
046: * <li>Methods: <a href="#method_summary">Summary</a> | <a
047: * href="#method_detail">Details</a></li> </ul> </li> </ul> </div>
048: *
049: *
050: * <h3>The <code>Active</code> contract</h3><a name="TheActiveContract"></a>
051: *
052: * <p>For any component which implements this interface, the {@link
053: * #initialize()} method must be the <i>first</i> method called or field
054: * accessed after an instance is constructed, and it must be called <i>only
055: * once</i> It is usually safest to call <code>initialize()</code> immediately
056: * after construction to make sure of that. Note that it <i>is</i> okay to
057: * create an instance of a component which implements active and never do
058: * anything with it, not even calling <code>initialize()</code> or {@link
059: * #dispose()}.</p>
060: *
061: * <p>For any component which implements this interface, the
062: * <code>dispose()</code> method must be called <i>exactly once</i>. There is
063: * one exception to this rule: if <code>initialize()</code> is never called,
064: * <code>dispose()</code> should never be called, either. After it has been
065: * called, <i>no</i> more methods should be called on the instance, nor should
066: * any fields be accessed. There is an exception to this rule as well: the
067: * garbage collector may call a <code>finalize()</code> method if it exists,
068: * which in turn may access fields and call other methods.</p>
069: *
070: * <h3>State definitions</h3><a name="StateDefinitions"></a>
071: *
072: * <p>With passive components, we just have <i>safe</i> (the component can be
073: * safely used) and <i>unsafe</i> (the component cannot be safely used)
074: * <b>state</b>. With active components, we usually introduce some more
075: * terminology to describe component state:</p>
076: *
077: * <p>An object whose constructor has returned has been <i>created</i>. While
078: * the <code>initialize()</code> method is running the component is
079: * <i>initializing</i>. Once the <code>initialize()</code> method has returned,
080: * the object is <i>initialized</i> and <i>active</i>. It will remain active
081: * until the <code>dispose()</code> method is called. While the
082: * <code>dispose()</code> method is running, the component is <i>disposing</i>
083: * or <i>shutting down</i>. Once the <code>dispose()</code> method has
084: * returned, the component has <i>shut down</i> and it has been
085: * <i>disposed</i>.</p>
086: *
087: * <h3>The contract in readable English...</h3> <a name="TheContractInReadableEnglish"></a>
088: *
089: * <p>After you create an instance of an <code>Active</code> component, call
090: * its <code>initialize()</code> method. Then use the component as you would
091: * use any other. When you are finished using it, call the
092: * <code>dispose()</code> method.</p>
093: *
094: * <ul><b>some tips:</b> <li>call <code>initialize()</code> <i>immediately</i>
095: * after you construct an instance.</li> <li>To make sure an instance is only
096: * ever <code>initialize()</code>d and <code>dispose()</code>d once, keep the
097: * responsibility for calling these methods with the same code that is
098: * responsible for creating the instance.</li> <li>Remove all references to an
099: * instance <i>immediately</i> after you have called <code>dispose()</code> (to
100: * make sure you don't accidentally call a method on it again later, and so
101: * that the component may be reclaimed for garbage collection).</li> </ul>
102: *
103: * <h3>Some notes on lifecycle management</h3> <a name="SomeNotesOnLifecycleManagement"></a>
104: *
105: * <p>The <code>Active</code> interface is the only <i>lifecycle</i> interface
106: * to make it into the Jicarilla Framework. You should try to avoid its use as
107: * much as possible, as components that depend on having
108: * <code>initialize()</code> and <code>dispose()</code> require more work by
109: * the client programmer.</p>
110: *
111: * <p>One good reason to use the <code>Active</code> interface is when you need
112: * to use threads, since those should not be created inside a constructor (see
113: * <a href="http://lsd.student.utwente.nl/jicarilla/WellBehavedCitizens">Well
114: * Behaved Citizens</a> for more information).</p>
115: *
116: * <p>Also, while the contract surrounding <code>Active</code> should be
117: * crystal-clear to everyone and it should always.
118: *
119: * <p>For example of the <code>Active</code> interface in use, take a look at
120: * any of the jicarilla components. You will note its use is minimal: most
121: * components defer their thread management to helper components like thread
122: * pools, freeing them from the need to be <code>Active</code>.</p>
123: *
124: * <p>The inversion of <i>active</i> is <i>passive</i>. Try to make most of
125: * your code passive, controlled by isolated bits of active code.</p>
126: *
127: * <h3>Enforcing the <code>Active</code> contract</h3> <a
128: * name="EnforcingTheActiveContract"></a>
129: *
130: * <p>There's many different things you can do to make sure that client code
131: * doesn't fail, or at least fails gracefully, even if it doesn't honor the
132: * <code>Active</code> contract correctly:</p>
133: *
134: * <ul> <li>extend from the {@link org.jicarilla.lang.AbstractActive
135: * AbstractActive} interface. It implements basic 'wrapper' methods around
136: * <code>initialize() and <code>dispose()</code> that shield the client class
137: * from clients that call these methods in an inappropriate order, or more than
138: * once.</li> <li>implement <b>lazy (re)initialization.</b> To do this, you
139: * make all your fields private, then add checks at the top of every public
140: * method (and every protected method if you're really playing it safe) that
141: * will <code>initialize()</code> a component if it hasn't been initialized
142: * yet, and maybe even reset, then re-initialize a component if it has been
143: * disposed of already. The <code>AbstractActive</code> class implements such a
144: * policy inside the {@link org.jicarilla.lang.AbstractActive#lazyInitialization()
145: * lazyInitialization()} method.</li> <li>implement <b>state checking</b>. To
146: * do this, add checks at the top of every public method that will throw an
147: * exception if the component is not in an active state. The
148: * <code>AbstractActive</code> class implements such a policy inside {@link
149: * org.jicarilla.lang.AbstractActive#checkActive()
150: * checkActive()} method.</li> <li><b>Use a container</b>. If you run your
151: * components inside an IoC container that is aware of the <code>Active</code>
152: * interface, such as Jicarilla-Container, the container can take care of
153: * calling the <code>initialize()</code> and <code>dispose()</code> methods for
154: * you automatically. It can even shield your components from malicious clients
155: * by implementing a proxy (or a security policy) that will prevent them from
156: * calling the <code>initialize()</code> or <code>dispose()</code> methods at
157: * all!</li> </ul>
158: *
159: * <p>Before you go overboard with these measures, consider the alternative:
160: * trust. If you trust users of your components to be able to always remember
161: * and follow the <code>Active</code> contract, don't bother with all the
162: * checks (they clutter up the code and add overhead).</p>
163: *
164: * <h3>Active components and thread safety</h3> <a name="ActiveComponentsAndThreadSafety"></a>
165: *
166: * <p>Active components need all the usual synchronization and checking to be
167: * safe in a multithreaded enviroment. In particular, be extra careful when
168: * using lazy initialization or state checking, since you open up the
169: * possibility of two concurrently called methods deciding to do lazy
170: * initialization at the same time. Note that the relevant methods for these
171: * two policies inside <code>AbstractActive</code> are all synchronized to
172: * prevent this kind of problem.</p>
173: *
174: * @author <a href="lsimons at jicarilla dot org">Leo Simons</a>
175: * @version $Id: Active.java,v 1.1 2004/03/23 13:37:56 lsimons Exp $
176: */
177: public interface Active {
178: /**
179: * Initialize this object so that it is ready to be used. If an exception
180: * is thrown from this method, the instance should be assumed to be in an
181: * unsafe state, {@link #dispose()} should be immediately called, and then
182: * all references to the instance should be disposed of. Needless to say,
183: * throwing exceptions from this method should be a rare event.
184: *
185: * @throws Throwable if some problem occurs during initialization.
186: */
187: void initialize() throws Throwable;
188:
189: /**
190: * Shut down this object, telling it to clean up after itself (usually
191: * stopping and disposal of worker threads). If an exception is thrown from
192: * this
193: *
194: * @throws Throwable if some problem occurs during disposition.
195: */
196: void dispose() throws Throwable;
197: }
|