A partir de la versión Java 1.3, Java incluyó la posibilidad de registrar un hilo especial, llamado gancho de apagado, que será ejecutado por la JVM cuando esté lista para apagarse. Sin un gancho de apagado, una aplicación no tendría forma de saber que se está cerrando. Por lo tanto, no tendría forma de saber que necesita completar cualquier trabajo en curso, y guardar cualquier dato que necesite ser preservado.

En esta ocasión el enfoque no será con detalles sobre ganchos de apagado pero mostramos brevemente qué son y como se registran con la JVM.

Registrar un Gancho de Apagado:

Thread shutdownHook = new Thread( "myapp-shutdown-hook" )
    {
        public void run()
        {
            System.out.println( "Starting MyApp shutdown..." );
            // Do some cleanup work.
            System.out.println( "MyApp shutdown complete." );
        }
    };
Runtime.getRuntime().addShutdownHook( shutdownHook );

Es posible y común tener multiples ganchos de apagado registrados. Normalmente, cada aplicación o componente principal registrará su propio gancho de apagado si es necesario. El registro de los ganchos de apagado debe realizarse como parte del proceso de inicialización para que un apagado se gestione correctamente, independientemente de su sincronización. En la mayoría de los casos, puede registrar un gancho de apagado y luego olvidarse que lo hizo.

Eliminar un Gancho de Apagado:

Por lo general, es posible codificar el gancho de apagado sin hacerlo, pero si descubre que necesita eliminar un gancho de apagado en algún momento, puede hacerlo de la siguiente manera:

Runtime.getRuntime().removeShutdownHook( shutdownHook );

Apagado de JVM:

Cuando la JVM inicia un apagado, supervisará todos los ganchos de apagado registrados y los lanzará cada uno como un nuevo hilo. Estos hilos se ejecutarán en paralelo hasta que todos se hayan completado. Cuando el último gancho de apagado haya terminado, la JVM se cerrará de inmediato, eliminando cualquier otro hilo que aún se esté ejecutando.

jvm 1    | Iniciando Apagado de MiApp...
jvm 1    | ...
jvm 1    | Apagado de MiApp completo.
wrapper  | <-- Wrapper Stopped

Un problema con los ganchos de apagado es que potencialmente pueden tardar horas en completarse. Durante este tiempo, normalmente no hay forma de decirle a Java que se cierre pronto. El Wrapper soluciona este problema usando el Tiempo de Espera de Salida de la JVM configurable, que a continuación se presenta.

Cuando se inicia el proceso de apagado de la JVM que se ha integrado con el Java Servicie Wrapper, la JVM ejecutará el gancho de apagado interno del Wrapper. El Wrapper usa su propio gancho de apagado para iniciar un apagado limpio de la aplicación integrada con el Wrapper y después realizar su propio proceso de limpieza.

Si es como la mayoría de los usuarios y utiliza el Método de Integración #1 (WrapperSimpleApp) o el Método de Integración #4 (WrapperJarApp) para su aplicación, entonces el gancho de apagado del Wrapper se completará casi inmediatamente.

Sin embargo, al usar el Método de Integración #2 o Método #3, entonces el gancho de apagado del Wrapper se ejecutará hasta que la aplicación se detenga. Para el método #2 WrapperStartStopApp, esto es cuando se completa el método principal de la clase de apagado registrada. Para la implementación del Método #3 WrapperListener, aquí es cuando se completa el método WrapperListener.stop().

El Wrapper define un tiempo de espera de apagado, que es la cantidad máxima de tiempo que permitirá que el gancho de apagado del Wrapper tarde en completarse. Si el apagado del Wrapper no informa de que se ha completado dentro de este tiempo de espera, el Wrapper asumirá que el proceso de apagado se ha congelado y eliminará la JVM a la fuerza. Esto se hace para solucionar problemas de apagado que, de otro modo, dejarían la aplicación en un estado inutilizable. El tiempo de espera de apagado predeterminado es de 30 segundos y se puede configurar usando la propiedad wrapper.shutdown.timeout.

jvm 1    | Deteniéndose...
wrapper  | Shutdown failed: Timed out waiting for signal from JVM.
wrapper  | JVM did not exit on request, terminated
wrapper  | <-- Wrapper Stopped

Una vez que se ha completado el ganche de apagado del Wrapper y se ha notificado al Wrapper que la JVM está lista para apagarse, el Wrapper entra en un modo en el que simplemente espera que la JVM se cierre por sí misma. Recuerde que la JVM lanza todos los ganchos de apagado registrados en paralelo. Esperará hasta que se complete el último y luego saldrá. Si alguno de los otros ganchos de apagado tarda mucho en completarse, entonces esto podría llevar un tiempo. Al igual que con el Tiempo de Espera de Apagado en la parte anterior, el Wrapper está diseñado para expirar después de un tiempo para evitar entrar en un estado en el que la aplicación no esté disponible. Por defecto, el tiempo de espera es de 15 segundos y se puede configurar usando la propiedad wrapper.jvm_exit.timeout.

jvm 1    | Deteniéndose...
jvm 1    | Se detuvo.
wrapper  | Shutdown failed: Timed out waiting for the JVM to terminate.
wrapper  | JVM did not exit on request, terminated
wrapper  | <-- Wrapper Stopped

Una vez que se haya completado el último gancho de apagado, el proceso de la JVM debería terminar casi inmediatamente. Una causa conocida por la que la salida tarda mucho es cuando se guarda un archivo de volcado cuando se ha habilitado la creación de perfiles de almacenamiento dinámico de la JVM.

Compatibilidad :	1.0.0
Ediciones :
Plataformas :

El primer método que probablemente encontrará es simplemente presionar CTRL-C mientras el Wrapper se ejecuta en una consola o terminal. Este método no requiere ningún desarrollo especial y se puede utilizar con prácticamente cualquier aplicación.

Windows:

Cuando el usuario presiona CTRL-C en Windows, el Wrapper envía la solicitud al proceso de Java. A continuación, Java gestiona la solicitud lanzando todos los ganchos de apagado que se hayan registrado en la aplicación.

...
wrapper  | CTRL-C trapped.  Shutting down.
jvm 1    | Iniciando Apagado de MiApp...
jvm 1    | ...
jvm 1    | Apagado de MiApp completo.
wrapper  | <-- Wrapper Stopped

UNIX:

En plataformas UNIX, CTRL-C hace que se envíe una señal INT al Wrapper. Esto hace que la salida se vea ligeramente diferente.

...
wrapper  | INT trapped.  Shutting down.
jvm 1    | Iniciando Apagado de MiApp...
jvm 1    | ...
jvm 1    | Apagado de MiApp completo.
wrapper  | <-- Wrapper Stopped

CTRL-C:

A veces, cuando se está desarrollando una aplicación, puede llegar a ser tedioso esperar siempre a que la aplicación se apague limpiamente. Si realmente desea apagarla de inmediato, el Wrapper le permite presionar CTRL-C por segunda vez para apagar la JVM. Si bien esta opción es muy útil, esto tiene el inconveniente de que es posible que los datos no se guarden correctamente porque los ganchos de apagado no se ejecutaron por completo.

...
wrapper  | CTRL-C trapped.  Shutting down.
jvm 1    | Iniciando Apagado de MiApp...
wrapper  | CTRL-C trapped.  Forcing immediate shutdown.
wrapper  | JVM did not exit on request, terminated
wrapper  | <-- Wrapper Stopped

Inhabilitar CTRL-C:

A la mayoría de usuarios les gusta hacer uso de esta función, pero si desea asegurarse de que la JVM siempre tenga la oportunidad de apagarse limpiamente, puede desactivar la función de apagado inmediato usando la propiedad wrapper.disable_forced_shutdown a partir de la versión 3.5.15 del Wrapper.

También hay casos en los que desea evitar intencionalmente que sus usuarios puedan detener la aplicación con CTRL-C. Esto se puede lograr fácilmente usando la propiedad wrapper.ignore_signals. Tenga en cuenta que al escoger esta opción, se necesitará usar uno de los otros métodos para apagar la aplicación.

wrapper  | CTRL-C trapped, but ignored.

Compatibilidad :	1.0.0
Ediciones :
Plataformas :

En plataformas UNIX, también es posible enviar una señal TERM al proceso del Wrapper. De hecho, así es como el script de shell incluido con el Wrapper solicita que se apague por defecto.

La señal TERM funciona casi igual que el método CTRL-C antes mencionado.

...
wrapper  | TERM trapped.  Shutting down.
jvm 1    | Iniciando Apagado de MiApp...
jvm 1    | ...
jvm 1    | Apagado de MiApp completo.
wrapper  | <-- Wrapper Stopped

Puede mandar esta señal desde la línea de comandos usando el siguiente comando.

kill {pid}

El {pid} debería reemplazarse con el Id del proceso del Wrapper. Si desea hacerlo mediante programación, puede hacer que el Wrapper almacene su Id de proceso actual en un archivo pid usando la propiedad wrapper.pidfile. Si está utilizando el script de shell, este archivo debería existir de forma predeterminada en el mismo directorio que el binario.

También se puede usar la propiedad wrapper.ignore_signals para inhabilitar este tipo de apagados.

wrapper  | TERM trapped, but ignored.

Compatibilidad :	1.0.0
Ediciones :
Plataformas :

Cuando se ejecuta como un servicio de Windows, es posible detener el servicio utilizando cualquier uno de una serie de comandos:

• Primera opción, detener el servicio desde el Panel de Control de Servicios ([Panel de Control] - [Administrador de Herramientas] - [Servicio]).
• Segunda opción, usar el comando net desde la línea de comandos:

net stop myapp

• Tercera opción, usar el comando sc, también desde la línea de comandos:

sc stop myapp

En cualquier caso, cuando se emite un comando para solicitar que se detenga un servicio, el Administrador de Control de Servicios de Windows controlará el proceso de cierre del servicio y luego informará cuando se complete. El Wrapper siempre responderá intentando cerrar la JVM limpiamente.

jvm 1    | ...
jvm 1    | Deteniéndose...
wrapper  | <-- Wrapper Stopped

Cuando se apaga el sistema en su totalidad, el Wrapper será apagado por el sistema operativo antes que dicho sistema sea apagado. Algunas versiones de Windows ignorarán los informes de que el servicio se está apagando si se toma demasiado tiempo y simplemente lo eliminarán si tarda demasiado. Si esto ocurre, es posible que vea un archivo de registro truncado, ya que el Wrapper y su JVM habrán sido eliminados a la fuerza por el sistema operativo.

wrapper  | User logged out.  Ignored.
wrapper  | Machine is shutting down.
jvm 1    | Deteniéndose...
wrapper  | <-- Wrapper Stopped

Compatibilidad :	3.1.1
Ediciones :
Plataformas :

El Wrapper puede configurarse para generar un archivo de anclaje mediante la propiedad wrapper.anchorfile. Los barcos utilizan un ancla para evitar que el barco se aleje flotando. Un ancla se utiliza en los barcos para evitar que el buque salga a flote. El Wrapper utiliza este archivo de la misma manera. Creará el archivo ancla al iniciar y después periódicamente se asegurará que todavía exista. Cuando y si el archivo se elimina alguna vez, el Wrapper iniciará inmediatamente el proceso de apagado.

jvm 1    | ...
wrapper  | Anchor file deleted.  Shutting down.
wrapper  | <-- Wrapper Stopped

En UNIX, si ha modificado el script de shell para ignorar las señales del sistema, utilizará este método para controlar cuándo debe apagarse el Wrapper.

Compatibilidad :	3.2.0
Ediciones :
Plataformas :

El Wrapper puede configurarse para buscar un archivo de comandos que puede contener cualquiera de una serie de comandos que el Wrapper interpretará. La ubicación de este archivo puede especificarse usando la propiedad wrapper.commandfile. Esta propiedad está deshabilitada por defecto.

Los comandos se emiten simplemente creando un archivo de texto que contenga el comando. El Wrapper eliminará el archivo tan pronto como se procese el comando.

STOP

jvm 1    | ...
wrapper  | Command 'STOP'. Shutting down with exit code 0.
jvm 1    | Deteniéndose...
wrapper  | <-- Wrapper Stopped

Si se utiliza este método, es importante, por supuesto, proteger el directorio donde se ubicará el archivo de comandos para asegurarse de que sólo los usuarios que deban poder emitir comandos puedan hacerlo. Consulte la documentación de la propiedad wrapper.commandfile para obtener una lista completa de los comandos disponibles, así como una serie de ejemplos.

Compatibilidad :	3.0.4
Ediciones :
Plataformas :

El Wrapper viene con una clase opcional que le permite conectarse con cualquier cliente Telnet para controlar el Wrapper de forma remota. Para utilizar este método es necesario añadir algunas líneas de código a la aplicación. Para una explicación completa de esta clase, por favor visite Javadocs WrapperActionServer. El Wrapper viene con una clase opcional que le permite conectarse con cualquier cliente Telnet para controlar remotamente el Wrapper Consulte los Javadocs de la clase WrapperActionServer para obtener una explicación completa.

Para configurar un servidor simple que sólo permita al cliente apagar el Wrapper, por favor intente añadir el siguiente código:

int port = 9999;
WrapperActionServer server = new WrapperActionServer( port );
server.enableShutdownAction( true );
server.start();

Se pueden habilitar acciones adicionales llamando a los métodos apropiados que se enumeran en los Javadocs.

Una vez que esto esté configurado, ahora puede conectarse a la aplicación con un comando telnet localhost 9999. Cuando esté conectado, simplemente presione la tecla S y el Wrapper se apagará limpiamente. Esto puede ser un riesgo potencial para la seguridad, así que asegúrese de proteger este puerto si lo usa. También es posible vincular el socket de escucha a localhost, impidiendo así las conexiones remotas.

Compatibilidad :	1.0.0
Ediciones :
Plataformas :

Como último resultado, o como parte de sus pruebas, es posible que desee forzar la eliminación del Wrapper. En Windows, puede hacerlo abriendo el Administrador de tareas, localizando el archivo wrapper.exe en la pestaña Procesos y luego presionando Finalizar tarea. En UNIX, puede hacer lo mismo usando una variante del comando kill kill -9 {pid}. En ambos casos, debe tener mucho cuidado de no finalizar el proceso incorrecto.

Cuando se elimina el proceso del Wrapper de esta manera, se termina inmediatamente y no tendrá la oportunidad de apagar la JVM limpiamente. El Wrapper está diseñado para que su componente Java inicie automáticamente el proceso de apagado de Java. Esto es crítico para evitar que la JVM se convierta en un proceso zombie incontrolado.

Cuando se elimina, el archivo de registro del Wrapper simplemente detendrá el registro en ese momento. Cualquier salida de registro de Java más allá de este punto no se incluirá en el archivo de registro.

Compatibilidad :	1.0.0
Ediciones :
Plataformas :

El proceso Java se puede eliminar casi de la misma manera como se hace con el proceso del Wrapper. Una vez más, esto normalmente no debería hacerse excepto como parte de sus pruebas. Puede usar la propiedad wrapper.java.pidfile para solicitar que el Wrapper escriba el ID del proceso del proceso Java.

Por defecto, cuando se elimina la JVM de esta manera, el Wrapper asumirá que se trata de un fallo y reiniciará la aplicación en una nueva JVM.

jvm 1    | ...
wrapper  | JVM exited unexpectedly.
wrapper  | Launching a JVM...
jvm 2    | WrapperManager: Inicializando...
jvm 2    | ...

Si mata el proceso Java de esta manera, no tendrá la oportunidad de ejecutar ninguno de sus ganchos de apagado, y por lo tanto no se cerrará limpiamente.

Compatibilidad :	1.0.0
Ediciones :
Plataformas :

Hay otras maneras de detener la JVM desde de la misma JVM. El método más común y que también no requiere un código específico de parte del Wrapper, es simplemente llamando System.exit(0). Cuando esto ocurra, la JVM iniciará su proceso de apagado normal, incluyendo la ejecución de todos los ganchos de apagado registrados.

jvm 1    | ...
jvm 1    | Deteniéndose...
wrapper  | <-- Wrapper Stopped

El argumento del método de salida se utiliza para especificar un código de salida (Exit Code) para la JVM. Los códigos de salida pueden ser muy útiles para ayudar a la aplicación que inició la JVM a comprender lo que sucedió. El Wrapper es capaz de reconocer diferentes códigos de salida y luego realizar diversas acciones en función de lo que desee hacer. Para más información sobre esta propiedad, por favor visite la página de la propiedad wrapper.on_exit.<n>.

Java también proporciona Runtime.getRuntime().halt(0), que hace posible apagar la JVM sin ejecutar ninguno de los ganchos de apagado registrados. Aunque esto puede ser útil en algunos casos, no recomendamos su uso con el Wrapper, ya que el Wrapper no tendrá forma de saber que la JVM se ha apagado intencionadamente. Cuando la JVM sale de esta forma, el Wrapper lo interpretará como un bloqueo de la JVM o una salida inesperada y, por lo tanto, reiniciará la JVM.

jvm 1    | ...
wrapper  | JVM exited unexpectedly.
wrapper  | Launching a JVM...
jvm 2    | WrapperManager: Inicializando...

Si realmente necesita apagar sin ejecutar ganchos de apagado, pruebe el método WrapperManager.stopimmediate(0) a continuación.

Compatibilidad :	1.0.0
Ediciones :
Plataformas :

Otro método es hacer uso de la API del Wrapper llamando a WrapperManager.stop(0). Cuando esto ocurra, la JVM iniciará su proceso de apagado normal, incluyendo la ejecución de todos los ganchos de apagado registrados.

jvm 1    | ...
jvm 1    | Deteniéndose...
wrapper  | <-- Wrapper Stopped

Compatibilidad :	3.0.4
Ediciones :
Plataformas :

Si desea apagar la JVM sin la ejecución de los ganchos de apagado registrados, lo puede hacer llamando al método WrapperManager.stopImmediate(0). Este método notificará al Wrapper que la JVM está planeando apagarse, pero lo hará sin la ejecución de los ganchos de apagado.

jvm 1    | ...
wrapper  | <-- Wrapper Stopped

Compatibilidad :	3.0.0
Ediciones :
Plataformas :

El Wrapper tiene una función que le permite registrar filtros en la salida de datos del registro de valores de la consola de la JVM y realizar cualquiera de una serie de acciones cuando se detecten valores específicos. Una de esas acciones es el de Apagado (SHUTDOWN). Para una lista completa de acciones disponibles, por favor consulte las propiedades wrapper.filter.action.<n> y wrapper.filter.trigger.<n>.

Filtros pueden ser de gran ayuda porque hacen posible agregar funcionalidad a aplicaciones sin la necesidad de un código Java. Un filtro se puede configurar completamente en el archivo de Configuración del Wrapper.

Para apagar la JVM cuando la aplicación registre el texto Alerta, se puede especificar un conjunto de propiedades como se muestra a continuación.

wrapper.filter.trigger.1=Oops
wrapper.filter.action.1=SHUTDOWN

jvm 1    | Hey I heard someone say Oops...
wrapper  | Filter trigger matched.  Shutting down.
jvm 1    | Deteniéndose...
wrapper  | <-- Wrapper Stopped

Además de los filtros, existen otras funciones que permiten especificar que se realice una determinada acción. Todas esas opciones pueden especificar una sola acción como Apagar (SHUTDOWN). Las siguientes propiedades son algunos ejemplos:

• wrapper.on_exit.<n>
• wrapper.timer.<n>.action
• wrapper.check.deadlock.action
• wrapper.event.<event_name>.command.block.action