Iniciar y Controlar su Aplicación (Windows)

En Windows, es posible ejecutar una Aplicación Java ya sea como una aplicación de escritorio, o como un Servicio de Windows en segundo plano. En el caso de un Servicio, el Wrapper necesita poder ser instalado, removido, reiniciado, detenido, tener su estado consultado, etc. Dependiendo si la aplicación tiene una GUI o si el próposito es que sea ejecutada en una ventana de comandos, esto también determinará como debe ser ejecutada.

A seguir puede ver las diferentes formas de iniciar el Wrapper.

Archivos Batch Dedicados

En sistemas Windows, la manera más común de implementar el Wrapper es asegurarse de usar archivos batch dedicados para ejecutar cada acción para controlar el Wrapper. Esto hace posible que el usuario tan solo presione dos veces sobre los iconos de dichos archivos y/o configure enlaces en menús.

Configurar los Archivos Batch

En la carpeta %WRAPPER_HOME%\src\bin que viene en la distribución del Wrapper, podrá ver un número de plantillas de archivos batch que son usados para una tarea específica. (Otros archivos incluidos en el directorio también se encuentran disponibles en esta página.)

Cuando se configura el Wrapper para ejecutarlo con una aplicación en particular, puede escoger cual de los archivos batch anteriores es la mejor opción para su aplicación. Por ejemplo, si una aplicación no acepta/respalda que sea pausada, entonces los archivos PauseApp-NT.bat.in y ResumeApp-NT.bat.in no son necesarios.

Personalizar los Archivos Batch

NOTA

Dependiendo de como el archivo explorador esté configurado en su computadora, tal vez no sea posible ver las extensiones del archivo.

Para cada archivo requerido, simplemente copíelo directamente a la carpeta bin de su aplicación. Cuando lo haga, cambie el nombre del archivo reemplazando App con el nombre de su aplicación y remueva .in que se encuentra al final.

Ejemplo de Reemplazo del Nombre de Archivos:
App.bat.in             -> MyApp.bat
InstallApp-NT.bat.in   -> InstallMyApp-NT.bat
StartApp-NT.bat.in     -> StartMyApp-NT.bat
StopApp-NT.bat.in      -> StopMyApp-NT.bat
UninstallApp-NT.bat.in -> UninstallMyApp-NT.bat

Todos los archivos contienen una sección al inicio con variables que se pueden personalizar.

rem -----------------------------------------------------------------------------
rem These settings can be modified to fit the needs of your application
rem Optimized for use with version @wrapper.version@ of the Wrapper.

rem The base name for the Wrapper binary.
set _WRAPPER_BASE=wrapper

rem The directory where the Wrapper binary (.exe) file is located. It can be
rem  either an absolute or a relative path. If the path contains any special
rem  characters, please make sure to quote the variable.
set _WRAPPER_DIR=

rem The name and location of the Wrapper configuration file. This will be used
rem  if the user does not specify a configuration file as the first parameter to
rem  this script.
rem If a relative path is specified, please note that the location is based on the
rem location of the Wrapper executable.
set _WRAPPER_CONF_DEFAULT="../conf/%_WRAPPER_BASE%.conf"

rem Makes it possible to override the Wrapper configuration file by specifying it
rem  as the first parameter.
rem set _WRAPPER_CONF_OVERRIDE=true

rem _PASS_THROUGH controls how the script arguments should be passed to the
rem  Wrapper. Possible values are:
rem  - commented or 'false': the arguments will be ignored (not passed).
rem  - 'app_args' or 'true': the arguments will be passed through the Wrapper as
rem                          arguments for the Java Application.
rem  - 'both': both Wrapper properties and Application arguments can be passed to
rem            the Wrapper. The Wrapper properties come in first position. The
rem            user can optionally add a '--' separator followed by application
rem            arguments.
rem NOTE - If _WRAPPER_CONF_OVERRIDE is set to true the above applies to arguments
rem        starting with the second, otherwise it applies to all arguments.
rem set _PASS_THROUGH=app_args

