Descripción General: Directivas del Archivo de Configuración

El Wrapper define directivas especiales que se procesan a medida que se carga el archivo de configuración. Estas se categorizan en las siguientes secciones:

ADVERTENCIA

Antes de la versión 3.6.0 del Wrapper, las directivas solí­an escribirse comenzando con el carácter "#" en lugar de "@". Sin embargo, esto dificultaba distinguirlas de los comentarios, que también comienzan con el carácter "#".

Al utilizar una versión del Wrapper anterior a la 3.6.0, tenga en cuenta que debe reemplazar el carácter "@" en los siguientes ejemplos, y escribir siempre las directivas comenzando con un "#".

Al utilizar la versión 3.6.0 del Wrapper o posterior, la sintaxis antigua con "#" sigue siendo compatible por motivos de retrocompatibilidad. Sin embargo, el valor predeterminado y recomendado es escribir las directivas comenzando con un "@".

Codificación del Archivo de Configuración

A partir de la versión 3.5.0 del Wrapper, se hizo posible especificar la codificación de archivos de configuración individuales. La codificación más portátil es UTF-8, pero se admiten otras codificaciones en algunas plataformas.

La directiva de codificación debe especificarse en la primera lí­nea de un archivo de configuración. El Wrapper registrará una advertencia si a algún archivo le falta la directiva. Es posible especificar diferentes codificaciones en los archivos incluidos (estilo en cascada).

Ejemplo con UTF-8: 
@encoding=UTF-8

wrapper.debug=FALSE
...

Inclusión de Archivo de Configuración en Cascada

Es posible dividir una configuración en uno o más archivos de configuración opcionales y luego incluirlos desde el archivo principal. Consulte la página Archivo de Configuración en Cascada ("archivo incluido") para obtener más información.

Ejemplo: 
@include ../conf/wrapper-settings.conf

Modo de Inclusión

Por diseño, el Wrapper omitirá silenciosamente cualquier archivo incluido que no pueda ubicar o leer por cualquier motivo. Esto puede ser muy potente, ya que permite crear configuraciones especí­ficas para una plataforma u omitir opcionalmente valores de propiedades existentes.

Sin embargo, en algunos casos, se requiere un archivo incluido para el correcto funcionamiento de una aplicación. Este es particularmente el caso de los archivos seguros que contienen contraseñas o datos confidenciales. A partir de la versión 3.5.5 del Wrapper, es posible especificar una inclusión requerida, lo que provocará un error e impedirá que el Wrapper se inicie si falta dicho archivo.

Ejemplo: 
@include.required ../conf/wrapper-settings.conf

A partir de la versión 3.6.0 del Wrapper, es posible especificar si los archivos incluidos son opcionales o requeridos de forma predeterminada. Este modo de inclusión se puede configurar con la directiva @include.default_mode y se puede cambiar en cualquier lugar del archivo de configuración actual o de sus archivos incluidos.

Ejemplo: 
@include.default_mode=required

# These are required includes
@include ../conf/wrapper-settings1.conf
@include ../conf/wrapper-settings2.conf
@include ../conf/wrapper-settings3.conf

@include.default_mode=optional

# These are optional includes
@include ../conf/wrapper-additional-settings1.conf
@include ../conf/wrapper-additional-settings2.conf
@include ../conf/wrapper-additional-settings3.conf

@include.optional permite especificar un archivo incluido opcional cuando el modo de inclusión predeterminado es "required" (requerido).

Ejemplo: 
@include.default_mode=required

# This is a required include
@include ../conf/wrapper-settings.conf

# This is a optional include
@include.optional ../conf/wrapper-additional-settings.conf

Depuración de Archivos Incluidos

A partir de la versión 3.3.0 del Wrapper, es posible depurar la forma en que funciona la directiva @include viendo exactamente qué se incluye y qué no. Consulte la página Mensajes de depuración en el "archivo incluido" (estilo en cascada) para obtener más información.

Ejemplo: 
@include.debug

Declaración de Propiedades Finales
Compatibilidad :3.7.0
Ediciones :Edición ProfesionaEdición EstándarEdición de la Comunidad (No Compatible)
Plataformas :WindowsMac OSXLinuxAlpine LinuxFreeBSDSolarisIBM z/Linux

A partir de la versión 3.7.0 del Wrapper, puede crear secciones dentro de su archivo de configuración donde las propiedades (o definiciones de variables) se marcan como finales. Declarar una propiedad como final bloquea su valor, lo que evita que cualquier declaración posterior en el mismo archivo o en un archivo incluido lo sobrescriba.

Caso de Uso Práctico:

Divida su configuración en varios archivos incluidos. Almacene las propiedades crí­ticas de la aplicación en un archivo con permisos restrictivos y márquelas como finales. Almacene las propiedades secundarias en un archivo separado con permisos más amplios, permitiendo a los usuarios sobrescribirlas o modificarlas cuando sea necesario.

Sintaxis y Alcance:

Para iniciar una sección donde las propiedades se definen como finales, agregue @properties.final=TRUE en cualquier ubicación de su archivo de configuración.

Para volver al modo predeterminado donde las propiedades se pueden sobrescribir, use @properties.final=FALSE.

NOTA

Esta directiva solo afecta al archivo de configuración actual en el que se declara y no se propaga a los archivos incluidos.

Ejemplo de Declaración Final: 
# Start a final section to ensure the following properties will never be modified
@properties.final=TRUE

# Main class.
wrapper.java.mainclass=org.tanukisoftware.wrapper.test.Main

# Application parameters.
#  Pass parameters via the backend instead of the command line.
wrapper.app.parameter.backend=TRUE

#  Add parameters as needed starting from 1
wrapper.app.parameter.1=param1
wrapper.app.parameter.2=param2

# Back to normal mode
@properties.final=FALSE

ADVERTENCIA

Si se encuentran declaraciones finales duplicadas para la misma propiedad, el Wrapper considerará esto como una mala configuración y abortará el inicio para evitar un estado de configuración ambiguo.

Este comportamiento estricto también se aplica a las propiedades de la lí­nea de comandos. Debido a que las anulaciones desde la lí­nea de comandos se tratan inherentemente como finales, intentar sobrescribir una propiedad que ya ha sido marcada como final en el archivo de configuración causará un conflicto fatal.

En todos los casos, el Wrapper registrará un mensaje de error detallando el conflicto antes de detenerse.

Depuración de Propiedades

A partir de la versión 3.5.4 del Wrapper, es posible configurar el Wrapper para que emita un mensaje en el inicio cada vez que otra declaración sobrescriba una propiedad, o cuando no se pueda establecer una propiedad porque su valor es fijo.

La versión 3.5.27 del Wrapper mejora esta caracterí­stica. Ahora es posible controlar el nivel de registro de estos mensajes y especificar si el Wrapper debe cerrarse después de registrarlos. También puede aplicar diferentes configuraciones por secciones de sus archivos de configuración y, por lo tanto, permitir ser más o menos estricto en algunas partes. Esto se puede lograr mediante dos nuevas directivas:

Dependiendo de la naturaleza de las propiedades, el Wrapper emitirá diferentes mensajes. Estos mensajes se describen a continuación.

NOTA

Por defecto, estos mensajes solo se registran en el modo de depuración porque es una práctica común sobrescribir los valores de las propiedades mediante el uso opcional de un Archivo de Configuración en Cascada ("archivo incluido") u otros métodos.

ADVERTENCIA

Debido a que las propiedades wrapper.name y wrapper.displayname se definen en el script de shell de UNIX, si utiliza este script para iniciar el Wrapper y depura las propiedades mediante las directivas anteriores, es posible que reciba mensajes de advertencia, ya que esas variables también están definidas de forma predeterminada en el archivo de configuración.

Puede evitar estos mensajes eliminando las propiedades redundantes en el archivo de configuración o descomentando la lí­nea "#APP_NAME_PASS_TO_WRAPPER=false" en el archivo de script.

La segunda opción hará que el script ya no pase estos parámetros al Wrapper. Tenga cuidado de no desactivar las propiedades "APP_NAME" y "APP_LONG_NAME", que son necesarias para el correcto funcionamiento del script.

Mensajes

Para ayudar a comprender por qué una propiedad tiene un valor especí­fico, puede resultar útil visualizar cuándo se ha modificado su valor o, por el contrario, cuándo se ha ignorado a pesar de un intento de sobrescribirlo.

Estos son los mensajes que puede obtener:

Propiedades Superpuestas:

El Wrapper está configurado para que se utilice la última instancia definida de una propiedad especí­fica. Esto puede ser muy potente, ya que se pueden configurar valores predeterminados y luego hacer referencia a un archivo incluido opcional que podrí­a contener valores especí­ficos para un sistema.

