WrapperListener


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  /**
47   * Applications which need to be controlled directly as a service can implement
48   *  the WrapperListener interface and then register themselves with the
49   *  WrapperManager on instantiation.  The WrapperManager will then control the
50   *  the class as a service for its entire life-cycle.
51   *
52   * @author Leif Mortenson <leif@tanukisoftware.com>
53   */
54  public interface WrapperListener
55  {
56      /**
57       * The start method is called when the WrapperManager is signaled by the 
58       *  native wrapper code that it can start its application.  This
59       *  method call is expected to return, so a new thread should be launched
60       *  if necessary.
61       * <p>
62       * If this method throws an exception the Wrapper will shutdown the current
63       *  JVM in an error state and then relaunch a new JVM.  It is the
64       *  responsibility of the user code to catch any exceptions and return an
65       *  appropriate exit code if the exception should result in the Wrapper
66       *  stopping.
67       *
68       * @param args List of arguments used to initialize the application.
69       *
70       * @return Any error code if the application should exit on completion
71       *         of the start method.  If there were no problems then this
72       *         method should return null.
73       */
74      Integer   start( String  [] args );
75      
76      /**
77       * Called when the application is shutting down.  The Wrapper assumes that
78       *  this method will return fairly quickly.  If the shutdown code code
79       *  could potentially take a long time, then WrapperManager.signalStopping()
80       *  should be called to extend the timeout period.  If for some reason,
81       *  the stop method can not return, then it must call
82       *  WrapperManager.stopped() to avoid warning messages from the Wrapper.
83       * <p>
84       * WARNING - Directly calling System.exit in this method will result in
85       *  a deadlock in cases where this method is called from within a shutdown
86       *  hook.  This method will be invoked by a shutdown hook if the JVM
87       *  shutdown was originally initiated by a call to System.exit.
88       *
89       * @param exitCode The suggested exit code that will be returned to the OS
90       *                 when the JVM exits.  If WrapperManager.stop was called
91       *                 to stop the JVM then this exit code will reflect that
92       *                 value.  However, if System.exit or Runtime.halt were
93       *                 used then this exitCode will always be 0.  In these
94       *                 cases, the Wrapper process will be able to detect the
95       *                 actual JVM exit code and handle it correctly.
96       *
97       * @return The exit code to actually return to the OS.  In most cases, this
98       *         should just be the value of exitCode, however the user code has
99       *         the option of changing the exit code if there are any problems
100      *         during shutdown.
101      */
102     int stop( int exitCode );
103     
104     /**
105      * Called whenever the native wrapper code traps a system control signal
106      *  against the Java process.  It is up to the callback to take any actions
107      *  necessary.  Possible values are: WrapperManager.WRAPPER_CTRL_C_EVENT, 
108      *    WRAPPER_CTRL_CLOSE_EVENT, WRAPPER_CTRL_LOGOFF_EVENT, 
109      *    WRAPPER_CTRL_SHUTDOWN_EVENT, WRAPPER_CTRL_TERM_EVENT, or
110      *    WRAPPER_CTRL_HUP_EVENT.
111      * <p>
112      * The WRAPPER_CTRL_C_EVENT will be called whether or not the JVM is
113      *  controlled by the Wrapper.  If controlled by the Wrapper, it is
114      *  undetermined as to whether the Wrapper or the JVM will receive this
115      *  signal first, but the Wrapper will always initiate a shutdown.  In
116      *  most cases, the implementation of this method should call
117      *  WrapperManager.stop() to initiate a shutdown from within the JVM.
118      *  The WrapperManager will always handle the shutdown correctly whether
119      *  shutdown is initiated from the Wrapper, within the JVM or both.
120      *  By calling stop here, it will ensure that the application will behave
121      *  correctly when run standalone, without the Wrapper.
122      * <p>
123      * WRAPPER_CTRL_CLOSE_EVENT, WRAPPER_CTRL_LOGOFF_EVENT, and
124      *  WRAPPER_CTRL_SHUTDOWN_EVENT events will only be encountered on Windows
125      *  systems.  Like the WRAPPER_CTRL_C_EVENT event, it is undetermined as to
126      *  whether the Wrapper or JVM will receive the signal first.  All signals
127      *  will be triggered by the OS whether the JVM is being run as an NT
128      *  service or as a console application.  If the JVM is running as a
129      *  console application, the Application must respond to the CLOSE and
130      *  LOGOFF events by calling WrapperManager.stop() in a timely manner.
131      *  In these cases, Windows will wait for the JVM process to exit before
132      *  moving on to signal the next process.  If the JVM process does not exit
133      *  within a reasonable amount of time, Windows will pop up a message box
134      *  for the user asking if they wish to wait for the process or exit or
135      *  forcibly close it.  The JVM must call stop() in response to the
136      *  SHUTDOWN method whether running as a console or NT service.  Usually,
137      *  the LOGOFF event should be ignored when the Wrapper is running as an
138      *  NT service.
139      * <p>
140      * WRAPPER_CTRL_TERM_EVENT events will only be encountered on UNIX systems.
141      * <p>
142      * If the wrapper.ignore_signals property is set to TRUE then any
143      *  WRAPPER_CTRL_C_EVENT, WRAPPER_CTRL_CLOSE_EVENT,
144      *  WRAPPER_CTRL_TERM_EVENT, or WRAPPER_CTRL_HUP_EVENT
145      *  events will be blocked prior to this method being called.
146      * <p>
147      * Unless you know what you are doing, it is suggested that the body of
148      *  this method contain the following code, or its functional equivalent.
149      * <pre>
150      *   public void controlEvent( int event )
151      *   {
152      *       if ( ( event == WrapperManager.WRAPPER_CTRL_LOGOFF_EVENT )
153      *           && WrapperManager.isLaunchedAsService() )
154      *       {
155      *           // Ignore
156      *       }
157      *       else
158      *       {
159      *           WrapperManager.stop( 0 );
160      *       }
161      *   }
162      * </pre>
163      *
164      * @param event The system control signal.
165      */
166     void controlEvent( int event );
167 }
168 
169
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags