Manifiesto de característica de la plataforma Eclipse
Versión 3.0 - Última revisión 22 de Junio de 2004
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"
os
CDATA #IMPLIED
arch
CDATA #IMPLIED
ws
CDATA #IMPLIED
nl CDATA #IMPLIED
>
<!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
unpack (true |
false) "true"
>
<!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 de los elementos y 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 (consulte el
Javadoc de org.eclipse.core.runtime.Platform).
Indica que esta característica sólo 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 arquitectura definidos por Eclipse (consulte el Javadoc de
org.eclipse.core.runtime.Platform).
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 sistemas de ventanas definidos por Eclipse
(consulte el Javadoc de org.eclipse.core.runtime.Platform).
Indica que esta característica sólo se debe instalar en uno de los sistemas
de ventanas 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).
- 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.ide.workbench.
- plugin: identificador opcional que representa el ID del conector que aparece en la característica que se utiliza para transportar la información de sello personal 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: 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. Si el manejador se especifica como clase, tiene visibilidad de las clases de
API del conector org.eclipse.update.core y de los conectores Eclipse necesarios para este conector; de lo contrario, si se especifica como extensión, tiene acceso a todas las clases como el conector que define la extensió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. Si la característica es un parche (consulte la sección <requires> que figura más adelante), debe ser el ID de otro parche.
- version: versión necesaria de la característica anidada.
- optional: es posible incluir una característica como opcional si este
atributo es "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: si falta una característica opcional, Eclipse no puede representar 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.
- search-location: una característica incluida puede actualizarse mediante parches.
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".
- os: especificación opcional de sistemas operativos. Lista separada por
comas de designadores de sistemas operativos definidos por Eclipse (consulte el
Javadoc de org.eclipse.core.runtime.Platform).
Indica que esta entrada sólo 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 arquitectura definidos por Eclipse (consulte el Javadoc de
org.eclipse.core.runtime.Platform).
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 sistemas de ventanas definidos por
Eclipse (consulte el Javadoc de org.eclipse.core.runtime.Platform).
Indica que esta entrada sólo se debe instalar en uno de los sistemas de
ventanas 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).
- 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).
- <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: si se establece en "true", esta restricción declara que la
característica incluyente 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 identificar la característica a la que se aplica el parche
- debe establecerse el atributo version
- no debe establecerse el atributo match y se presupondrá el valor "perfect".
- si en otras características se utiliza el atributo <include>, también deben ser parches.
Un parche es una característica que transporta versiones más actualizadas de los conectores para la característica a la que se aplica el parche. No sustituye a la característica. Un parche también puede transportar otros parches por inclusión.
- <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 (consulte el
Javadoc de org.eclipse.core.runtime.Platform).
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 arquitectura definidos por Eclipse (consulte el Javadoc de
org.eclipse.core.runtime.Platform).
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 sistemas de ventanas definidos por
Eclipse (consulte el Javadoc de org.eclipse.core.runtime.Platform).
Indica que esta entrada sólo se debe instalar en uno de los sistemas de
ventanas 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).
- 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).
- unpack (nuevo en 3.0): especificación opcional suministrada por el empaquetador de características, que indica que el conector es capaz de ejecutarse desde un JAR y que el contenido del JAR de conector no debe desempaquetarse en un directorio. El valor por omisión es "true".
(Nota de implementación: los conectores parciales, suministrados en una característica que especifique org.eclipse.update.core.DeltaInstallHandler como manejador de instalación, no deben establecer unpack en "false")
- <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 (consulte el
Javadoc de org.eclipse.core.runtime.Platform).
Indica que esta entrada sólo 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 arquitectura definidos por Eclipse (consulte el Javadoc de
org.eclipse.core.runtime.Platform).
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 sistemas de ventanas definidos por
Eclipse (consulte el Javadoc de org.eclipse.core.runtime.Platform).
Indica que esta entrada sólo debe instalarse en uno de los sistemas de ventanas
especificados. Si no se especifica este atributo, la entrada puede
instalarse 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.
Tenga en cuenta que las series
traducidas se emplean durante la instalación (es decir, no emplean el
mecanismo de entorno de ejecución de los fragmentos de conector).