001 //Copyright (C) 2006 A. Nelson
002 //
003 //This program is free software; you can redistribute it and/or
004 //modify it under the terms of the GNU General Public License
005 //as published by the Free Software Foundation; either version 2
006 //of the License, or (at your option) any later version.
007 //
008 //This program is distributed in the hope that it will be useful,
009 //but WITHOUT ANY WARRANTY; without even the implied warranty of
010 //MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
011 //GNU General Public License for more details.
012 //
013 //You should have received a copy of the GNU General Public License
014 //along with this program; if not, write to the Free Software
015 //Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
016
017
018 package pluginCore;
019
020 /**
021 * The base class for all plug-ins that are to be loaded in the PluginCore.
022 *
023 * Plugin saveing and loading.
024 * The plugin must have a number of abstract methods written that will
025 * allow it to operate with other plugins and the plugin core.
026 *
027 * int send( Message messIn)
028 * This method receves the messages sent from other plugins,
029 * if your plugin does not intend to receve messages it can
030 * safely return error (-1) on this.
031 *
032 * boolean init( CoreHandler coreIn )
033 *
034 * void run()
035 *
036 * void shutdown()
037 *
038 * Object[] savePluginState( )
039 *
040 * boolean setPluginState( Object[] stateVec )
041 **/
042 public abstract class Plugin extends Thread {
043
044 /**
045 * The stub used to make calls back to the PluginCore.
046 **/
047 transient protected CoreHandler frameworkCore;
048
049 /**
050 * The Id of this plug-in.
051 **/
052 protected int pluginID;
053
054 /**
055 * Enable or disables debugging.
056 **/
057 protected boolean DEBUG = false;
058
059 /**
060 * Enable or disable the traceing.
061 */
062 protected boolean TRACE = false;
063
064 /**
065 * The name of this plug-in.
066 **/
067 protected String pluginName;
068
069 /**
070 * Nice empty constructor.
071 **/
072 public Plugin () {
073
074
075 }
076
077 /** Abstract Methods **/
078
079 /**
080 * The main loop of the plug-in.
081 **/
082 public abstract void run();
083
084 /**
085 * Called by the PluginCore, allows plug-ins to exit in a tidy and controlled manner. This call is followed by a safeJoin() call.
086 **/
087 public abstract void shutdown();
088
089 /**
090 * Hands a message to the plug-in from another plug-in via the PluginCore.
091 * @param msgIn The message that is being delivered.
092 * @return 1 on success, -1 on failure.
093 **/
094 public abstract int receive( Message msgIn );
095
096 /**
097 * Saves the current state of the object in a Vector.
098 * The order that objects are stored is very important to this
099 * and it is expected that the programer puts the fully qualified
100 * name of the originateing object as the frist field in the Vector
101 * so that other plugins can quickly identify the source of the data.
102 * @return The data from inside of the plugin held in a vector.
103 */
104 public abstract Object[] savePluginState( );
105
106 /**
107 * Sets the current state of the object using a vector of
108 * objects. It is the job of the programer to properly
109 * interpert and use the data that is handed in from
110 * the vector.
111 * According to protocol it is proper to put the object name as the first
112 * field in the vector so that a later object can quickly idnetify
113 * how to deal with the data in the vector.
114 * @param stateVec This Vector object will hold the objects to load from.
115 * @return True on sucess, false otherwise.
116 */
117 public abstract boolean setPluginState( Object[] stateVec );
118
119
120 /**
121 * Sets the plug-in id for this plug-in.
122 * @param id The new Id.
123 **/
124 public void setID(int id){
125
126 pluginID = id;
127 }
128
129 /**
130 * Saves the core handler to the frameworkCore variable.
131 * @param coreIn The core that is to be saved.
132 */
133 public void setCoreHandeler( CoreHandler coreIn ){
134
135 frameworkCore = coreIn;
136 }
137 /**
138 * Gets the plugin's Id.
139 * @return The plugin's Id.
140 **/
141 public int getID( ) {
142
143 return pluginID;
144 }
145
146 /**
147 * Sets the plugin's state with a object array from a previous plugin.
148 * @param stateIn The object array with the saved state.
149 * @param coreIn The CoreHandler from the running core.
150 * @return True on sucess, else false.
151 * @throws java.io.IOException
152 */
153 public boolean loadNewState( Object[] stateIn, CoreHandler coreIn )throws java.io.IOException{
154
155 if( frameworkCore != null ){
156
157 printError("This object has a running core!");
158 return false;
159 }
160
161 frameworkCore = coreIn;
162
163 return setPluginState( stateIn );
164 }
165
166
167 /**
168 * Calls join and returns true if it was successful, false otherwise.
169 * @return True if successful, else false.
170 **/
171 public boolean safeJoin() {
172
173 try {
174
175 this.join( );
176 }catch( InterruptedException e ) {
177
178 printError("safeJoin caught exception " + e );
179 return false;
180 }
181 return true;
182 }
183 /**
184 * Sleeps the thread for timeToSleep milliseconds.
185 * @return True if successful, else false.
186 **/
187 public boolean safeSleep( int timeToSleep ){
188
189 try {
190
191 Thread.sleep( timeToSleep );
192 }catch( InterruptedException e ) {
193
194 return false;
195 }
196 return true;
197 }
198
199
200 /**
201 * Identifies if Debugging is enabled for this plug-in.
202 * @return True if debugging is enabled, else false.
203 **/
204 public boolean debugStatus(){
205
206 return DEBUG;
207 }
208
209 /**
210 * Calls join and returns true if it was successful, false otherwise.
211 * @param timer The number of milliseconds to wait before forceing shutdown.
212 * @return True if successful, else false.
213 **/
214 public boolean safeJoin( int timer ) {
215
216 try {
217
218 this.join( timer );
219 }catch( InterruptedException e ) {
220
221 printError("safeJoin caught exception " + e );
222 return false;
223 }
224 return true;
225 }
226
227 /**
228 * Gets the name of the plug-in.
229 * @return The String name of the plug-in.
230 **/
231 public String getPluginName() {
232
233 return pluginName;
234 }
235
236 /**
237 * This can be turned off by setting TRACE to false, but will print the class name,
238 * plus the included method name.
239 * @param traceString This is also printed with the trace call.
240 */
241 protected void printTrace( String traceString ){
242
243 if( TRACE == false ) return;
244 System.out.println( this.getClass().getName() + traceString );
245 }
246
247 /**
248 * This will place debugging output in your program, turn on or off by setting DEBUG true/false.
249 * @param debugMsg This is the message to be printed with the debug.
250 */
251 protected void printDebug( String debugMsg ) {
252
253 if( DEBUG == true )
254 System.out.println( pluginName
255 + "(" + pluginID + "): "
256 + debugMsg );
257 }
258
259 /**
260 * This will allways print out the errorMsg to System.err
261 * @param errorMsg The error to print.
262 */
263 protected void printError( String errorMsg ) {
264
265 /**
266 * This should have a error on or off.
267 **/
268 System.err.println( "Error occourred in "
269 + pluginName
270 + "(" + pluginID + "): "
271 + errorMsg );
272 }
273
274 /**
275 * Gets the String value of the plug-in.
276 * @return The String value of the plug-in.
277 **/
278 public String toString(){
279
280 return pluginName;
281 }
282 }