rem Do not modify anything beyond this point
rem -----------------------------------------------------------------------------

Ejecutar en una Consola

Iniciar la aplicación

Ejecutar la aplicación en la ventana de comandos (Command Window) de una consola es posible al presionar dos veces sobre el archivo batch MyApp.bat> desde el explorador de archivos. Otra opción es abrir la ventana de comandos y ejecutarel archivo batch desde el símbolo del sistema (Command prompt). Debido a la manera en la que el archivo de órdenes del Wrapper configura su propio directorio, no es necesario ejecutar este archivo batch desde el directorio bin.

Ejemplo de Salida de Datos:
MyApp.bat
wrapper  | --> Wrapper Started as Console
wrapper  | Java Service Wrapper Professional Edition 64-bit {version}
wrapper  |   Copyright (C) 1999-{year} Tanuki Software, Ltd. All Rights Reserved.
wrapper  |     https://wrapper.tanukisoftware.com
wrapper  |   Licensed to {licensee}
wrapper  |
wrapper  | Launching a JVM...
jvm 1    | WrapperManager: Initializing...

Detener la aplicación

La aplicación puede ser terminada al presionar CTRL-C en la consola (ventana de comandos). Esto hará con que el Wrapper apague la aplicación limpiamente. Por favor visite la página para más opciones sobre como detener una aplicación de consola.

Ejecutar como un Servicio de Windows

NOTA

Antes de continuar, asegúrese que ha configurado todas las propiedades relacionadas con el Servicio de Windows en el archivo wrapper.conf. También debe verificar que la aplicación está ejecutándose correctamente en modo consola.

Instalar como un Servicio de Windows

La aplicación puede ser instalada como un servicio al presionar dos veces sobre el archivo batch InstallMyApp-NT.bat desde el explorador de archivos. También lo puede hacer al abrir la ventana de comandos y después ejecutar el script instalado desde el símbolo del sistema. Si el servicio es instalado exitosamente el script finalizará inmediatamente.

Si hay algún problema, entonces un mensaje de error describiendo lo que sucedió se mostrará. El script esperará a que el usuario presione una tecla antes de finalizar.

Ejemplo de Comando y Salida de Datos:
InstallMyApp-NT.bat
wrapper  | My Application service installed.

Iniciar y Detener el Servicio de Windows

El servicio ahora puede ser iniciado y detenido usando los archivos batch respectivos.

Ejemplo de Comando y Salida de Datos:
StartMyApp-NT.bat
wrapper  | Starting the My Application service...
wrapper  | My Application started.
StopMyApp-NT.bat
wrapper  | Stopping the My Application service...
wrapper  | My Application stopped.

Como el servicio es un Servicio de Windows normal, también lo puede iniciar y detener desde el Panel de Control de Servicios en Windows ([Panel de Control] - [Sistema y seguridad] - [Herramientas administrativas] - [Servicios]), seleccionando el servicio y después presionando "Iniciar".

Además, el servicio puede ser controlado usando los comandos net start MyApp y net stop MyApp.

Ejemplo de Comando y Salida de Datos:
net start MyApp
The My Application service is starting....
The My Application service was started successfully.
net stop MyApp
The My Application service is stopping..
The My Application service was stopped successfully.

NOTA

Los comandos net start x y net stop x tienen problemas con los servicios que se tardan para iniciar o detenerse. En la mayoría de los casos funcionarán, pero si el servicio se tarda aún por segundos para detenerse el comando net stop x notificará que el servicio fue detenido aún si se encuentra en el proceso de detenerse. Esto puede generar problemas cuando el script tenga que esperar hasta que el servicio en realidad se haya detenido antes de poder continuar. Al hacer uso del Wrapper para iniciar y detener el servicio, le garantizamos que no tendrá problema alguno.

El método del Wrapper para iniciar y detener el servicio también es de gran ayuda al usar scripts. Así, ya no se necesita que el nombre real del servicio instalado esté presente en ningun otro lugar, excepto en el archivo wrapper.conf. Por esta razón, no hay necesidad de editar manualmente multiples archivos si el nombre del servicio llega a cambiar.