Ejemplo de Redefinición de Propiedad: 
STATUS | wrapper  | The "foo.bar" property was redefined.
STATUS | wrapper  |   Old Value foo.bar=123 (on line #10 of configuration file: /home/wrapper/conf/wrapper.conf)
STATUS | wrapper  |   New Value foo.bar=XYZ (on line #12 of configuration file: /home/wrapper/conf/wrapper-custom.conf)

Propiedades de la lí­nea de comandos:

Los valores de las propiedades especificados en la lí­nea de comandos del Wrapper son "finales", lo que significa que no se pueden cambiar ni sobrescribir con valores del archivo de configuración. Esto es muy útil porque un usuario puede ejecutar el Wrapper con un valor de prueba sin tener que editar realmente el archivo de configuración.

Final Property Redefinition Example: 
STATUS | wrapper  | The "foo.bar" property is defined on the Wrapper command line and cannot be overwritten.
STATUS | wrapper  |   Fixed Value foo.bar=123
STATUS | wrapper  |   Ignored Value foo.bar=XYZ (on line #8 of configuration file: /home/wrapper/conf/wrapper.conf)

Variables de Entorno Internas:

El Wrapper también establece varias variables de entorno internas. Estas se realizan mediante el uso de propiedades finales. Si el archivo de configuración del usuario intenta establecer alguna de ellas, el Wrapper las ignorará y mantendrá los valores establecidos por el Wrapper.

Ejemplo de Redefinición de Propiedad Final: 
STATUS | wrapper  | The "set.WRAPPER_ARCH" property is defined by the Wrapper internally and cannot be overwritten.
STATUS | wrapper  |   Fixed Value set.WRAPPER_ARCH=x86
STATUS | wrapper  |   Ignored Value set.WRAPPER_ARCH=special (on line #10 of configuration file: /home/wrapper/conf/wrapper.conf)

@properties.on_overwrite.loglevel
Compatibilidad :3.5.27
Ediciones :Edición ProfesionaEdición EstándarEdición de la Comunidad
Plataformas :WindowsMac OSXLinuxAlpine LinuxFreeBSDSolarisIBM z/Linux

Esta directiva se utiliza para establecer el nivel de registro en el que se deben registrar los mensajes.

Los valores válidos incluyen:

  • AUTO: un valor predeterminado para resolver automáticamente el nivel de registro (ver a continuación).

  • NOTICE: para registrar en el nivel de registro NOTICE.

  • ADVICE: para registrar en el nivel de registro ADVICE.

  • FATAL: para registrar en el nivel de registro FATAL.

  • ERROR: para registrar en el nivel de registro ERROR.

  • WARN: para registrar en el nivel de registro WARN.

  • STATUS: para registrar en el nivel de registro STATUS.

  • INFO: para registrar en el nivel de registro INFO.

  • DEBUG: para registrar en el nivel de registro DEBUG.

El valor predeterminado es AUTO, que se resuelve como "WARN" (advertencia) siempre que se sobrescriba una propiedad dentro del mismo archivo de configuración o en un archivo con una profundidad de inclusión menor que la del archivo de la definición anterior. También se resuelve como "WARN" cuando se sobrescribe una propiedad final incrustada durante la personalización. En todos los demás casos, se resuelve como "DEBUG" (depuración).

NOTA

Antes de la versión 3.5.36, el valor predeterminado de esta directiva era DEBUG.

Ejemplo - registrar las propiedades sobrescritas en el nivel WARN (de advertencia): 
@properties.on_overwrite.loglevel=WARN

NOTA

El uso de la directiva #properties.debug ha quedado obsoleto a partir de la versión 3.5.27 del Wrapper en favor de estas nuevas directivas que ofrecen un control más preciso sobre la depuración de las propiedades. Por razones de retrocompatibilidad, #properties.debug tendrá el mismo efecto que @properties.on_overwrite.loglevel=STATUS.

@properties.on_overwrite.exit
Compatibilidad :3.5.27
Ediciones :Edición ProfesionaEdición EstándarEdición de la Comunidad
Plataformas :WindowsMac OSXLinuxAlpine LinuxFreeBSDSolarisIBM z/Linux

Esta directiva se utiliza para especificar si el Wrapper debe cerrarse si se sobrescribe alguna propiedad.

Los valores válidos incluyen:

  • TRUE: especifica que el Wrapper debe cerrarse si se sobrescribe cualquier propiedad que siga a esta directiva.

  • FALSE: especifica que el Wrapper no debe cerrarse si se sobrescribe cualquier propiedad que siga a esta directiva.

El valor predeterminado es FALSE.

Ejemplo (cerrar si se encuentra alguna propiedad sobrescrita): 
@properties.on_overwrite.exit=TRUE

Uso

Una directiva es válida desde la lí­nea donde se inserta en el archivo de configuración hasta el final del archivo o hasta que se encuentre una próxima directiva con el mismo nombre. Si se encuentra, el valor de la nueva directiva será válido para la siguiente sección en el archivo de configuración.

Cuando @properties.on_overwrite.exit se establece en TRUE, el valor de @properties.on_overwrite.loglevel se eleva automáticamente a FATAL (si estaba configurado en un nivel inferior). Esto se mantiene siempre y cuando @properties.on_overwrite.exit no se restablezca a FALSE.

Ejemplo: 
wrapper.name=@app.name@
wrapper.lang.folder=../lang
...

@properties.on_overwrite.loglevel=STATUS
wrapper.lang.folder=../../lang
...

@properties.on_overwrite.loglevel=INFO
wrapper.name=newAppName
...

@properties.on_overwrite.exit=TRUE
wrapper.app.parameter.3=start
...

wrapper.app.parameter.3=start_app
...

@properties.on_overwrite.exit=FALSE
...

En la configuración anterior, wrapper.lang.folder se registrará con un nivel "STATUS", wrapper.name se registrará con un nivel "INFO", y wrapper.app.parameter.3 se registrará en un nivel "FATAL", lo que provocará que el Wrapper se cierre. Cualquier propiedad que siga a "@properties.on_overwrite.exit=FALSE" no provocará el cierre del Wrapper y se registrará con un nivel "INFO", como se configuró anteriormente.

NOTA

A partir de la versión 3.5.27, el Wrapper también registrará mensajes si la lí­nea de comandos contiene propiedades duplicadas o intenta establecer una variable de entorno interna.

Aún puede usar @properties.on_overwrite.loglevel y @properties.on_overwrite.exit para controlar el nivel de registro en el que deben aparecer estos mensajes y especificar si el Wrapper debe cerrarse después de registrarlos. Si se configuran varias directivas en el archivo de configuración, se aplicará la última directiva de cada tipo.

Alternar la Expansión de Variables
Compatibilidad :3.5.55
Ediciones :Edición ProfesionaEdición EstándarEdición de la Comunidad
Plataformas :WindowsMac OSXLinuxAlpine LinuxFreeBSDSolarisIBM z/Linux

Cualquier valor de propiedad de configuración puede hacer referencia a variables con la siguiente sintaxis: %MYVAR%. Para obtener más detalles sobre cómo definir una variable y la lista de variables predefinidas, consulte esta página.

A partir de la versión 3.5.55 del Wrapper, es posible habilitar o deshabilitar la expansión de variables (es decir, el reemplazo de la notación sintáctica anterior por el valor de la variable) para secciones del archivo de configuración.

Por defecto (si no se utiliza esta directiva), la expansión de variables está habilitada. Puede deshabilitarla agregando "@variables.expand=FALSE" en cualquier lugar de su archivo de configuración. Las propiedades referenciadas en lí­neas posteriores no expandirán las variables. "@variables.expand=TRUE" le permite volver a habilitar la expansión de variables a partir de cierta lí­nea.

Ejemplo: 
set.MYVAR=some_value

@variables.expand=FALSE

# %MYVAR% will not be expanded
wrapper.app.parameter.1=%MYVAR% 

@variables.expand=TRUE

# %MYVAR% will be expanded to 'some_value'
wrapper.app.parameter.2=%MYVAR%

NOTA

La desactivación de la expansión de variables solo se aplica al archivo de configuración actual, y no a los archivos incluidos. Si se incluye un archivo después de que @variables.expand se establezca en FALSE, las variables referenciadas en el archivo incluido se expandirán, a menos que el archivo en sí­ también especifique @variables.expand=FALSE.

¿Por qué es útil?

En algunos casos, puede que necesite usar el carácter "%" en el valor de una propiedad. Cuando se hace referencia a este carácter dos veces en el mismo valor, se interpretarán como delimitadores de una variable, incluso si no tení­a la intención de referenciar una variable.

Ejemplo: (el siguiente valor generará la advertencia "The "20with" environment variable was referenced but has not been defined.") 
wrapper.app.parameter.1=http://url%20with%20spaces

Para solucionar este problema, una posibilidad es utilizar una variable especial %WRAPPER_PERCENTAGE% cuyo valor es un único carácter "%".

Ejemplo: (se expandirá a "http://url%20with%20spaces" sin generar ninguna advertencia) 
wrapper.app.parameter.1=http://url%WRAPPER_PERCENTAGE%20with%WRAPPER_PERCENTAGE%20spaces

Sin embargo, esto puede dificultar la lectura del valor, especialmente si el "%" se usa muchas veces.

@variables.expand ofrece una alternativa para deshabilitar completamente la expansión de variables si sabe que ciertas partes de su configuración no hacen referencia a ninguna variable y deberí­an usar el carácter "%" sin interpretarse como delimitadores de variables.

Referencia: Loglevel
  • wrapper.console.loglevel (1.0.0)

    Filtra los mensajes enviados a la consola de acuerdo con sus niveles de registro.

  • wrapper.logdialog.loglevel (3.3.1)

    Filtra los mensajes del diálogo de registros de acuerdo con sus niveles de registro.

  • wrapper.logfile.loglevel (2.2.5)

    Filtra los mensajes enviados al archivo de registro de acuerdo con sus niveles de registro.

  • wrapper.syslog.loglevel (2.2.5)

    Filtra los mensajes enviados al syslog (o al registro de eventos en Windows) de acuerdo con sus niveles de registro.