KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > java > plugin > Plugin


1 /*****************************************************************************
2  * Java Plug-in Framework (JPF)
3  * Copyright (C) 2004-2005 Dmitry Olshansky
4  *
5  * This library is free software; you can redistribute it and/or
6  * modify it under the terms of the GNU Lesser General Public
7  * License as published by the Free Software Foundation; either
8  * version 2.1 of the License, or (at your option) any later version.
9  *
10  * This library is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13  * Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public
16  * License along with this library; if not, write to the Free Software
17  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
18  *****************************************************************************/
19 package org.java.plugin;
20
21 import org.apache.commons.logging.Log;
22 import org.apache.commons.logging.LogFactory;
23 import org.java.plugin.registry.PluginDescriptor;
24
25 /**
26  * This is base for "home" class of plug-in runtime. Using this class,
27  * plug-in code can get access to plug-in framework
28  * ({@link org.java.plugin.PluginManager manager},
29  * {@link org.java.plugin.registry.PluginRegistry registry}) which was loaded it.
30  * It is also used by manager during plug-in life cycle management (activation
31  * and deactivation).
32  * <br>
33  * Plug-in vendor may provide it's own implementation of this class if some
34  * actions should be performed during plug-in activation/deactivation. When no
35  * class specified, framework provides default "empty" implementation that does
36  * nothing when plug-in started and stopped.
37  * @version $Id: Plugin.java,v 1.4 2005/07/20 18:43:46 ddimon Exp $
38  */
39 public abstract class Plugin {
40     /**
41      * Makes logging service available for descending classes.
42      */
43     protected final Log log = LogFactory.getLog(getClass());
44
45     private PluginManager manager;
46     private PluginDescriptor descriptor;
47     private boolean started;
48     
49     /**
50      * Constructor to be used by plug-in manager for plug-in instantiation.
51      * @see Class#newInstance()
52      */
53     protected Plugin() {
54         // no-op
55 }
56
57     /**
58      * Constructor to be used by plug-in manager for plug-in instantiation.
59      * Your plug-ins have to provide constructor with this exact signature to
60      * be successfully loaded by manager.
61      * @param aManager manager, which controls this plug-in
62      * @param descr descriptor of this plug-in
63      * @deprecated Define {@link #Plugin() no-arguments constructor} instead of
64      * this one if you need to run come code during class
65      * instantiation. Not though that it is not recommended to put
66      * any code within class constructor, use plug-in "lifecyle"
67      * methods {@link #doStart()} and {@link #doStop()} for that
68      * purposes.
69      */
70     public Plugin(final PluginManager aManager, final PluginDescriptor descr) {
71         this.manager = aManager;
72         this.descriptor = descr;
73         if (descr == null) {
74             throw new IllegalArgumentException JavaDoc("descriptor cannot be NULL"); //$NON-NLS-1$
75 }
76     }
77
78     /**
79      * @return descriptor of this plug-in
80      */
81     public final PluginDescriptor getDescriptor() {
82         return descriptor;
83     }
84     
85     /*
86      * For internal use only!
87      */
88     final void setDescriptor(final PluginDescriptor descr) {
89         this.descriptor = descr;
90     }
91     
92     /**
93      * @return manager which controls this plug-in
94      */
95     public final PluginManager getManager() {
96         return manager;
97     }
98     
99     /*
100      * For internal use only!
101      */
102     final void setManager(final PluginManager aManager) {
103         this.manager = aManager;
104     }
105
106     /*
107      * For internal use only!
108      */
109     final void start() throws Exception JavaDoc {
110         if (!started) {
111             doStart();
112             started = true;
113         }
114     }
115
116     /*
117      * For internal use only!
118      */
119     final void stop() throws Exception JavaDoc {
120         if (started) {
121             doStop();
122             started = false;
123         }
124     }
125
126     /**
127      * @return <code>true</code> if this plug-in is in active state
128      */
129     public final boolean isActive() {
130         return started;
131     }
132
133     /**
134      * This method will be called once during plug-in activation before any
135      * access to any code from this plug-in.
136      * @throws Exception if an error has occurred during plug-in start-up
137      */
138     protected abstract void doStart() throws Exception JavaDoc;
139
140     /**
141      * This method will be called once during plug-in deactivation. After
142      * this method call, no other code from this plug-in can be accessed,
143      * unless {@link #doStart()} method will be called again (but for another
144      * instance of this class).
145      * @throws Exception if an error has occurred during plug-in shutdown
146      */
147     protected abstract void doStop() throws Exception JavaDoc;
148
149     /**
150      * @see java.lang.Object#toString()
151      */
152     public String JavaDoc toString() {
153         return "{" + getClass().getName() //$NON-NLS-1$
154 + ": manager=" + manager //$NON-NLS-1$
155 + ", descriptor=" + descriptor //$NON-NLS-1$
156 + "}"; //$NON-NLS-1$
157 }
158 }
159
Popular Tags