Archivo de manifiesto de característica de Liberty

Una característica de Liberty consta de un archivo de manifiesto de característica y una colección de uno o varios paquetes OSGi que proporcionan clases y servicios que corresponden a una prestación en particular del entorno de ejecución del perfil Liberty. Puede encontrar la introducción del formato de un manifiesto de característica y el significado de cada cabecera en el archivo de manifiesto.

El archivo de manifiesto de característica del perfil Liberty utiliza el formato de metadatos del servicio de subsistema en la especificación OSGi Enterprise R5. Una característica se define mediante un archivo de manifiesto (archivo .mf) que se almacena en el directorio lib/features y debe utilizar un tipo personalizado de subsistema: osgi.subsystem.feature. Para obtener más información sobre la sintaxis de manifiesto OSGi, consulte la sección 1.3.2 de la especificación principal OSGi.

Nota: En el archivo de manifiesto de característica, los atributos adoptan la forma nombre=valor, pero las directivas adoptan la forma nombre:=valor.

Se definen las siguientes cabeceras:
Tabla 1. Cabeceras de un archivo de manifiesto de característica .

En esta tabla se muestran las cabeceras de un archivo de manifiesto de una característica en el perfil Liberty. La primera columna muestra una lista de cabeceras, la segunda columna muestra la descripción de cada cabecera y la tercera columna establece si es necesaria la cabecera.

Cabecera Descripción ¿Es obligatorio?
Subsystem-ManifestVersion El formato de la versión del archivo de manifiesto de característica. Debe establecerse en 1. No
Subsystem-SymbolicName El nombre simbólico de la característica y los atributos o directivas.
Subsystem-Version La versión de la característica. Consulte la sección 3.2.5 de la especificación principal de OSGi para ver los detalles de cómo se define. No
Subsystem-Type El tipo de subsistema de la característica. Todas las características son actualmente del mismo tipo de subsistema: osgi.subsystem.feature.
Subsystem-Content El contenido de subsistema de la característica. Es una lista separada por comas de paquetes y subsistemas que son necesarios para ejecutar esta característica. Si desea permitir que se configure la característica automática en el archivo server.xml, debe tener la cabecera de capacidad que contiene las características necesarias, que además deben estar definidas en el contenido del subsistema.
Subsytem-Localization La ubicación de los archivos de localización de la característica. No
Subsystem-Name Un nombre abreviado, legible para los usuarios, de la característica. Este valor se puede localizar. No
Subsystem-Description Descripción de la característica. Este valor se puede localizar. No
IBM-Feature-Version La versión de este tipo de subsistema. Debe establecerse en 2.
IBM-Provision-Capability La cabecera de capacidad que describe si una característica puede suministrarse automáticamente. No
IBM-API-Package Los paquetes de API que esta característica expone a las aplicaciones, las características de otras extensiones del producto y el kernel de Liberty. No
IBM-API-Service Los servicios OSGi que expone esta característica a las aplicaciones OSGi. No
IBM-SPI-Package Los paquetes de SPI que esta característica expone a las características de otras extensiones del producto y el kernel de Liberty. No
IBM-ShortName Nombre abreviado de la característica. No
IBM-AppliesTo Versión de Liberty a la que se aplica esta característica. No
Subsystem-License Tipo de licencia de esta característica. No
IBM-License-Agreement Prefijo de la ubicación de los archivos del acuerdo de licencia. No
IBM-License-Information Prefijo de la ubicación de los archivos de información de la licencia. No
IBM-App-ForceRestart Especifica que las aplicaciones se van a reiniciar cuando se instale o se desinstale la característica en un servidor en ejecución. No

Subsystem-SymbolicName

La sintaxis de esta cabecera coincide con la sintaxis de Bundle-SymbolicName para un paquete. Tiene un nombre simbólico que sigue la sintaxis de estilo de nombres de paquete y, opcionalmente puede utilizar un conjunto de atributos y directivas.

Se da soporte a los siguientes atributos:
  • superseded. Este atributo indica si esta característica está reemplazada por una o varias características o uno o varios elementos de funcionalidad. Tiene uno de los valores siguientes:
    • true: la característica está reemplazada.
    • false: la característica no está reemplazada.
    Este atributo es opcional; el valor predeterminado es false.

    Para obtener más información, consulte Características reemplazadas.

  • superseded-by. Este atributo especifica una lista separada por comas de las características que reemplazan a esta característica, si hay alguna, y es opcional.
