KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > tanukisoftware > wrapper > 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 JavaDoc start( String JavaDoc[] 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
Popular Tags