Si la propiedad wrapper.ntservice.starttype es configurada a AUTO_START, el servicio se iniciará todas las veces que la máquina se reinicie.

Desinstalar (remover) como Servicio de Windows

El servicio puede ser removido al ejecutar el archivo batch UninstallMyApp-NT.bat. Si se encuentra en ejecución, éste se detendrá antes de ser removido.

Comando y Ejemplo de Salida de Datos:
UninstallMyApp-NT.bat
wrapper  | Service is running.  Stopping it...
wrapper  | Waiting to stop...
wrapper  | My Application stopped.
wrapper  | My Application service removed.

Archivo Batch Basado en Comandos

Algunas aplicaciones conectadas al puerto desde sistemas operativos basados en UNIX podrán trabajar mejor con un comando de archivo de órdenes estilo UNIX para controlar el servicio. El archivo batch basado en comandos combina todas las funcionalidades individuales de los archivos batch especializados en un solo archivo, el cual hace uso de un comando como parámetro.

Configuración de Archivos Batch

En la carpeta %WRAPPER_HOME%\src\bin que viene en la distribución del Wrapper, podrá ver una plantilla de archivos batch, AppCommand.bat.in.

Copie este archivo en la carpeta bin de su aplicación. Cuando lo haga, cambie el nombre del archivo reemplazando App con el nombre de su aplicación y remueva .in que se encuentra al final.

Ejemplo de Reemplazo de Nombre de Archivos:
MyServerCommand.bat.in             -> MyServerCommand.bat
MyServer.bat.in   -> MyServer.bat

Todos los archivos contienen una sección al inicio que puede ser personalizada para poder agregar el nombre del archivo y la estructura del directorio de su aplicación.

Bloque de configuración de Script:
rem -----------------------------------------------------------------------------
rem These settings can be modified to fit the needs of your application
rem Optimized for use with version @wrapper.version@ of the Wrapper.

rem The base name for the Wrapper binary.
set _WRAPPER_BASE=wrapper

rem The name and location of the Wrapper configuration file.
rem  (Do not remove quotes.)
set _WRAPPER_CONF="../conf/wrapper.conf"

rem _FIXED_COMMAND tells the script to use a hard coded command rather than
rem  expecting the first parameter of the command line to be the command.
rem  By default the command will will be expected to be the first parameter.
rem set _FIXED_COMMAND=console

rem _PASS_THROUGH tells the script to pass all parameters through to the JVM
rem  as is.  If _FIXED_COMMAND is specified then all parameters will be passed.
rem  If not set then all parameters starting with the second will be passed.
set _PASS_THROUGH=true

rem Do not modify anything beyond this point
rem -----------------------------------------------------------------------------

Ejecución de Archivo Script

El archivo batch basado en comandos es autodocumentado, y si el usuario trata de ejecutarlo sin parámetros, el script desplegará su uso.

Uso con _PASS_THROUGH habilitado:
Usage: TestWrapperCommand [ console {JavaAppArgs} : start : stop : restart : pause : resume : status : permissions : privileges : install {JavaAppArgs} : installstart {JavaAppArgs} : update {JavaAppArgs} : remove : setup : teardown ]

Commands:
  console      Launch in the current console.
  start        Start the Service.
  stop         Stop the Service.
  restart      Stop the Service if running and then start.
  pause        Pause the Service if running.
  resume       Resume the Service if paused.
  status       Query the current status of the Service.
  permissions  Query the current permissions of the Service.
  privileges   Query the current privileges of the Service.
  install      Install the Service.
  installstart Install the Service and then start running it.
  update       Update an installed Service.
  remove       Uninstall the Service.
  setup        Setup the Wrapper (for registration to the Windows Event Log).
  teardown     Teardown the Wrapper (unregister from the Windows Event Log).

JavaAppArgs:
  Optional arguments which will be passed to the Java application.