Se admite la directiva siguiente:
  • visibility. Esta directiva toma uno de los valores siguientes:
    • public: característica que se considera que es API. Las herramientas del desarrollador admiten la característica, para utilizarla en el archivo server.xml y en la salida de los mensajes.
    • protected: se considera que la característica es SPI. Las herramientas del desarrollador no admiten la característica, para utilizarla en el archivo server.xml ni en la salida de los mensajes. Se incluye la característica de modo que los extensores puedan utilizarla para crear características de nivel superior.
    • private: (valor predeterminado), la característica es interna al producto. No se admite la característica para utilizarla en el archivo server.xml ni para que las características de extensor hagan referencia a ella. La característica se puede cambiar en cualquier momento, incluso entre fixpacks.
Por ejemplo:
Subsystem-SymbolicName: com.ibm.example.feature-1.0; 
    visibility:=public; superseded=true; superseded-by="com.ibm.example.feature-2.0"
Si un nombre de característica de la lista superseded-by va encerrada entre corchetes, [], esta característica se ha separado de la característica que la reemplaza. En el ejemplo siguiente, la característica appSecurity-1.0, que contiene las características servlet-3.0 y ldapRegistry-3.0, se reemplaza por la característica appSecurity-2.0, que no contiene las características servlet-3.0 y ldapRegistry-3.0:
IBM-ShortName: appSecurity-1.0
Subsystem-SymbolicName: com.ibm.websphere.appserver.appSecurity-1.0; visibility:=public;
superseded=true; superseded-by="appSecurity-2.0, [servlet-3.0], [ldapRegistry-3.0]"
Para obtener más información, consulte Características separadas.
Procedimientos recomendados: Si las herramientas del desarrollador deben mostrar la característica, debe ser public. Si la característica está disponible sólo para partes de confianza, debe ser protected. Si la característica es interna y está sujeta a cambios en cualquier momento, debe ser private.

Subsystem-Content

Esta cabecera define el contenido de la característica, para el tiempo de ejecución y para la instalación. Sigue la misma sintaxis de cabecera que la especificación Subsystem con la sintaxis siguiente:
Subsystem-Content ::= content ( ',' content )*
        content ::= unique-name ( ';' parameter )*
        unique-name ::= unique-name        (see OSGi core spec section 1.3.2)
unique-name utiliza el formato de las cabeceras Bundle-SymbolicName o Subsystem-SymbolicName. Se da soporte a los siguientes atributos:
  • version: el rango de versiones que deben coincidir cuando se busca un paquete. Sólo se seleccionan los paquetes en este rango. Un ejemplo típico del rango de versiones es [1,1.0.100).
  • type: el tipo de contenido que se suministra. Puede especificar cualquier valor para indicar el tipo de contenido; algunos tipos darán como resultado paquetes instalados e iniciados en la entorno OSGi de un servidor que utiliza la característica, todos los tipos harán que se incluya el contenido en un paquete de instalación que incluye la característica. Los valores siguientes están predefinidos:
    • osgi.bundle: se trata del valor predeterminado e indica un paquete OSGi que se debe suministrar en el entorno OSGi del servidor y en un paquete de instalación.
    • osgi.subsystem.feature: este valor indica que se debe suministrar la característica en el entorno OSGi del servidor y en un paquete de instalación. Estas características tienen que utilizar el nombre especificado en la cabecera Subsystem-SymbolicName.
    • jar: este valor indica que se debe incluir un archivo JAR en un paquete de instalación y que se puede seleccionar mediante una combinación de un rango de versión o un valor de ubicación.
    • file: este valor indica que el archivo identificado en el atributo location se debe incluir en un paquete de instalación.
Se admiten las siguientes directivas:
  • location: la ubicación del paquete. En el caso de tipo JAR o paquete, este valor puede ser una lista separada por comas de directorios que se utiliza para identificar los paquetes de API y especificaciones en el directorio dev, o una sola entrada apuntando directamente al archivo JAR. Cuando type es file, sólo se permite una única entrada y debe apuntar directamente a dicho archivo.
  • start-phase: la fase de inicio en la que el paquete debe iniciarse durante el arranque del sistema. La directiva start-phase puede tener uno de los valores siguientes:
    • SERVICE: este valor indica la primera fase. De forma predeterminada, se correlaciona con un nivel de inicio de 9.
    • CONTAINER: este es el valor predeterminado si no se proporciona ningún atributo start-fase. Indica la fase del contenedor en la que se inician los contenedores de aplicaciones. De forma predeterminada, se correlaciona con un nivel de inicio de 12.
    • APPLICATION: este valor indica la última fase en la que se inician las aplicaciones.
    Los paquetes también pueden definirse para que se inicien justo antes o después de estas fases añadiendo _LATE para ser posteriores o _EARLY para ser anteriores a la fase clave. Por lo tanto, si desea que se ejecuten inmediatamente después de la fase de contenedor, utilice CONTAINER_LATE, y si desea que se ejecuten antes de la fase de APPLICATION, utilice APPLICATION_EARLY.
