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: * Fault-tolerant {@link Active} class which synchronizes initialize() and
030: * dispose() and will silently ignore repeated or otherwise inappropriate calls
031: * to either method, thus freeing subclasses from the need to check against
032: * repeated calls. Furthermore, it contains several protected utility methods
033: * that allow you to implement both the state checking and lazy initialization
034: * code patterns described in the documentation for the <code>Active</code>
035: * interface.
036: *
037: * @author <a href="lsimons at jicarilla dot org">Leo Simons</a>
038: * @version $Id: AbstractActive.java,v 1.1 2004/03/23 13:37:57 lsimons Exp $
039: */
040: public abstract class AbstractActive implements Active {
041: /** Whether we're running. */
042: protected boolean m_running = false;
043: /** Whether we've stopped. */
044: protected boolean m_stopped = false;
045:
046: /**
047: * Intialize the component.
048: *
049: * @throws Throwable in case of a problem.
050: * @see org.jicarilla.lang.Active#initialize()
051: */
052: public final synchronized void initialize() throws Throwable {
053: if (!m_running)
054: // if(!m_stopped)
055: {
056: doInitialize();
057: }
058: m_running = true;
059: }
060:
061: /**
062: * This method is called from initialize(). Override it in subclasses to
063: * implement 'active' behaviour. There's no need to call the base method.
064: *
065: * @throws Throwable in case of a problem.
066: */
067: protected void doInitialize() throws Throwable {
068: };
069:
070: /**
071: * Dispose of the component.
072: *
073: * @throws Throwable in case of a problem.
074: * @see org.jicarilla.lang.Active@dispose()
075: */
076: public final synchronized void dispose() throws Throwable {
077: if (!m_running)
078: return;
079:
080: m_running = false;
081: doDispose();
082: m_stopped = true;
083: }
084:
085: /**
086: * This method is called from dispose(). Override it in subclasses to
087: * implement 'active' behaviour. There's no need to call the base method.
088: *
089: * @throws Throwable in case of a problem.
090: */
091: protected void doDispose() throws Throwable {
092: };
093:
094: /**
095: * Check whether we're initialized.
096: *
097: * @return true if we are, false otherwise.
098: */
099: protected final synchronized boolean isInitialized() {
100: return m_running;
101: }
102:
103: /**
104: * Check whether we're disposed.
105: *
106: * @return true if we are, false otherwise.
107: */
108: protected final synchronized boolean isDisposed() {
109: return m_stopped;
110: }
111:
112: /**
113: * Check whether we're active.
114: *
115: * @return true if we are, false otherwise.
116: */
117: protected final synchronized boolean isActive() {
118: return (m_running && !m_stopped);
119: }
120:
121: /**
122: * Check whether we're active.
123: *
124: * @throws AssertionError if we're not active
125: */
126: protected final synchronized void checkActive() {
127: Assert.assertFalse(
128: "This component has been dispose()d of, don't use it!",
129: m_stopped);
130: Assert.assertTrue("You must call initialize() first!",
131: m_running);
132: }
133:
134: /**
135: * Helps implement lazy initialization (and even re-initialization if we
136: * implement {@link org.jicarilla.lang.Recyclable}). Call
137: * this method on the first line of all the public (and optionally all
138: * protected) methods in your subclass.
139: *
140: * @throws Throwable if an exception occurs during {@link #initialize()}
141: * @throws AssertionError if we've been disposed of and we don't implement
142: * Recyclable
143: */
144: protected final synchronized void lazyInitialization()
145: throws Throwable {
146: // we're active, all is fine
147: if (m_running)
148: return;
149:
150: // we're not yet initialized, do it now
151: if (!m_stopped) {
152: initialize();
153: return;
154: }
155:
156: // we're disposed of...
157:
158: // ...maybe we can recycle ourselves though...
159: if (this instanceof Recyclable) {
160: m_running = false;
161: m_stopped = false;
162: ((Recyclable) this ).recycle();
163: initialize();
164: return;
165: }
166:
167: // ...no, we can't!
168: throw new AssertionError(
169: "This component has been dispose()d of, don't use it!");
170: }
171: }
|