wrapperlistener.java

java程序写系统的服务

package org.tanukisoftware.wrapper;

/*
 * Copyright (c) 1999, 2006 Tanuki Software Inc.
 * 
 * Permission is hereby granted, free of charge, to any person
 * obtaining a copy of the Java Service Wrapper and associated
 * documentation files (the "Software"), to deal in the Software
 * without  restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sub-license,
 * and/or sell copies of the Software, and to permit persons to
 * whom the Software is furnished to do so, subject to the
 * following conditions:
 * 
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 
 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES 
 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 
 * NON-INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT 
 * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, 
 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 * OTHER DEALINGS IN THE SOFTWARE.
 * 
 * 
 * Portions of the Software have been derived from source code
 * developed by Silver Egg Technology under the following license:
 * 
 * Copyright (c) 2001 Silver Egg Technology
 * 
 * Permission is hereby granted, free of charge, to any person
 * obtaining a copy of this software and associated documentation
 * files (the "Software"), to deal in the Software without 
 * restriction, including without limitation the rights to use, 
 * copy, modify, merge, publish, distribute, sub-license, and/or 
 * sell copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following 
 * conditions:
 * 
 * The above copyright notice and this permission notice shall be
 * included in all copies or substantial portions of the Software.
 */

// $Log: WrapperListener.java,v $
// Revision 1.10  2006/02/24 05:45:57  mortenson
// Update the copyright.
//
// Revision 1.9  2005/05/23 02:41:12  mortenson
// Update the copyright information.
//
// Revision 1.8  2004/12/16 14:13:47  mortenson
// Fix a problem where TERM signals were not being correctly ignored by the JVM
// process on UNIX platforms even if wrapper.ignore_signals was set.
//
// Revision 1.7  2004/08/13 14:34:03  mortenson
// Fix a typo in javadoc references to the signalStopping() method.
//
// Revision 1.6  2004/06/15 05:26:57  mortenson
// Fix a problem where the Wrapper would sometimes hang on shutdown if
// another thread called System.exit while the Wrapper was shutting down.
// Bug #955248.
//
// Revision 1.5  2004/02/13 02:53:26  mortenson
// Add some javadocs describing what happens if an uncaught exception is thrown
// within the start method.
//
// Revision 1.4  2004/01/16 04:42:00  mortenson
// The license was revised for this version to include a copyright omission.
// This change is to be retroactively applied to all versions of the Java
// Service Wrapper starting with version 3.0.0.
//
// Revision 1.3  2003/06/19 05:45:02  mortenson
// Modified the suggested behavior of the WrapperListener.controlEvent() method.
//
// Revision 1.2  2003/04/03 04:05:23  mortenson
// Fix several typos in the docs.  Thanks to Mike Castle.
//
// Revision 1.1  2003/02/03 06:55:28  mortenson
// License transfer to TanukiSoftware.org
//

/**
 * Applications which need to be controlled directly as a service can implement
 *  the WrapperListener interface and then register themselves with the
 *  WrapperManager on instantiation.  The WrapperManager will then control the
 *  the class as a service for its entire life-cycle.
 *
 * @author Leif Mortenson <[e-mail]>
 * @version $Revision: 1.10 $
 */
public interface WrapperListener
{
    /**
     * The start method is called when the WrapperManager is signaled by the 
     *	native wrapper code that it can start its application.  This
     *	method call is expected to return, so a new thread should be launched
     *	if necessary.
     * <p>
     * If this method throws an exception the Wrapper will shutdown the current
     *  JVM in an error state and then relaunch a new JVM.  It is the
     *  responsibility of the user code to catch any exceptions and return an
     *  appropriate exit code if the exception should result in the Wrapper
     *  stopping.
     *
     * @param args List of arguments used to initialize the application.
     *
     * @return Any error code if the application should exit on completion
     *         of the start method.  If there were no problems then this
     *         method should return null.
     */
    Integer start( String[] args );
    