Por ejemplo:
Subsystem-Content: com.ibm.websphere.appserver.api.basics; version="[1,1.0.100)"; type=jar; location:="dev/api/ibm/,lib/",
                   com.ibm.websphere.appserver.spi.application; 
				   				   location:="dev/spi/ibm/com.ibm.websphere.appserver.spi.application_1.0.0.jar"; type="jar",
                   com.ibm.websphere.appserver.spi.application_1.0.0-javadoc.zip;
				   				   location:="dev/spi/ibm/javadoc/com.ibm.websphere.appserver.spi.application_1.0.0-javadoc.zip"; type="file"
Para plataformas AIXPara plataformas HP-UXPara plataformas LINUXPara plataformas SolarisPara plataformas i de IBMRepositorio de Liberty[8.5.5.4 o posterior]La siguiente directiva se admite en la versión 8.5.5.4 y posterior:
  • ibm.executable - Añade el permiso de ejecución al archivo asociado, según el valor actual de umask, cuando el valor se establece en "true". Cualquier otro valor implicará que no se emprenda ninguna acción. En la tabla siguiente se muestra el valor actual de umask y la clase que obtiene el permiso de ejecución.
    Tabla 2. Ejemplos de valores de umask y clases con permisos de ejecución establecidos mediante ibm.executable
    Umask Permisos de ejecución otorgados a la clase
    022 propietario, grupo, otras
    023 propietario, grupo
    055 propietario

Subsytem-Localization

Esta cabecera especifica la ubicación de los archivos de localización de la característica.

Por ejemplo:
Subsystem-Localization: OSGI-INF/l10n/loc

Subsystem-Name

Utilice esta cabecera para suministrar un nombre abreviado, legible para el usuario, de la característica. Puede especificar una serie literal o un nombre de propiedad. Si especifica un nombre de propiedad, se puede localizar el valor.

Por ejemplo
Subsystem-Name: %name
donde el valor de name se define en un archivo de propiedades en la ubicación especificada en la cabecera Subsytem-Localization (loc.properties en el ejemplo anterior), con el formato siguiente:
name=nombre_característica 

Subsystem-Description

Utilice esta cabecera para proporcionar una descripción de la característica. Puede especificar una serie literal o un nombre de propiedad. Si especifica un nombre de propiedad, se puede localizar el valor.

Por ejemplo
Subsystem-Description: %desc
donde el valor de desc se define en un archivo de propiedades en la ubicación especificada en la cabecera Subsytem-Localization (loc.properties en el ejemplo anterior), con el formato siguiente:
desc=descripción_característica

IBM-Provision-Capability

Las características suministradas automáticamente son características que tienen la cabecera IBM-Provision-Capability en el manifiesto. Esta cabecera describe otras características que deben ser suministrados para que esta característica se suministre automáticamente. Al enumerar las demás características, utilice la cabecera Subsystem-SymbolicName de la característica. Cuando se configuran características en el archivo server.xml, runtime comprueba si se han cumplido las capacidades de las características de suministro automático y, en caso afirmativo, se suministran de forma automática.

El formato de la cabecera IBM-Provision-Capability utiliza filtros LDAP de OSGi estándar.

IBM-API-Package

Esta cabecera se utiliza para indicar qué paquetes de API están visibles para las aplicaciones. Se coincide con la sintaxis de la cabecera Export-Package. Esto significa que es una lista separada por comas de paquetes de API, pero cada paquete de API puede tener varios atributos.

