WrapperSimpleApp


1   package org.tanukisoftware.wrapper;
2   
3   /*
4    * Copyright (c) 1999, 2006 Tanuki Software Inc.
5    * 
6    * Permission is hereby granted, free of charge, to any person
7    * obtaining a copy of the Java Service Wrapper and associated
8    * documentation files (the "Software"), to deal in the Software
9    * without  restriction, including without limitation the rights
10   * to use, copy, modify, merge, publish, distribute, sub-license,
11   * and/or sell copies of the Software, and to permit persons to
12   * whom the Software is furnished to do so, subject to the
13   * following conditions:
14   * 
15   * The above copyright notice and this permission notice shall be
16   * included in all copies or substantial portions of the Software.
17   * 
18   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 
19   * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES 
20   * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 
21   * NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT 
22   * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, 
23   * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
24   * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
25   * OTHER DEALINGS IN THE SOFTWARE.
26   * 
27   * 
28   * Portions of the Software have been derived from source code
29   * developed by Silver Egg Technology under the following license:
30   * 
31   * Copyright (c) 2001 Silver Egg Technology
32   * 
33   * Permission is hereby granted, free of charge, to any person
34   * obtaining a copy of this software and associated documentation
35   * files (the "Software"), to deal in the Software without 
36   * restriction, including without limitation the rights to use, 
37   * copy, modify, merge, publish, distribute, sub-license, and/or 
38   * sell copies of the Software, and to permit persons to whom the
39   * Software is furnished to do so, subject to the following 
40   * conditions:
41   * 
42   * The above copyright notice and this permission notice shall be
43   * included in all copies or substantial portions of the Software.
44   */
45  
46  import java.lang.reflect.InvocationTargetException  ;
47  import java.lang.reflect.Method  ;
48  import java.lang.reflect.Modifier  ;
49  
50  /**
51   * By default the WrapperSimpleApp will only wait for 2 seconds for the main
52   *  method of the start class to complete.  This was done because the main
53   *  methods of many applications never return.  It is possible to force the
54   *  class to wait for the startup main method to complete by defining the
55   *  following system property when launching the JVM (defaults to FALSE):
56   *  -Dorg.tanukisoftware.wrapper.WrapperSimpleApp.waitForStartMain=TRUE
57   * <p>
58   * Using the waitForStartMain property will cause the startup to wait
59   *  indefinitely.  This is fine if the main method will always return
60   *  within a predefined period of time.  But if there is any chance that
61   *  it could hang, then the maxStartMainWait property may be a better
62   *  option.  It allows the 2 second wait time to be overridden. To wait
63   *  for up to 5 minutes for the startup main method to complete, set
64   *  the property to 300 as follows (defaults to 2 seconds):
65   *  -Dorg.tanukisoftware.wrapper.WrapperSimpleApp.maxStartMainWait=300
66   * <p>
67   * It is possible to extend this class but make absolutely sure that any
68   *  overridden methods call their super method or the class will fail to
69   *  function correctly.  Most users will have no need to override this
70   *  class.
71   * <p>
72   * NOTE - The main methods of many applications are designed not to
73   *  return.  In these cases, you must either stick with the default 2 second
74   *  startup timeout or specify a slightly longer timeout, using the
75   *  maxStartMainWait property, to simulate the amount of time your application
76   *  takes to start up.
77   * <p>
78   * WARNING - If the waitForStartMain is specified for an application
79   *  whose start method never returns, the Wrapper will appear at first to be
80   *  functioning correctly.  However the Wrapper will never enter a running
81   *  state, this means that the Windows Service Manager and several of the
82   *  Wrapper's error recovery mechanisms will not function correctly.
83   *
84   * @author Leif Mortenson <leif@tanukisoftware.com>
85   */
86  public class WrapperSimpleApp
87      implements WrapperListener, Runnable  
88  {
89      /**
90       * Application's main method
91       */
92      private Method   m_mainMethod;
93      
94      /**
95       * Command line arguments to be passed on to the application
96       */
97      private String  [] m_appArgs;
98      
99      /**
100      * Gets set to true when the thread used to launch the application
101      *  actuially starts.
102      */
103     private boolean m_mainStarted;
104     
105     /**
106      * Gets set to true when the thread used to launch the application
107      *  completes.
108      */
109     private boolean m_mainComplete;
110     
111     /**
112      * Exit code to be returned if the application fails to start.
113      */
114     private Integer   m_mainExitCode;
115     
116     /**
117      * Flag used to signify that the start method has completed.
118      */
119     private boolean m_startComplete;
120     
121     /*---------------------------------------------------------------
122      * Constructors
123      *-------------------------------------------------------------*/
124     /**
125      * Creates an instance of a WrapperSimpleApp.
126      *
127      * @param The full list of arguments passed to the JVM.
128      */
129     protected WrapperSimpleApp( String   args[] )
130     {
131         
132         // Initialize the WrapperManager class on startup by referencing it.
133         Class   wmClass = WrapperManager.class;
134         
135         // Get the class name of the application
136         if ( args.length < 1 )
137         {
138             showUsage();
139             WrapperManager.stop( 1 );
140             return;  // Will not get here
141         }
142         
143         // Look for the specified class by name
144         Class   mainClass;
145         try
146         {
147             mainClass = Class.forName( args[0] );
148         }
149         catch ( ClassNotFoundException   e )
150         {
151             System.out.println( "WrapperSimpleApp: Unable to locate the class " + args[0] + ": "
152                 + e );
153             showUsage();
154             WrapperManager.stop( 1 );
155             return;  // Will not get here
156         }
157         catch ( LinkageError   e )
158         {
159             System.out.println( "WrapperSimpleApp: Unable to locate the class " + args[0] + ": "
160                 + e );
161             showUsage();
162             WrapperManager.stop( 1 );
163             return;  // Will not get here
164         }
165         
166         // Look for the main method
167         try
168         {
169             // getDeclaredMethod will return any method named main in the specified class,
170             //  while getMethod will only return public methods, but it will search up the
171             //  inheritance path.
172             m_mainMethod = mainClass.getMethod( "main", new Class  [] { String  [].class } );
173         }
174         catch ( NoSuchMethodException   e )
175         {
176             System.out.println(
177                 "WrapperSimpleApp: Unable to locate a public static main method in class "
178                 + args[0] + ": " + e );
179             showUsage();
180             WrapperManager.stop( 1 );
181             return;  // Will not get here
182         }
183         catch ( SecurityException   e )
184         {
185             System.out.println(
186                 "WrapperSimpleApp: Unable to locate a public static main method in class "
187                 + args[0] + ": " + e );
188             showUsage();
189             WrapperManager.stop( 1 );
190             return;  // Will not get here
191         }
192         
193         // Make sure that the method is public and static
194         int modifiers = m_mainMethod.getModifiers();
195         if ( !( Modifier.isPublic( modifiers ) && Modifier.isStatic( modifiers ) ) )
196         {
197             System.out.println( "WrapperSimpleApp: The main method in class " + args[0]
198                 + " must be declared public and static." );
199             showUsage();
200             WrapperManager.stop( 1 );
201             return;  // Will not get here
202         }
203         
204         // Build the application args array
205         String  [] appArgs = new String  [args.length - 1];
206         System.arraycopy( args, 1, appArgs, 0, appArgs.length );
207         
208         // Start the application.  If the JVM was launched from the native
209         //  Wrapper then the application will wait for the native Wrapper to
210         //  call the application's start method.  Otherwise the start method
211         //  will be called immediately.
212         WrapperManager.start( this, appArgs );
213         
214         // This thread ends, the WrapperManager will start the application after the Wrapper has
215         //  been properly initialized by calling the start method above.
216     }
217     
218     /*---------------------------------------------------------------
219      * Runnable Methods
220      *-------------------------------------------------------------*/
221     /**
222      * Used to launch the application in a separate thread.
223      */
224     public void run()
225     {
226         // Notify the start method that the thread has been started by the JVM.
227         synchronized( this )
228         {
229             m_mainStarted = true;
230             notifyAll();
231         }
232         
233         Throwable   t = null;
234         try
235         {
236             if ( WrapperManager.isDebugEnabled() )
237             {
238                 System.out.println( "WrapperSimpleApp: invoking main method" );
239             }
240             m_mainMethod.invoke( null, new Object  [] { m_appArgs } );
241             if ( WrapperManager.isDebugEnabled() )
242             {
243                 System.out.println( "WrapperSimpleApp: main method completed" );
244             }
245             
246             synchronized(this)
247             {
248                 // Let the start() method know that the main method returned, in case it is 
249                 //  still waiting.
250                 m_mainComplete = true;
251                 this.notifyAll();
252             }
253             
254             return;
255         }
256         catch ( IllegalAccessException   e )
257         {
258             t = e;
259         }
260         catch ( IllegalArgumentException   e )
261         {
262             t = e;
263         }
264         catch ( InvocationTargetException   e )
265         {
266             t = e.getTargetException();
267             if ( t == null )
268             {
269                 t = e;
270             }
271         }
272         
273         // If we get here, then an error was thrown.  If this happened quickly 
274         // enough, the start method should be allowed to shut things down.
275         System.out.println();
276         System.out.println( "WrapperSimpleApp: Encountered an error running main: " + t );
277 
278         // We should print a stack trace here, because in the case of an 
279         // InvocationTargetException, the user needs to know what exception
280         // their app threw.
281         t.printStackTrace();
282 
283         synchronized(this)
284         {
285             if ( m_startComplete )
286             {
287                 // Shut down here.
288                 WrapperManager.stop( 1 );
289                 return; // Will not get here.
290             }
291             else
292             {
293                 // Let start method handle shutdown.
294                 m_mainComplete = true;
295                 m_mainExitCode = new Integer  ( 1 );
296                 this.notifyAll();
297                 return;
298             }
299         }
300     }
301     
302     /*---------------------------------------------------------------
303      * WrapperListener Methods
304      *-------------------------------------------------------------*/
305     /**
306      * The start method is called when the WrapperManager is signalled by the 
307      *  native wrapper code that it can start its application.  This
308      *  method call is expected to return, so a new thread should be launched
309      *  if necessary.
310      * If there are any problems, then an Integer should be returned, set to
311      *  the desired exit code.  If the application should continue,
312      *  return null.
313      */
314     public Integer   start( String  [] args )
315     {
316         // Decide whether or not to wait for the start main method to complete before returning.
317         boolean waitForStartMain = WrapperSystemPropertyUtil.getBooleanProperty(
318             WrapperSimpleApp.class.getName() + ".waitForStartMain", false );
319         int maxStartMainWait = WrapperSystemPropertyUtil.getIntProperty(
320             WrapperSimpleApp.class.getName() + ".maxStartMainWait", 2 );
321         maxStartMainWait = Math.max( 1, maxStartMainWait ); 
322         
323         // Decide the maximum number of times to loop waiting for the main start method.
324         int maxLoops;
325         if ( waitForStartMain )
326         {
327             maxLoops = Integer.MAX_VALUE;
328             if ( WrapperManager.isDebugEnabled() )
329             {
330                 System.out.println( "WrapperSimpleApp: start(args) Will wait indefinitely "
331                     + "for the main method to complete." );
332             }
333         }
334         else
335         {
336             maxLoops = maxStartMainWait; // 1s loops.
337             if ( WrapperManager.isDebugEnabled() )
338             {
339                 System.out.println( "WrapperSimpleApp: start(args) Will wait up to " + maxLoops
340                     + " seconds for the main method to complete." );
341             }
342         }
343         
344         Thread   mainThread = new Thread  ( this, "WrapperSimpleAppMain" );
345         synchronized(this)
346         {
347             m_appArgs = args;
348             mainThread.start();
349             
350             // To avoid problems with the main thread starting slowly on heavily loaded systems,
351             //  do not continue until the thread has actually started.
352             while ( !m_mainStarted )
353             {
354                 try
355                 {
356                     this.wait( 1000 );
357                 }
358                 catch ( InterruptedException   e )
359                 {
360                     // Continue.
361                 }
362             }
363             
364             // Wait for startup main method to complete.
365             int loops = 0;
366             while ( ( loops < maxLoops ) && ( !m_mainComplete ) )
367             {
368                 try
369                 {
370                     this.wait( 1000 );
371                 }
372                 catch ( InterruptedException   e )
373                 {
374                     // Continue.
375                 }
376                 
377                 if ( !m_mainComplete )
378                 {
379                     // If maxLoops is large then this could take a while.  Notify the
380                     //  WrapperManager that we are still starting so it doesn't give up.
381                     WrapperManager.signalStarting( 5000 );
382                 }
383                 
384                 loops++;
385             }
386             
387             // Always set the flag stating that the start method completed.  This is needed
388             //  so the run method can decide whether or not it needs to be responsible for
389             //  shutting down the JVM in the event of an exception thrown by the start main
390             //  method.
391             m_startComplete = true;
392             
393             // The main exit code will be null unless an error was thrown by the start
394             //  main method.
395             if ( WrapperManager.isDebugEnabled() )
396             {
397                 System.out.println( "WrapperSimpleApp: start(args) end.  Main Completed="
398                     + m_mainComplete + ", exitCode=" + m_mainExitCode );
399             }
400             return m_mainExitCode;
401         }
402     }
403     
404     /**
405      * Called when the application is shutting down.
406      */
407     public int stop( int exitCode )
408     {
409         if ( WrapperManager.isDebugEnabled() )
410         {
411             System.out.println( "WrapperSimpleApp: stop(" + exitCode + ")" );
412         }
413         
414         // Normally an application will be asked to shutdown here.  Standard Java applications do
415         //  not have shutdown hooks, so do nothing here.  It will be as if the user hit CTRL-C to
416         //  kill the application.
417         return exitCode;
418     }
419     
420     /**
421      * Called whenever the native wrapper code traps a system control signal
422      *  against the Java process.  It is up to the callback to take any actions
423      *  necessary.  Possible values are: WrapperManager.WRAPPER_CTRL_C_EVENT, 
424      *    WRAPPER_CTRL_CLOSE_EVENT, WRAPPER_CTRL_LOGOFF_EVENT, or 
425      *    WRAPPER_CTRL_SHUTDOWN_EVENT
426      */
427     public void controlEvent( int event )
428     {
429         if ( ( event == WrapperManager.WRAPPER_CTRL_LOGOFF_EVENT )
430             && WrapperManager.isLaunchedAsService() )
431         {
432             // Ignore
433             if ( WrapperManager.isDebugEnabled() )
434             {
435                 System.out.println( "WrapperSimpleApp: controlEvent(" + event + ") Ignored" );
436             }
437         }
438         else
439         {
440             if ( WrapperManager.isDebugEnabled() )
441             {
442                 System.out.println( "WrapperSimpleApp: controlEvent(" + event + ") Stopping" );
443             }
444             WrapperManager.stop( 0 );
445             // Will not get here.
446         }
447     }
448     
449     /*---------------------------------------------------------------
450      * Methods
451      *-------------------------------------------------------------*/
452     /**
453      * Displays application usage
454      */
455     protected void showUsage()
456     {
457         System.out.println();
458         System.out.println(
459             "WrapperSimpleApp Usage:" );
460         System.out.println(
461             "  java org.tanukisoftware.wrapper.WrapperSimpleApp {app_class} [app_arguments]" );
462         System.out.println();
463         System.out.println(
464             "Where:" );
465         System.out.println(
466             "  app_class:      The fully qualified class name of the application to run." );
467         System.out.println(
468             "  app_arguments:  The arguments that would normally be passed to the" );
469         System.out.println(
470             "                  application." );
471     }
472     
473     /*---------------------------------------------------------------
474      * Main Method
475      *-------------------------------------------------------------*/
476     /**
477      * Used to Wrapper enable a standard Java application.  This main
478      *  expects the first argument to be the class name of the application
479      *  to launch.  All remaining arguments will be wrapped into a new
480      *  argument list and passed to the main method of the specified
481      *  application.
482      */
483     public static void main( String   args[] )
484     {
485         new WrapperSimpleApp( args );
486     }
487 }
488 
489
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags