A partir de la versión Java 1.3, Java permite registrar un proceso especial llamado gancho de apagado, que será ejecutado por la JVM cuando este lista para ser apagada. Sin un gancho de apagado, una aplicación no tendría manera alguna de saber que esta siendo apagada. Por lo tanto tampoco tendría una manera de saber que necesita completar algún trabajo en progreso y guardar cualquier información que se necesite.

En esta ocasión el enfoque no será con detalles sobre ganchos de apagado pero mostramos brevemente que 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( "Iniciando Apagado de MiApp..." );
            // Do some cleanup work.
            System.out.println( "Apagado de MiApp completo." );
        }
    };
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 debe realizarse como parte del proceso de inicio para que un apagado sea controlado correctamente, independientemente de su sincronización. En la mayoría de los casos, puede registrar un gancho de apagado y después olvidar que lo hizo.

Remover Gancho de Apagado:

Por lo general es posible codificar el gancho de apagado sin hacerlo, pero si necesita removerlo en algún momento lo puede hacer 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 lanzará cada uno de ellos como nuevos subprocesos. Estos subprocesos se ejecutarán en paralelo hasta que todos se hayan completado. Cuando el último gancho de apagado haya terminado, la JVM inmediatamente saldrá, eleminando todos los otros subprocesos que todavía esten en ejecución.

jvm 1    | Iniciando Apagado de MiApp...
jvm 1    | ...
jvm 1    | Apagado de MiApp completo.
wrapper  | <-- El Wrapper se detuvo.

Un problema con los ganchos de apagado es que potencialmente pueden tardar horas en completarse. Durante ese tiempo, normalmente no hay manera alguna de ordenarle a Java que se apague de manera rápida. El Wrapper soluciona este problema usando la propiedad configurable Tiempo de Espera JVM Exit que a continuación se presenta.

Cuando se inicia el proceso de apagado de la JVM, el cual viene 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.

Normalmente la mayoría de usuarios decide usar el Método de Integración # 1 (WrapperSimpleApp) o 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 haya sido detenida . Con el método 2 WrapperStartStopApp el registro se lleva a cabo cuando el método principal del apagado registrado de la clase se haya completado. Para el método 3 WrapperListener dicho registro es implementado cuando el método WrapperListener.stop() es completado.

El Wrapper define el tiempo de espera de un apagado el cual es el tiempo máximo de espera que permitirá que el gancho de apagado del Wrapper se complete totalmente. Si el apagado del Wrapper no manda un reporte que ya se ha completado dicho proceso dentro del período de tiempo de espera especificado, el Wrapper asumirá que el proceso se ha congelado y por consiguiente apagará de inmediato la JVM. Esto es hecho como solución a problemas de apagado, que en caso opuesto dejaría la aplicación en un estado inestable. El tiempo de espera del apagado es de 30 segundos y puede configurarse usando la propiedad wrapper.shutdown.timeout.

jvm 1    | Deteniéndose...
wrapper  | Error en el Apagado: Tiempo de espera: Esperando por una señal de la JVM.
wrapper  | JVM did not exit on request, terminated
wrapper  | <-- El Wrapper se detuvo

Después de que el gancho de apagado del Wrapper se ha completado y notificado que la JVM esta lista para el apagado, el Wrapper entra en un modo en el que simplemente está esperando para que la JVM termine por su cuenta. Recordemos que la JVM lanza todos los ganchos de apagado registrados en paralelo y esperará hasta que el último se haya completado y después salir. Al igual que con el Tiempo de Espera del Apagado en la parte de arriba, el Wrapper está diseñado con un tiempo máximo de espera y evitar entrar en un estado en el que la aplicación no este disponible. Por defecto el tiempo de espera es de 15 segundos y puede ser configurado usando la propiedad wrapper.jvm_exit.timeout.

jvm 1    | Deteniéndose...
jvm 1    | Se detuvo.
wrapper  | Error en el Apagado: Tiempo de espera: Esperando a que la JVM termine. 
wrapper  | JVM did not exit on request, terminated
wrapper  | <-- El Wrapper se detuvo

Una vez que el último de los ganchos de apagado se ha completado, el proceso de la JVM debe terminar casi inmediatamente. Una razón por la cual la salida toma mucho tiempo, es cuando un archivo de volcado de memoria esta siendo guardado cuando el montículo de perfiles de la JVM ha sido habilitado.

Compatibilidad :	1.0.0
Ediciones :
Plataformas :

El primer método con el que normalmente se encontrará es al presionar CTRL-C mientras el Wrapper este en función en la consola o terminal. Este método no requiere un desarrollo especial y puede ser usado con casi cualquier aplicación.

Windows:

Cuando el usuario presiona CTRL-C en Windows, el Wrapper envia esta solicitud al proceso Java. Dicho proceso continúa cuando Java controla dicha solicitud ejecutando todos los ganchos de apagado que esten registrados en la aplicación.

...
wrapper  | CTRL-C detectado. Apagando.
jvm 1    | Iniciando Apagado de MiApp...
jvm 1    | ...
jvm 1    | Apagado de MiApp completo..
wrapper  | <-- El Wrapper se detuvo

UNIX:

En plataformas UNIX CTRL-C causa que se envie al Wrapper una señal INT. Esto ocasiona que la salida de datos se genere un poco diferente.

...
wrapper  | INT detectado. Apagando.
jvm 1    | Iniciando Apagado de MiApp...
jvm 1    | ...
jvm 1    | Apagado de MiApp completo..
wrapper  | <-- El Wrapper se detuvo

CTRL-C:

En ocasiones, cuando se está desarrollando una aplicación, puede ser cansado esperar siempre a que la aplicación se apague limpiamente. Si usted realmente desea apagarla inmediatamente, el Wrapper le permite pulsar CTRL-C por segunda vez para apagar la JVM de esa manera. Aunque esta opción es muy útil, tiene el inconveniente de que los datos posiblemente no se guarden correctamente debido a que los ganchos de apagado no terminarán de ejecutarse completamente.

...
wrapper  | CTRL-C detectado.  Apagando.
jvm 1    | Iniciando Apagado de MiApp...
wrapper  | CTRL-C detectado.  Forzando apagado inmediato.
wrapper  | JVM did not exit on request, terminated
wrapper  | <-- El Wrapper se detuvo

Inhabilitar CTRL-C:

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

Hay algunos casos cuando quiera de una manera intencional evitar que sus usuarios puedan detener la aplicación usando CTRL-C. Esto es muy fácil de hacer, usando la propiedad wrapper.ignore_signals. Tomar 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 detectado, pero ignorado.

Compatibilidad :	1.0.0
Ediciones :
Plataformas :

En plataformas UNIX, también es posible enviar una señal TERM al proceso del Wrapper. En realidad esta es la manera en la que el intérprete de comandos el cual viene incluido con el Wrapper, solicita que este se apague por defecto.

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

...
wrapper  | TERM detectado.  Apagando.
jvm 1    | Iniciando Apagado de MiApp...
jvm 1    | ...
jvm 1    | Apagado de MiApp completo..
wrapper  | <-- El Wrapper se detuvo

Usted 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 esta usando el intérprete de comandos (shell) del Wrapper entonces este archivo debería existir por defecto, en el mismo directorio que el del Wrapper.

La propiedad wrapper.ignore_signals se puede usar para inhabilitar este tipo de apagados.

wrapper  | TERM detectado, pero ignorado.

Compatibilidad :	1.0.0
Ediciones :
Plataformas :

Cuando se esta usando el Servicio de Windows, es posible detener el servicio a través de un número de comandos.

• Primer paso, detener el servicio del Panel de Control de Servicios ([Panel de Control] - [Administrador de Herramientas] - [Servicio]).
• Segundo paso usando el comando net desde la línea de comandos:

net stop myapp

• Tercer paso usando el comando sc también desde la línea de comandos:

sc stop myapp

En cualquier caso, cuando se configura un comando para solicitar que un servicio se detenga, el Administrador de Control del Servicio de Windows se hará cargo del proceso de apagado y luego informar que se haya completado. El Wrapper siempre responderá al intentar apagar la JVM limpiamente.

jvm 1    | ...
jvm 1    | Deteniéndose...
wrapper  | <-- El Wrapper se detuvo

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 no harán caso a los informes de que el servicio se está cerrando si se toma demasiado tiempo y simplemente de manera inmediata se eliminará el servicio. Si esto sucede, es posible ver un archivo de registro truncado mostrando como el Wrapper y su JVM fueron eliminados por el sistema operativo.

wrapper  | User logged out.  Ignored.
wrapper  | La máquina se esta apagando.
jvm 1    | Deteniéndose...
wrapper  | <-- El Wrapper se detuvo

Compatibilidad :	3.1.1
Ediciones :
Plataformas :

El Wrapper puede ser configurado para generar una salida de datos del anclaje usando la propiedad wrapper.anchorfile. Un anclaje es utilizado por los barcos para mantenerse a flote. El Wrapper utiliza el concepto, creando un archivo de anclaje haciendo el mismo trabajo. Creará el archivo de anclaje al iniciar y después periódicamente se asegurará que todavía exista. Cuando y si el archivo es eliminado, el Wrapper inmediatamente iniciará el proceso de apagado.

jvm 1    | ...
wrapper  | Archivo del anclaje eliminado. Apagando.
wrapper  | <-- El Wrapper se detuvo

En UNIX, si ha modificado el intérprete de comandos (shell) para ignorar señales del sistema este será el método que se usará para controlar el momento en el que el Wrapper deba ser apagado.

Compatibilidad :	3.2.0
Ediciones :
Plataformas :

El Wrapper puede ser configurado para buscar un archivo de comandos el cual puede contener un sin número de comandos que el Wrapper interpretará. La ubicación de este archivo puede especificarse usando la propiedad wrapper.commandfile, la cual esta inhabilitada por defecto.

Los comandos se emiten con la simple creación de un archivo de texto en el cual estará el comando presente. El archivo será borrado por el Wrapper tan pronto como se procese el comando.

STOP

jvm 1    | ...
wrapper  | Comando 'STOP'. Apagando el equipo con el código de salida 0.
jvm 1    | Deteniéndose...
wrapper  | <-- El Wrapper se detuvo

Si decide utilizar este método, es importante que se proteja el directorio donde el archivo de comandos esta localizado y asegurarse que sólo usuarios autorizados puedan asignar comandos cuando sea necesario.

Por favor revise la documentación de la propiedad wrapper.commandfile para una lista completa de comandos disponibles así como una serie de ejemplos.

Compatibilidad :	3.0.4
Ediciones :
Plataformas :

El Wrapper tiene incluido una clase opcional que habilita la conexión con cualquier cliente Telnet y remotamente controlar el Wrapper. Al usar este método es necesario que agrege a su aplicación unas cuantas líneas de código. Para una explicación completa de esta clase por favor visite javadocs WrapperActionServer.

Para configurar un simple servidor que le permita solo al cliente apagar el Wrapper, por favor agregue el siguiente código:

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

Acciones adicionales se pueden habilitar llamando a una lista de métodos apropiados que se encuentran en javadocs.

Una vez que sea configurado podrá conectarse con la aplicación usando el comando telnet localhost 9999. Cuando se contecte simplemente presione la tecla S y el Wrapper se apagará limpiamente. Esto puede ser un posible riesgo de seguridad por lo tanto, si decide usar este puerto asegúrese de protegerlo. También es posible enlazar el socket que escucha, a un host local evitando que interfiera con conexiones remotas.

Compatibilidad :	1.0.0
Ediciones :
Plataformas :

Como último resultado o como parte de sus pruebas tal vez desee forzar la eliminación del Wrapper. En Windows, puede hacerlo al abrir el Administrador de Tareas localizando el archivo wrapper.exe en la lengüeta de Procesos presionar Terminar Proceso. En UNIX, puede hacer lo mismo usando una variante de los comandos kill kill -9 {pid}. En los dos casos usted necesita ser cuidadoso de no terminar el proceso equivocado.

Cuando elimine el proceso del Wrapper de esta manera, será de manera inmediata y no tendrá la oportunidad de apagar la JVM limpiamente. El Wrapper está diseñado de tal manera que los componentes de Java inicien el proceso de apagado de Java automáticamente. Esto es crítico para evitar que la JVM se convierta en un proceso zombie, que sería difícil de controlar.

Cuando el Wrapper sea eliminado el archivo de registro de valores del Wrapper ya no registrará valores en ese momento. Después de este punto cualquier salida de datos que se genere en Java ya no será posible registrarlo.

Compatibilidad :	1.0.0
Ediciones :
Plataformas :

El proceso Java puede eliminarse casi de la misma manera como se hace con el proceso del Wrapper. Una vez más, esto normalmente no debería de hacerse excepto que sea parte de una serie de pruebas. Puede usar la propiedad wrapper.java.pidfile para solicitar que el Wrapper pueda proporcionar y escribir el ID del proceso del proceso Java.

Por defecto, cuando la JVM es eliminada de esta manera, el Wrapper asumirá que ha dejado de funcionar y reiniciará la aplicación en una JVM nueva.

jvm 1    | ...
wrapper  | JVM salió inesperadamente..
wrapper  | Iniciando JVM...
jvm 2    | WrapperManager: Initializing...
jvm 2    | ...

Si efectua una eliminación inmediata de esta manera, no habrá una oportunidad para que se ejecuten cualquiera de los ganchos de apagado, como resultado el apagado no será hecho de manera limpia.

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 pasa, la JVM iniciará su proceso de apagado normalmente incluyendo la ejecución de todos los ganchos de apagado registrados.

jvm 1    | ...
jvm 1    | Deteniéndose...
wrapper  | <-- El Wrapper se detuvo

El argumento para el método de salida, se utiliza para especificar un Código de Salida para la JVM. Los códigos de salida son útiles para ayudar a la aplicación que inició la JVM entender lo que pasó. El Wrapper es capaz de reconocer los diferentes códigos de salida y luego tomar distintas acciones en función a lo que se desee hacer. Para más información sobre esta propiedad por favor visite wrapper.on_exit.<n>.

Java también proporciona un Runtime.getRuntime().halt(0) y hace posible apagar la JVM sin ejecutar ninguno de los ganchos de apagado registrados. Si bien esto puede ser útil en algunos casos, no se recomienda su uso con el Wrapper ya que no tendrá manera de saber que la JVM se apagó intencionalmente. Cuando la JVM se apaga de esta manera, el Wrapper interpretará que la JVM ha dejado de funcionar o que se ejecutó una salida inesperada y como resultado reiniciará la JVM.

jvm 1    | ...
wrapper  | JVM salió inesperadamente.
wrapper  | Iniciando JVM...
jvm 2    | WrapperManager: Initializing...

Si en realidad necesita efectuar un apagado sin la ejecución de ganchos de apagado por favor usar el siguiente método WrapperManager.stopimmediate(0).

Compatibilidad :	1.0.0
Ediciones :
Plataformas :

Otro método es usar la API del Wrapper y llamar WrapperManager.stop(0). Cuando esto pasa, la JVM iniciará su proceso de apagado normalmente incluyendo la ejecución de todos los ganchos de apagado que esten registrados.

jvm 1    | ...
jvm 1    | Deteniéndose...
wrapper  | <-- El Wrapper se detuvo

Compatibilidad :	3.0.4
Ediciones :
Plataformas :

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

jvm 1    | ...
wrapper  | <-- El Wrapper se detuvo

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 un número 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 visitar 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 puede ser configurado totalmente en el archivo de Configuración del Wrapper.

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

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

jvm 1    | Creo que esta pasando algo...
wrapper  | Filtro desencadenado coincidio.  Apagando.
jvm 1    | Deteniéndose...
wrapper  | <-- El Wrapper se detuvo

También hay un gran número de otras funciones, además de filtros, que le permiten especificar una acción determinada y llevarla a cabo. 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