Se admite el atributo siguiente:
  • type: el tipo de paquete de API. El atributo type puede tener uno de los valores siguientes:
    • spec: indica una API proporcionada por un cuerpo estándar como, por ejemplo, javax.servlet o org.osgi.framework.
    • ibm-api: indica una API de valor añadido proporcionada por IBM®.
    • api: indica una API definida por el usuario. Éste es el valor predeterminado.
    • third-party: indica una API que está visible, pero no está controlada por IBM. Normalmente, son paquetes de código abierto.
    • internal: indica paquetes que no son de API que se deben exponer a las aplicaciones para que funcionen. Puede utilizarse si se ha mejorado, o entramado, el código de bytes del código Java™ para añadir referencias al código interno en el tiempo de ejecución.
Por ejemplo:
IBM-API-Package: javax.servlet; type="spec",
                 com.ibm.websphere.servlet.session; type="ibm-api",
                 com.ibm.wsspi.webcontainer.annotation; type="internal"

IBM-API-Service

Esta cabecera se utiliza para indicar qué servicios de la característica están visibles para las aplicaciones OSGi. La característica debe registrar también el servicio en el registro de servicios OSGi.

Tiene la siguiente sintaxis:
IBM-API-Service ::= service ( ',' service )*
                    service ::= service-name ( ';' attribute )*
                    service-name ::= unique-name
service-name es la clase Java o el nombre de interfaz del servicio. Los atributos se interpretan como las propiedades de servicio de los servicios.
Por ejemplo:
IBM-API-Service: com.ibm.example.service.FeatureServiceOne; 
                 myServiceAttribute=myAttributeValue,
                 com.ibm.example.service.FeatureServiceTwo

Si una aplicación OSGi desea utilizar los servicios proporcionados por la cabecera IBM-API-Service, la aplicación debe incluir una referencia Blueprint al servicio para que el servicio se suministre a la aplicación.

Por ejemplo:
<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
		<reference id="FeatureServiceOneRef"
						interface="com.ibm.example.service.FeatureServiceOne" />
</blueprint>

Para que un paquete de una aplicación OSGi pueda utilizar un servicio, el paquete de la interfaz debe estar disponible para dicho paquete, lo que significa que el paquete de interfaz debe especificarse mediante una cabecera Import-Package en el archivo de manifiesto del paquete de consumo. El paquete de interfaz también debe especificarse mediante una cabecera Export-Package en un paquete de características y especificarse en la cabecera IBM-API-Package del archivo de manifiesto de la característica. El servicio proporcionado por una característica debe registrarse en el registro de servicios OSGi utilizando la interfaz BundleContext OSGi o cualquier otro mecanismo como Blueprint o los servicios declarativos. Para obtener más información, consulte los apartados Desarrollo de un paquete OSGi con la activación simple y Composición de características avanzadas utilizando servicios declarativos de OSGi.

IBM-SPI-Package

Cuando cree su propia característica de Liberty, instálela en la extensión del producto del usuario. Cualquier otra característica que esté instalada en la extensión del producto del usuario podrá acceder a todos los paquetes de su característica. No obstante, si desea que una característica que está instalada en otra extensión de producto acceda a un paquete en su característica, debe listar el nombre de paquete en la cabecera IBM-SPI-Package.

Los paquetes listados en la cabecera IBM-SPI-Package deben estar exportados por un paquete en la característica de Liberty, y aparecer en la lista de la cabecera Export-Package del archivo de manifiesto del paquete.

IBM-ShortName

Esta cabecera es un nombre abreviado de una característica que puede utilizar para especificar una característica en el archivo server.xml. Si no hay ninguna cabecera IBM-ShortName en el archivo de manifiesto, se utiliza Subsystem-SymbolicName de forma predeterminada. La cabecera IBM-ShortName solo es válida para las características públicas.

IBM-AppliesTo

Esta cabecera especifica la versión de Liberty a la que se aplica esta característica. Proporcione una lista de elementos separados por comas, cada uno en la forma siguiente:
ID_producto; productVersion=versión_producto; productInstallType=tipo_instalación_producto; productEdition=ediciones_producto

Si proporciona más de un elemento, el valor de ID_producto debe ser distinto para cada uno.

El valor de ediciones_producto puede ser una edición única o una lista de ediciones separadas por comas encerrada entre comillas.

Por ejemplo:
IBM-AppliesTo: com.ibm.websphere.appserver; productVersion=8.5.5; productInstallType=Archive; productEdition="BASE,DEVELOPERS,EXPRESS,ND"

Subsystem-License

Esta cabecera define el tipo de licencia de esta característica. Si proporciona un valor para la cabecera Subsystem-License y no proporciona valores para las cabeceras IBM-License-Agreement e IBM-License-Information, se muestra al usuario el valor de cabecera Subsystem-License para la aceptación durante la instalación.

