Source Code Cross Referenced for Active.java in  » Web-Server » JicarillaHTTP » org » jicarilla » lang » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Java Source Code / Java Documentation
1. 6.0 JDK Core
2. 6.0 JDK Modules
3. 6.0 JDK Modules com.sun
4. 6.0 JDK Modules com.sun.java
5. 6.0 JDK Modules sun
6. 6.0 JDK Platform
7. Ajax
8. Apache Harmony Java SE
9. Aspect oriented
10. Authentication Authorization
11. Blogger System
12. Build
13. Byte Code
14. Cache
15. Chart
16. Chat
17. Code Analyzer
18. Collaboration
19. Content Management System
20. Database Client
21. Database DBMS
22. Database JDBC Connection Pool
23. Database ORM
24. Development
25. EJB Server geronimo
26. EJB Server GlassFish
27. EJB Server JBoss 4.2.1
28. EJB Server resin 3.1.5
29. ERP CRM Financial
30. ESB
31. Forum
32. GIS
33. Graphic Library
34. Groupware
35. HTML Parser
36. IDE
37. IDE Eclipse
38. IDE Netbeans
39. Installer
40. Internationalization Localization
41. Inversion of Control
42. Issue Tracking
43. J2EE
44. JBoss
45. JMS
46. JMX
47. Library
48. Mail Clients
49. Net
50. Parser
51. PDF
52. Portal
53. Profiler
54. Project Management
55. Report
56. RSS RDF
57. Rule Engine
58. Science
59. Scripting
60. Search Engine
61. Security
62. Sevlet Container
63. Source Control
64. Swing Library
65. Template Engine
66. Test Coverage
67. Testing
68. UML
69. Web Crawler
70. Web Framework
71. Web Mail
72. Web Server
73. Web Services
74. Web Services apache cxf 2.0.1
75. Web Services AXIS2
76. Wiki Engine
77. Workflow Engines
78. XML
79. XML UI
Java
Java Tutorial
Java Open Source
Jar File Download
Java Articles
Java Products
Java by API
Photoshop Tutorials
Maya Tutorials
Flash Tutorials
3ds-Max Tutorials
Illustrator Tutorials
GIMP Tutorials
C# / C Sharp
C# / CSharp Tutorial
C# / CSharp Open Source
ASP.Net
ASP.NET Tutorial
JavaScript DHTML
JavaScript Tutorial
JavaScript Reference
HTML / CSS
HTML CSS Reference
C / ANSI-C
C Tutorial
C++
C++ Tutorial
Ruby
PHP
Python
Python Tutorial
Python Open Source
SQL Server / T-SQL
SQL Server / T-SQL Tutorial
Oracle PL / SQL
Oracle PL/SQL Tutorial
PostgreSQL
SQL / MySQL
MySQL Tutorial
VB.Net
VB.Net Tutorial
Flash / Flex / ActionScript
VBA / Excel / Access / Word
XML
XML Tutorial
Microsoft Office PowerPoint 2007 Tutorial
Microsoft Office Excel 2007 Tutorial
Microsoft Office Word 2007 Tutorial
Java Source Code / Java Documentation » Web Server » JicarillaHTTP » org.jicarilla.lang 
Source Cross Referenced  Class Diagram Java Document (Java Doc) 


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:        }
www.java2java.com | Contact Us
Copyright 2009 - 12 Demo Source and Support. All rights reserved.
All other trademarks are property of their respective owners.