Archivadores de características
La información de empaquetado de características se coloca en un archivo .jar
Java independiente.
Los recursos jar Java estándar se emplean para construir
archivadores de características.
Los archivadores de características hacen
referencia a archivadores de conectores empaquetados por separado (vea el
apartado siguiente) y a archivos no de conector.Las características se
identifican con un identificador estructurado que toma como base el nombre del
dominio Internet del proveedor. Por ejemplo, la organización eclipse.org
produce la característica org.eclipse.jdt. El juego de caracteres que se emplea
para los identificadores de una característica es precisamente el que esté
especificado para los identificadores de la característica (vea
Manifiesto de conector).
El convenio recomendado para denominar los archivadores de
características es:
<id>_<versión>.jar
Donde <id> es el identificador de la característica y
<versión> es el identificador completo de la versión, que está en
el correspondiente archivo feature.xml.
Tenga en cuenta que este es un convenio
recomendado que minimiza la probabilidad de que se produzcan colisiones, pero
no viene impuesto por la arquitectura de Eclipse. Por ejemplo, los siguientes
nombres también son válidos para los archivadores de características:
org.eclipse.jdt_2.0.0.jar
org.eclipse.pde_2.0.jar
mi_característica.jar
Internamente, cada archivador de característica se empaqueta de forma
relativa al correspondiente directorio de la característica (sin incluir el
elemento de vía de acceso del directorio). La estructura del archivador es
la siguiente:
feature.xml
feature<_entornoLocal>.properties (vea "Información de característica
traducida")
otros archivos y subdirectorios de la característica (TBD)
META-INF/
archivos de manifiesto y de seguridad jar Java
Manifiesto de una característica
El formato del manifiesto de una característica viene definido por la
siguiente dtd:
<?xml encoding="ISO-8859-1"?>
<!ELEMENT feature (install-handler? | description? | copyright? |
license? | url? | includes* | requires? | plugin* | data*)>
<!ATTLIST feature
id
CDATA #REQUIRED
version
CDATA #REQUIRED
label
CDATA #IMPLIED
provider-name CDATA #IMPLIED
image
CDATA #IMPLIED
os
CDATA #IMPLIED
arch
CDATA #IMPLIED
ws
CDATA #IMPLIED
nl
CDATA #IMPLIED
colocation-affinity
CDATA #IMPLIED
primary
(true | false) "false"
exclusive (true | false)
"false"
plugin CDATA
#IMPLIED
application CDATA #IMPLIED
>
<!ELEMENT install-handler EMPTY>
<!ATTLIST install-handler
library
CDATA #IMPLIED
handler
CDATA #IMPLIED
>
<!ELEMENT description (#PCDATA)>
<!ATTLIST description
url
CDATA #IMPLIED
>
<!ELEMENT copyright (#PCDATA)>
<!ATTLIST copyright
url
CDATA #IMPLIED
>
<!ELEMENT license (#PCDATA)>
<!ATTLIST license
url
CDATA #IMPLIED
>
<!ELEMENT url (update?, discovery*)>
<!ELEMENT update EMPTY>
<!ATTLIST update
url
CDATA #REQUIRED
label
CDATA #IMPLIED
>
<!ELEMENT discovery EMPTY>
<!ATTLIST discovery
type
(web | update) "update"
url
CDATA #REQUIRED
label
CDATA #IMPLIED
>
<!ELEMENT includes EMPTY>
<!ATTLIST includes
id CDATA #REQUIRED
version CDATA #REQUIRED
name
CDATA #IMPLIED
optional (true | false)
"false"
search-location (root | self | both)
"root"
match
(perfect | equivalent | compatible | greaterOrEqual) "compatible"
>
<!ELEMENT requires (import+)>
<!ELEMENT import EMPTY>
<!ATTLIST import
plugin
CDATA #IMPLIED
feature CDATA #IMPLIED
version
CDATA #IMPLIED
match
(perfect | equivalent | compatible | greaterOrEqual) "compatible"
patch (true |
false) "false"
>
<!ELEMENT plugin EMPTY>
<!ATTLIST plugin
id
CDATA #REQUIRED
version
CDATA #REQUIRED
fragment (true
| false) "false"
os
CDATA #IMPLIED
arch
CDATA #IMPLIED
ws
CDATA #IMPLIED
nl
CDATA #IMPLIED
download-size CDATA #IMPLIED
install-size CDATA #IMPLIED
>
<!ELEMENT data EMPTY>
<!ATTLIST data
id
CDATA #REQUIRED
os
CDATA #IMPLIED
arch
CDATA #IMPLIED
ws
CDATA #IMPLIED
nl
CDATA #IMPLIED
download-size CDATA #IMPLIED
install-size CDATA #IMPLIED
>
Las definiciones del elemento y de los atributos son las siguientes:
-
<feature>: define la característica.
-
id: identificador necesario de la característica (por ejemplo,
com.xyz.micaracterística).
-
version: versión necesaria del componente (por ejemplo, 1.0.3).
-
label: etiqueta visualizable opcional (nombre). Debe ser traducible.
-
provider-name: etiqueta de visualización opcional que identifica la
organización que proporciona este componente. Debe ser traducible.
-
image: imagen opcional que debe utilizarse al visualizar información sobre la
característica.
Se especifica de manera relativa al archivo feature.xml.
-
os: especificación opcional de sistemas operativos. Lista separada por comas de
designadores de sistemas operativos definidos por Eclipse (vea el Javadoc de
org.eclipse.core.boot.BootLoader).
Indica que esta característica solo
se debe instalar en uno de los sistemas operativos especificados. Si no se
especifica este atributo, la característica se puede instalar en todos los
sistemas (implementación transportable). Esta información se utiliza en el soporte
de instalación y actualización a modo de sugerencia (el usuario puede forzar la
instalación de la característica sin tener en cuenta este valor).
-
arch: especificación opcional de arquitecturas de máquina. Lista separada por comas de
designadores de arquitecturas definidos por Eclipse (vea el Javadoc de
org.eclipse.core.boot.BootLoader).
Indica que esta característica solo
se debe instalar en uno de los sistemas especificados. Si no se
especifica este atributo, la característica se puede instalar en todos los
sistemas (implementación transportable). Esta información se utiliza en el soporte
de instalación y actualización a modo de sugerencia (el usuario puede forzar la
instalación de la característica sin tener en cuenta este valor).
-
ws: especificación opcional de sistemas de colocación en ventanas. Lista separada por comas de
designadores de ws definidos por Eclipse (vea el Javadoc de
org.eclipse.core.boot.BootLoader).
Indica que esta característica solo
se debe instalar en uno de los sistemas ws. Si no se
especifica este atributo, la característica se puede instalar en todos los
sistemas (implementación transportable). Esta información se utiliza en el soporte
de instalación y actualización a modo de sugerencia (el usuario puede forzar la
instalación de la característica sin tener en cuenta este valor).
-
nl: especificación opcional de entornos locales. Lista separada por comas de
designadores de entornos locales definidos por Java. Indica que esta
característica solo se debe instalar en un sistema que se ejecute con un
entorno local compatible (siguiendo las reglas Java de coincidencia con
entornos locales). Si no se especifica este atributo, la característica se
puede instalar en todos los sistemas (implementación independiente del
idioma). Esta información se utiliza en el soporte
de instalación y actualización a modo de sugerencia (el usuario puede forzar la
instalación de la característica sin tener en cuenta este valor).
-
colocation-affinity: referencia opcional a otro identificador de característica
que sirve para seleccionar la ubicación de instalación por omisión de esta
característica. Cuando esta característica se instale como nueva (no hay
instalada ninguna otra versión de ella), se realiza un intento de instalarla en
la misma ubicación de instalación que la característica a la que se hace
referencia.
-
primary: indicación opcional que especifica si esta característica se puede
usar como primaria. El valor por omisión es false (no puede usarse como
característica primaria).
-
application: identificador opcional de la aplicación de Eclipse que debe
utilizarse durante el inicio cuando la característica declarante es la
primaria. El identificador debe representar una aplicación válida que esté
registrada en el punto de extensión
org.eclipse.core.runtime.applications. El valor por omisión es
org.eclipse.ui.workbench.
-
plugin (nuevo en el release 2.1): identificador opcional que representa el ID del conector que aparece en la característica que se utiliza para transportar la información de atribuciones de la característica (imágenes, traducciones, pantallas de lanzamiento en el caso de características primarias, etc.).
Si no se especifica, se presupondrá que el conector de atribuciones tiene el mismo ID que la característica.
-
exclusive (nuevo en el release 2.1): indicador opcional que, si es "true", indica que la característica no puede instalarse en un grupo con otras características.
-
<install-handler>
-
library: biblioteca .jar opcional que contiene las clases del manejador de
instalación.
Si se especifica, el .jar al que se hace referencia debe estar
situado en el archivador de la característica.
Se especifica dentro del
archivador de la característica, en forma de vía de acceso relativa a la entrada
feature.xml. Si no se especifica, se emplea el propio archivador de la
característica para cargar las clases del manejador de instalación. Este
atributo solo se interpreta si también se especifica el atributo class.
-
handler: identificador opcional del manejador de instalación. Este valor se
interpreta en función del valor del atributo library. Si library
está especificado, el valor se interpreta como nombre totalmente calificado de
una clase contenida en la biblioteca especificada por
library. Si library no está especificado, el valor se interpreta
como identificador de una extensión registrada en el punto de extensión
org.eclipse.update.installHandlers. En los dos casos, la clase
resultante debe implementar la interfaz IInstallHandler. La clase se
carga dinámicamente y se la llama en momentos específicos del proceso de la
característica. El manejador tiene visibilidad hacia las clases de API del
conector de actualización y los conectores de Eclipse que necesita el conector
de actualización.
-
<description>: texto descriptivo, corto y sencillo del componente. Debe ser traducible.
-
url: URL opcional de la descripción completa en forma de HTML. El URL se puede
especificar como absoluto o relativo. Si se especifica como relativo, se supone
que lo es en relación al archivador de la característica (y debe estar
empaquetado en dicho archivador). Observe que, para el manejo de idiomas
nacionales (NL), el valor del URL debe estar separado para permitir especificar
URL alternativos para cada idioma nacional.
-
<copyright>: texto simple del copyright de la característica. Debe ser traducible.
-
url: URL opcional de la descripción completa en forma de HTML. El URL se puede
especificar como absoluto o relativo. Si se especifica como relativo, se supone
que lo es en relación al archivador de la característica (y debe estar
empaquetado en dicho archivador). Observe que, para el manejo de idiomas
nacionales (NL), el valor del URL debe estar separado para permitir especificar
URL alternativos para cada idioma nacional.
-
<license>: texto simple de la licencia "mediante pulsación" de la
característica. Debe ser traducible. Se
visualiza en un diálogo estándar con las acciones [Aceptar] [Rechazar]
durante el proceso de bajada/instalación. Observe que hay que especificar la
licencia mediante pulsación para toda característica que se vaya a seleccionar
para instalación o actualización utilizando el gestor de actualizaciones de
Eclipse. Si se emplean características anidadas, solo es necesario definir el
texto de licencia mediante pulsación del padre de la anidación (es decir, de la
característica seleccionada para instalación o actualización). El texto de la
licencia es necesario aunque se especifique el atributo url
opcional.
-
url: URL opcional de la descripción completa en forma de HTML. El URL se puede
especificar como absoluto o relativo. Si se especifica como relativo, se supone
que lo es en relación al archivador de la característica (y debe estar
empaquetado en dicho archivador). Observe que, para el manejo de idiomas
nacionales (NL), el valor del URL debe estar separado para permitir especificar
URL alternativos para cada idioma nacional. Tenga presente que el contenido
("content") de este URL no es lo que se presenta como licencia mediante
pulsación durante el proceso de instalación. La licencia mediante pulsación es
el valor real del elemento <license> (por ejemplo, <license>texto mediante pulsación</license>)
-
<url>: URL opcional que especifica uno o varios sitios que contienen
actualizaciones de características o características nuevas.
-
<update>: URL donde conseguir actualizaciones para esta característica.
-
url: URL real.
-
label: etiqueta visualizable (nombre) para el sitio al que se hace referencia.
-
<discovery>: URL donde conseguir nuevas características. En general, un
proveedor puede utilizar este elemento para hacer referencia a su(s) propio(s)
sitio(s) o a los sitios de socios que ofrecen características
complementarias. Eclipse utiliza este elemento sencillamente como
forma de distribuir los URL de sitios nuevos a los clientes. Los sitios que pertenecen a características raíz (en la parte superior de la jerarquía) aparecen generalmente en la sección "Sitios a visitar" del gestor de actualizaciones.
-
url: URL real.
-
label: etiqueta visualizable (nombre) para el sitio al que se hace referencia.
-
type (nuevo en el release 2.1): por omisión, se supone que los sitios de descubrimiento son sitios de actualización ("update"). Si el valor de este atributo se establece en
"web", es posible indicar a Eclipse que el URL debe considerarse un hiperenlace Web habitual que puede visualizarse directamente en el navegador adecuado.
-
<includes>: referencia opcional a una característica anidada que se
considera parte de la presente característica. Las características anidadas
deben estar situadas en el mismo sitio de actualizaciones que la característica
en cuestión.
-
id: identificador necesario de la característica anidada.
-
version: versión necesaria de la característica anidada.
-
optional (nuevo en el release 2.1): es posible incluir una característica como opcional si este atributo se establece en "true". Se permite a los usuarios no instalar las características opcionales, inhabilitarlas si están instaladas e instalarlas posteriormente. El hecho de que falte una característica opcional no se considera un error.
-
name (nuevo en el release 2.1): si falta una característica opcional, Eclipse no puede visualizar su nombre adecuadamente. Este atributo puede utilizarse como "espacio reservado" para que Eclipse pueda visualizar el nombre de la característica opcional cuando no está instalada.
-
match (nuevo en el release 2.1): si se incluye una característica con match="perfect"
(el valor por omisión), debe existir la versión exacta para que la referencia pueda cumplirse.
Por el contrario, otros valores ("compatible", "equivalent" etc.)
permiten algo más de flexibilidad. Es de vital importancia establecer este atributo en un valor diferente de "perfect" si desea que puedan actualizarse o parchearse las ramificaciones.
-
search-location (nuevo en el release 2.1): si el atributo match se establece en un valor distinto de "perfect", una característica incluida puede actualizarse con los límites establecidos por el atributo "match". Por omisión, la ubicación de
búsqueda (search location) es "root", lo que significa que se tomará en cuenta el
URL especificado en el elemento "update" situado dentro del elemento
"url" del padre. Si una característica incluida tiene definido su propio elemento
"update", se pasará por alto por omisión.
Si la característica padre desea permitir que se actualice la hija a partir de su propia ubicación, puede establecer este atributo en "both" o "self".
-
<requires>: información opcional de las dependencias de la característica. Se
expresa en términos de dependencias de conectores. Si se especifica, entra en
vigor mediante el soporte de instalación y actualización en el momento de la
instalación.
-
<import>: entrada de dependencias. La especificación y el proceso es un
subconjunto de la especificación de <import> en el archivo plugin.xml.
-
plugin: identificador del conector dependiente, si se utiliza el conector (plug-in) para expresar la dependencia.
-
feature (nuevo en el release 2.1): identificador de la característica dependiente, si se utiliza la característica (feature) para expresar la dependencia. Deben establecerse el atributo plugin o el atributo feature, pero no ambos. Si el atributo "patch" es "true", debe utilizarse el atributo feature.
-
version: especificación opcional de la versión del conector. Si el atributo "patch" es "true", debe establecerse el atributo version.
-
match: regla opcional de comparación. Los valores válidos y el proceso son los
siguientes:
-
Si el atributo version no está especificado, se hace caso omiso del atributo
match (si está especificado).
-
perfect: la versión del conector dependiente debe coincidir
exactamente con la versión especificada. Si "patch" es "true", se presupone "perfect" y no pueden establecerse otros valores.
-
equivalent: la versión del conector dependiente debe tener un
nivel de servicio igual o superior al de la versión especificada (los niveles
principal y secundario de la versión deben ser iguales al de la versión
especificada).
-
compatible: la versión del conector dependiente debe tener un
nivel secundario o de servicio igual o superior al de la versión especificada
(el nivel principal de la versión debe ser igual al de la versión especificada).
-
greaterOrEqual: la versión del conector dependiente debe tener un
nivel principal, secundario o de servicio igual o superior al de la versión
especificada.
-
patch (nuevo en el release 2.1): si se establece en "true", esta restricción declara la característica incluyente que debe ser un parche de la característica a la que se hace referencia. Al establecer este atributo, deben seguirse ciertas normas:
- debe utilizarse el atributo feature para expresar la dependencia de parche (patch)
- debe establecerse el atributo version
- no debe establecerse el atributo match y se presupondrá el valor "perfect".
Un parche es una característica que transporta versiones más actualizadas de las características en la jerarquía de la característica a la que se aplica el parche. Un parche transporta estas nuevas versiones de característica por inclusión. La característica a la que se aplica el parche debe estar preparada para aceptar parches mediante la inclusión de sus hijas utilizando el atributo "match" establecido en un valor que no sea "perfect". Esto es de vital importancia, ya que permitirá a la característica parcheada recoger versiones más actualizadas de sus hojas una vez instalado el parche.
-
<plugin>: identifica el conector al que se hace referencia.
-
id: identificador necesario del conector (del archivo plugin.xml).
-
version: versión necesaria del conector (del archivo plugin.xml).
-
fragment: especificación opcional que indica si esta entrada en un
fragmento de conector. El valor por omisión es "false".
-
os: especificación opcional de sistemas operativos. Lista separada por comas de
designadores de sistemas operativos definidos por Eclipse (vea el Javadoc de
org.eclipse.core.boot.BootLoader).
Indica que esta entrada solo
se debe instalar en uno de los sistemas operativos especificados. Si no se
especifica este atributo, la entrada se puede instalar en todos los
sistemas (implementación transportable). Esta información se utiliza en el soporte
de instalación y actualización a modo de sugerencia (el usuario puede forzar la
instalación de la entrada sin tener en cuenta este valor).
-
arch: especificación opcional de arquitecturas de máquina. Lista separada por comas de
designadores de arquitecturas definidos por Eclipse (vea el Javadoc de
org.eclipse.core.boot.BootLoader).
Indica que esta característica solo
se debe instalar en uno de los sistemas especificados. Si no se
especifica este atributo, la característica se puede instalar en todos los
sistemas (implementación transportable). Esta información se utiliza en el soporte
de instalación y actualización a modo de sugerencia (el usuario puede forzar la
instalación de la característica sin tener en cuenta este valor).
-
ws: especificación opcional de sistemas de colocación en ventanas. Lista separada por comas de
designadores de ws definidos por Eclipse (vea el Javadoc de
org.eclipse.core.boot.BootLoader).
Indica que esta entrada solo
se debe instalar en uno de los sistemas ws. Si no se
especifica este atributo, la entrada se puede instalar en todos los
sistemas (implementación transportable). Esta información se utiliza en el soporte
de instalación y actualización a modo de sugerencia (el usuario puede forzar la
instalación de la entrada sin tener en cuenta este valor).
-
nl: especificación opcional de entornos locales. Lista separada por comas de
designadores de entornos locales definidos por Java. Indica que esta
entrada solo se debe instalar en un sistema que se ejecute con un
entorno local compatible (siguiendo las reglas Java de coincidencia con
entornos locales). Si no se especifica este atributo, la entrada se
puede instalar en todos los sistemas (implementación independiente del
idioma). Esta información se utiliza en el soporte
de instalación y actualización a modo de sugerencia (el usuario puede forzar la
instalación de la entrada sin tener en cuenta este valor).
-
download-size: sugerencia opcional suministrada por el empaquetador de la
característica; indica el tamaño de bajada en KBytes del archivador de conector
al que se hace referencia. Si no se especifica, el tamaño de bajada es
desconocido (Nota de implementación: la implementación debe distinguir
entre un tamaño desconocido ("not known") y el tamaño 0).
-
install-size: sugerencia opcional suministrada por el empaquetador de la
característica; indica el tamaño de instalación en KBytes del archivador de conector
al que se hace referencia. Si no se especifica, el tamaño de instalación es
desconocido (Nota de implementación: la implementación debe distinguir
entre un tamaño desconocido ("not known") y el tamaño 0).
-
<data>: identifica los datos no de conector que forman parte de la
característica.
-
id: identificador necesario de los datos, en forma de vía de acceso relativa.
-
os: especificación opcional de sistemas operativos. Lista separada por comas de
designadores de sistemas operativos definidos por Eclipse (vea el Javadoc de
org.eclipse.core.boot.BootLoader).
Indica que esta entrada solo
se debe instalar en uno de los sistemas operativos especificados. Si no se
especifica este atributo, la entrada se puede instalar en todos los
sistemas (implementación transportable). Esta información se utiliza en el soporte
de instalación y actualización a modo de sugerencia (el usuario puede forzar la
instalación de la entrada sin tener en cuenta este valor).
-
arch: especificación opcional de arquitecturas de máquina. Lista separada por comas de
designadores de arquitecturas definidos por Eclipse (vea el Javadoc de
org.eclipse.core.boot.BootLoader).
Indica que esta característica solo
se debe instalar en uno de los sistemas especificados. Si no se
especifica este atributo, la característica se puede instalar en todos los
sistemas (implementación transportable). Esta información se utiliza en el soporte
de instalación y actualización a modo de sugerencia (el usuario puede forzar la
instalación de la característica sin tener en cuenta este valor).
-
ws: especificación opcional de sistemas de colocación en ventanas. Lista separada por comas de
designadores de ws definidos por Eclipse (vea el Javadoc de
org.eclipse.core.boot.BootLoader).
Indica que esta entrada solo
se debe instalar en uno de los sistemas ws. Si no se
especifica este atributo, la entrada se puede instalar en todos los
sistemas (implementación transportable). Esta información se utiliza en el soporte
de instalación y actualización a modo de sugerencia (el usuario puede forzar la
instalación de la entrada sin tener en cuenta este valor).
-
nl: especificación opcional de entornos locales. Lista separada por comas de
designadores de entornos locales definidos por Java. Indica que esta
entrada solo se debe instalar en un sistema que se ejecute con un
entorno local compatible (siguiendo las reglas Java de coincidencia con
entornos locales). Si no se especifica este atributo, la entrada se
puede instalar en todos los sistemas (implementación independiente del
idioma). Esta información se utiliza en el soporte
de instalación y actualización a modo de sugerencia (el usuario puede forzar la
instalación de la entrada sin tener en cuenta este valor).
-
download-size: sugerencia opcional suministrada por el empaquetador de la
característica; indica el tamaño de bajada en KBytes del archivador de datos
al que se hace referencia. Si no se especifica, el tamaño de bajada es
desconocido (Nota de implementación: la implementación debe distinguir
entre un tamaño desconocido ("not known") y el tamaño 0).
-
install-size: sugerencia opcional suministrada por el empaquetador de la
característica; indica el tamaño de instalación en KBytes del archivador de datos
al que se hace referencia. Si no se especifica, el tamaño de instalación es
desconocido (Nota de implementación: la implementación debe distinguir
entre un tamaño desconocido ("not known") y el tamaño 0).
Al interaccionar con el sitio de actualizaciones, la implementación de la
característica correlaciona los elementos <plugin> y
<data> con los identificadores de vía de acceso utilizados por el
sitio para determinar los archivos reales que hay que bajar e
instalar. La implementación de características por omisión suministrada por
Eclipse construye los identificadores de vía de acceso de la siguiente manera:
-
El elemento <plugin> da como resultado una entrada de vía de acceso
cuyo formato es "plugins/<idConector>_<versiónConector>.jar" (por ejemplo,
"plugins/org.eclipse.core.boot_2.0.0.jar").
-
El elemento <data> da como resultado una entrada de vía de acceso
cuyo formato es
"features/<idCaracterística>_<versiónCaracterística>/<idDatos>"
(por ejemplo, "features/com.xyz.tools_1.0.3/examples.zip").
Observe que, en general, los documentos del manifiesto feature.xml deben
especificar la codificación UTF-8. Por ejemplo
<?xml version="1.0" encoding="UTF-8"?>
El texto traducible contenido en el archivo feature.xml se puede separar en
archivos feature<_entornoLocal>.properties siguiendo los convenios de
los paquetes compuestos de propiedades Java.
Fíjese en que las series
traducidas se emplean en tiempo de instalación (es decir, no emplean el
mecanismo de tiempo de ejecución de los fragmentos de conector).