    /**
     * Called when the application is shutting down.  The Wrapper assumes that
     *  this method will return fairly quickly.  If the shutdown code code
     *  could potentially take a long time, then WrapperManager.signalStopping()
     *  should be called to extend the timeout period.  If for some reason,
     *  the stop method can not return, then it must call
     *  WrapperManager.stopped() to avoid warning messages from the Wrapper.
     * <p>
     * WARNING - Directly calling System.exit in this method will result in
     *  a deadlock in cases where this method is called from within a shutdown
     *  hook.  This method will be invoked by a shutdown hook if the JVM
     *  shutdown was originally initiated by a call to System.exit.
     *
     * @param exitCode The suggested exit code that will be returned to the OS
     *                 when the JVM exits.
     *
     * @return The exit code to actually return to the OS.  In most cases, this
     *         should just be the value of exitCode, however the user code has
     *         the option of changing the exit code if there are any problems
     *         during shutdown.
     */
    int stop( int exitCode );
    
    /**
     * Called whenever the native wrapper code traps a system control signal
     *  against the Java process.  It is up to the callback to take any actions
     *  necessary.  Possible values are: WrapperManager.WRAPPER_CTRL_C_EVENT, 
     *    WRAPPER_CTRL_CLOSE_EVENT, WRAPPER_CTRL_LOGOFF_EVENT, 
     *    WRAPPER_CTRL_SHUTDOWN_EVENT, or WRAPPER_CTRL_TERM_EVENT.
     * <p>
     * The WRAPPER_CTRL_C_EVENT will be called whether or not the JVM is
     *  controlled by the Wrapper.  If controlled by the Wrapper, it is
     *  undetermined as to whether the Wrapper or the JVM will receive this
     *  signal first, but the Wrapper will always initiate a shutdown.  In
     *  most cases, the implementation of this method should call
     *  WrapperManager.stop() to initiate a shutdown from within the JVM.
     *  The WrapperManager will always handle the shutdown correctly whether
     *  shutdown is initiated from the Wrapper, within the JVM or both.
     *  By calling stop here, it will ensure that the application will behave
     *  correctly when run standalone, without the Wrapper.
     * <p>
     * WRAPPER_CTRL_CLOSE_EVENT, WRAPPER_CTRL_LOGOFF_EVENT, and
     *  WRAPPER_CTRL_SHUTDOWN_EVENT events will only be encountered on Windows
     *  systems.  Like the WRAPPER_CTRL_C_EVENT event, it is undetermined as to
     *  whether the Wrapper or JVM will receive the signal first.  All signals
     *  will be triggered by the OS whether the JVM is being run as an NT
     *  service or as a console application.  If the JVM is running as a
     *  console application, the Application must respond to the CLOSE and
     *  LOGOFF events by calling WrapperManager.stop() in a timely manner.
     *  In these cases, Windows will wait for the JVM process to exit before
     *  moving on to signal the next process.  If the JVM process does not exit
     *  within a reasonable amount of time, Windows will pop up a message box
     *  for the user asking if they wish to wait for the process or exit or
     *  forcibly close it.  The JVM must call stop() in response to the
     *  SHUTDOWN method whether running as a console or NT service.  Usually,
     *  the LOGOFF event should be ignored when the Wrapper is running as an
     *  NT service.
     * <p>
     * WRAPPER_CTRL_TERM_EVENT events will only be encountered on UNIX systems.
     * <p>
     * If the wrapper.ignore_signals property is set to TRUE then any
     *  WRAPPER_CTRL_C_EVENT, WRAPPER_CTRL_CLOSE_EVENT, or WRAPPER_CTRL_TERM_EVENT
     *  events will be blocked prior to this method being called.
     * <p>
     * Unless you know what you are doing, it is suggested that the body of
     *  this method contain the following code, or its functional equivalent.
     * <pre>
     *   public void controlEvent( int event )
     *   {
     *       if ( ( event == WrapperManager.WRAPPER_CTRL_LOGOFF_EVENT )
     *           && WrapperManager.isLaunchedAsService() )
     *       {
     *           // Ignore
     *       }
     *       else
     *       {
     *           WrapperManager.stop( 0 );
     *       }
     *   }
     * </pre>
     *
     * @param event The system control signal.
     */
    void controlEvent( int event );
}