Uso con _PASS_THROUGH deshabilitado:
Usage: TestWrapperCommand [ console : start : stop : restart : pause : resume : status : permissions : privileges : install : installstart : update : remove : setup : teardown ]

...

Hay ciertas diferencias entre el archivo batch para Windows y el script de UNIX. El script de UNIX puede ser usado para detener el Wrapper ejecutado en una consola; sin embargo, no es posible hacerlo con los archivos batch en Windows. Además, el comando dump no existe en el archivo batch en Windows.

Como puede ver, el archivo batch basado en comandos proporciona una amplia gama de funciones:

Por ejemplo, el Wrapper puede ser iniciado en una consola usando el siguiente comando:

MyApp.bat console
wrapper  | --> Wrapper Started as Console
wrapper  | Java Service Wrapper Professional Edition 64-bit {version}
wrapper  |   Copyright (C) 1999-{year} Tanuki Software, Ltd. All Rights Reserved.
wrapper  |     https://wrapper.tanukisoftware.com
wrapper  |   Licensed to {licensee}
wrapper  |
wrapper  | Launching a JVM...
jvm 1    | WrapperManager: Initializing...

Para ejecutar otros comandos, simplemente se reemplaza el comando de la "consola" con el comando que desea ejecutar.

Binario Independiente

El Java Service Wrapper también puede ser ejecutado directamente sin usar el archivo batch.

Uso del Wrapper

Si el wrapper ejecutable es lanzado sin parámetros o con "-?", la siguiente salida de datos se mostrará.

Uso del Wrapper:
Java Service Wrapper Professional Edition 64-bit {version}
  Copyright (C) 1999-{year} Tanuki Software, Ltd. All Rights Reserved.
    https://wrapper.tanukisoftware.com

Usage:
  bin\wrapper <command> <configuration file> [configuration properties] [...]
  bin\wrapper <configuration file> [configuration properties] [...]
     (<command> implicitly '-c')
  bin\wrapper <command>
     (<configuration file> implicitly 'wrapper.conf')
  bin\wrapper
     (<command> implicitly '-c' and <configuration file> 'wrapper.conf')
  bin\wrapper --customize [customize arguments]

where <command> can be one of:
  -c  --console run as a Console application
  -su --setup   SetUp the wrapper
  -td --teardown TearDown the wrapper
  -t  --start   starT an NT service
  -a  --pause   pAuse a started NT service
  -e  --resume  rEsume a paused NT service
  -p  --stop    stoP a running NT service
  -i  --install Install as an NT service
  -it --installstart Install and sTart as an NT service
  -u  --update Update an installed NT service
  -r  --remove  Uninstall/Remove as an NT service
  -l=<code> --controlcode=<code> send a user controL Code to a running NT service
  -d  --dump    request a thread Dump
  -q  --query   Query the current status of the service
  -qs --querysilent Silently Query the current status of the service
  -h  --hostid  prints a list of HostIds which can be used to license this host.
  -v  --version print the wrapper's version information.
  -?  --help    print this help message
  -- <args>     mark the end of Wrapper arguments.  All arguments after the
                '--' will be passed through unmodified to the java application.

<configuration file> is the wrapper.conf to use.  Name must be absolute or relative
  to the location of bin\wrapper

[configuration properties] are configuration name-value pairs which override values
  in wrapper.conf.  For example:
  wrapper.debug=true

  --customize  This command will allow you to customize your Wrapper executable.
    The following [customize arguments] are available:
      --target <target file> Specifies the name and location of the customized
          Wrapper executable.  This property is mandatory as it is not possible
          or safe to guess a default file name.
      --icon <icon file> Specifies the custom icon for your Wrapper executable.
      --passthrough If set, the new Wrapper executable will precede the
                    whole command line to the wrapped application.
      --conf <conf file> Specifies the default location of the conf file
      --manufacturer <Manufacturer> Sets the Manufacturer for the binary

  Please note that any file references must be absolute or relative to the location
  of the Wrapper executable.]

Iniciar la Aplicación

Para ejecutar el Wrapper como una aplicación de consola, deberá especificar el comando -c, seguido del archivo wrapper.conf. La ubicación del archivo wrapper.conf puede ser absoluto o relativo. Si una ruta relativa es usada, dicha ruta será siempre relativa a la ubicación del archivo wrapper.exe y no a la del directorio actual.

Ejemplo de Comando:
wrapper.exe -c ..\conf\wrapper.conf

Instalar la Aplicación como un Servicio

Para instalar la aplicación como un Servicio de Windows, ejecute:

Ejemplo de Comando:
wrapper.exe -i ..\conf\wrapper.conf

Iniciar la Aplicación como un Servicio

Una vez instalado, el servicio puede ser iniciado como cualquier otro Servicio de Windows. Si wrapper.ntservice.starttype fue configurado a AUTO_START cuando fue instalado, entonces el servicio será iniciado la próxima vez que la máquina sea reiniciada. Es posible iniciar el servicio desde el Panel de Control de Servicios ([Panel de Control] - [Sistema y seguridad] - [Herramientas administrativas] - [Servicios]) en Windows al seleccionar el servicio y presionar el botón "Iniciar" o haciendo uso de uno de los siguientes comandos:

Ejemplo de Comando:
wrapper.exe -t ..\conf\wrapper.conf
net start MyApp

NOTA

Los comandos net start x y net stop x tienen problemas con los servicios que se tardan para iniciar y detenerse. En la mayoría de los casos funcionarán, pero si el servicio se tarda aún por segundos para detenerse, el comando net stop x notificará que el servicio fue detenido aún si se encuentra en el proceso de detenerse. Esto puede generar problemas cuando el script tenga que esperar hasta que el servicio en realidad se haya detenido antes de poder continuar. Al hacer uso del Wrapper para iniciar y detener el servicio, le garantizamos que no tendrá problema alguno.

El método del Wrapper para iniciar y detener el servicio también es útil en scripts, ya que no necesita que el nombre real del servicio instalado esté presente en ningun lugar excepto en el archivo wrapper.conf. Por esta razón, no hay necesidad de editar manualmente multiples archivos si el nombre del servicio llega a cambiar.

Detener la Aplicación como un Servicio

El servicio puede ser detenido usando el Panel de Control de Servicios en Windows ([Panel de Control] - [Sistema y seguridad] - [Herramientas administrativas] - [Servicios]), seleccionando el servicio y después presionando "Iniciar", o con uno de los comandos a seguir:

Ejemplo de Comando:
wrapper.exe -p ..\conf\wrapper.conf
net stop MyApp

Desinstalar la Aplicación como un Servicio

Para desinstalar la aplicación como un Servicio de Windows, ejecute el siguiente comando:

Ejemplo de Comando:
wrapper.exe -r ..\conf\wrapper.conf

Si el servicio está en ejecución a la hora que está siendo desinstalado, el servicio será detenido limpiamente para después ser removido.

Consultar el Estado de la Aplicación como un Servicio

El Wrapper puede ser usado para consultar el estado del servicio manualmente o desde el archivo batch. Esto puede ser útil para Install Scripts que necesiten saber el estado actual de la configuración del servicio.

Ejemplo de Comando y Salida de Datos:
wrapper.exe -q ..\conf\wrapper.conf
wrapper  | The My Application Service is installed.
wrapper  |   Start Type: Automatic
wrapper  |   Interactive: Yes
wrapper  |   Running: No

Si se ejecuta con el comando "-q", el Wrapper desplegará el estatus actual a la consola y el comando "-qs" se ejecutará silenciosamente. El Wrapper saldrá con un código de salida el cual es una combinación de los siguientes bits:

Un código de salida "15" (=1+2+4+8), por ejemplo, indica que el servicio está instalado, en ejecución, interactuando y configurado para iniciar automáticamente cuando el sistema sea reiniciado. Un código de salida "0" (zero) significa que el servicio no está instalado.

Referencia: Iniciar su Aplicación con el Wrapper