Si ya hay una característica instalada con el mismo valor de cabecera Subsystem-License, no se muestra la licencia y no se busca la aprobación de licencia durante la instalación. Si las dependencias en la cabecera Subsystem-Content significan que hay dos o más características que se van a instalar que tienen el mismo valor de cabecera Subsystem-License, el usuario solo tiene que aceptar la licencia una vez durante la instalación.

Por ejemplo:
Subsystem-License: L-JTHS-93TMHH
Subsystem-License: http://www.apache.org/licenses/LICENSE-2.0.html

IBM-License-Agreement

Esta cabecera especifica el prefijo de la ubicación de los archivos del acuerdo de licencia. Proporcione la vía de acceso de archivo en el archivado de subsistema de los archivos LA_idioma, hasta, pero sin incluir, el carácter "_" (la herramienta de instalación añade el código de idioma). Si no se ha aceptado la licencia, el usuario debe aceptar la licencia al instalar la característica. Los archivos de licencia se copian en el directorio de instalación de Liberty.

Por ejemplo:
IBM-License-Agreement: lafiles/LA

IBM-License-Information

Esta cabecera especifica el prefijo de la ubicación de los archivos de información de la licencia. Proporcione la vía de acceso de archivo en el archivado de subsistema de los archivos LI_idioma, hasta, pero sin incluir, el carácter "_" (la herramienta de instalación añade el código de idioma). Si no se ha aceptado la licencia, el usuario debe aceptar la licencia al instalar la característica. Los archivos de licencia se copian en el directorio de instalación de Liberty.

Por ejemplo:
IBM-License-Information: lafiles/LI

IBM-App-ForceRestart

Esta cabecera hace que las aplicaciones se reinicien al instalar la característica en un servidor en ejecución o eliminarla. Esta cabecera puede tomar uno de los valores siguientes:
  • install: reinicia las aplicaciones cuando se instala la característica.
  • uninstall: reinicia las aplicaciones cuando se desinstala la característica.
  • install: reinicia las aplicaciones cuando se instala o se desinstala la característica.

Ejemplo de archivo de manifiesto de característica

En el ejemplo siguiente se muestra la definición de la característica example-1.0. El atributo visibility público permite que esta característica se especifique directamente en los archivos de configuración de servidor (server.xml); se incluirá también en la lista desplegable de características que se muestran en la vista Configuración de servidor de las herramientas de desarrollador y estará disponible para la inclusión en características que están en otras extensiones del producto. Si se instala esta característica en la extensión del producto usr de una instalación de tiempo de ejecución, se puede configurar en un servidor incluyendo el código siguiente en el archivo server.xml:
<featureManager>
		<feature>usr:example-1.0</feature>
</featureManager>
La configuración de esta característica en un servidor dará como resultado el paquete especificado, com.ibm.example.bundle1, instalado e iniciado en la infraestructura OSGi del entorno de ejecución del servidor. El paquete de API único, com.ibm.example.publicapi, será visible para todas las aplicaciones de ese servidor, excepto para las aplicaciones Java EE configuradas para no tener visibilidad para el tipo de paquete api. Las aplicaciones OSGi deben importar explícitamente el paquete si desean utilizarlo. Los dos paquetes SPI, com.ibm.example.spi.utils y com.acme.spi.spiservices, serán visibles para todo el código de característica del servidor, como lo será el paquete de API.
IBM-Feature-Version: 2
Subsystem-ManifestVersion: 1.0
Subsystem-SymbolicName: com.ibm.example-1.0; visibility:=public
Subsystem-Version: 1.0.0.qualifier
Subsystem-Type: osgi.subsystem.feature
Subsystem-Content: com.ibm.example.bundle1; version="1.0.0"
Subsystem-Localization: OSGI-INF/l10n/loc
Manifest-Version: 1.0
Subsystem-Name: %name
Subsystem-Description: %desc
IBM-API-Package: com.ibm.example.publicapi; type="api"
IBM-SPI-Package: com.ibm.example.spi.utils, com.ibm.example.spi.spiservices
IBM-ShortName: example-1.0

Icono que indica el tipo de tema Tema de referencia

Términos y condiciones para centros de información | Comentarios


Icono de indicación de fecha y hora Última actualización: 15 de junio de 2015
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-libcore-mp&topic=rwlp_feat_definition
Nombre de archivo:rwlp_feat_definition.html