Manifiesto de plug-in de la plataforma Eclipse

Versión 3.0 - Última revisión 24 de Junio de 2004

Esta es una versión archivada del documento. La versión actual puede encontrarse aquí.

Las definiciones de códigos XML del manifiesto abajo indicadas utilizan diversos identificadores y símbolos de denominación. Para eliminar la ambigüedad, le presentamos algunas reglas de producción para estos [están relacionadas en el texto presentado más abajo]. En general, todos los identificadores son sensibles a las mayúsculas y minúsculas.

SimpleToken := secuencia de caracteres de ('a-z','A-Z','0-9','_')
ComposedToken := SimpleToken | (SimpleToken '.' ComposedToken)
JavaClassName := ComposedToken
PlugInId := ComposedToken
PlugInPrereq := PlugInId | 'export' PlugInId
ExtensionId := SimpleToken
ExtensionPointId := SimpleToken
ExtensionPointReference := ExtensionPointID | (PlugInId '.' ExtensionPointId)

El resto de esta sección describe la estructura del archivo plugin.xml como una serie de fragmentos de DTD. El archivo plugin.dtd presenta la definición de DTD en su totalidad.

<?xml encoding="US-ASCII"?>
<!ELEMENT plugin (requires?, runtime?, extension-point*, extension*)>
<!ATTLIST plugin
  name                CDATA #REQUIRED
  id                  CDATA #REQUIRED
  version             CDATA #REQUIRED 
  provider-name       CDATA #IMPLIED
  class               CDATA #IMPLIED 
>

El elemento <plugin> define el cuerpo del manifiesto. De forma opcional, aquí están las definiciones para el código de tiempo de ejecución del plug-in, las definiciones de otros plug-ins que se necesitan para este, las declaraciones de cualquier punto de extensión nuevo introducido por el plug-in, así como las extensiones de configuración o funcionales (configuradas en los puntos de extensión definidos por otros plug-ins, o introducidas por este plug-in). Los atributos <plugin> son los siguientes:

La regla de construcción DTD XML DTD element* indica cero o más apariciiones del elemento; element? indica cero apariciones o una aparición del elemento; y element+ (utilizada más abajo) indica una o más apariciones del elemento. En función de la definición de <plugin> arriba explicada, esto significa que será válido, por ejemplo, un plug-in que contenga una sola definición de tiempo de ejecución y ninguna declaración de punto de extensión o configuración de extensión (por ejemplo, las bibliotecas comunes de las que dependen otros plug-ins). De forma similar, también será válido un plug-in que contenga solo configuraciones de extensión pero ningún punto de extensión o de tiempo de ejecución propios (por ejemplo, al configurar clases entregadas en otros plug-ins en puntos de extensión declarados en otros plug-ins).

La sección <requires> del manifiesto declara las dependencias de otros plug-ins.

<!ELEMENT requires (import+)>
<!ELEMENT import EMPTY>
<!ATTLIST import
 plugin              CDATA #REQUIRED
 version             CDATA #IMPLIED
 match               (perfect | equivalent | compatible | greaterOrEqual) "compatible"
 export              (true | false) "false"
 optional            (true | false) "false"
>

Cada dependencia se especifica utilizando un elemento <import>. Contiene los siguientes atributos:

La sección <runtime> del manifiesto contiene una definición de una o más bibliotecas que componen el código de tiempo de ejecución del plug-in. Las bibliotecas referenciadas se utilizan por los mecanismos de ejecución de la plataforma (el cargador de clases del plug-in) para cargar y ejecutar el código correcto requerido por el plug-in.

<!ELEMENT runtime (library+)>
<!ELEMENT library (export*, packages?)>
<!ATTLIST library
  name                CDATA #REQUIRED
  type                (code | resource) "code"
>
<!ELEMENT export EMPTY>
<!ATTLIST export
  name                CDATA #REQUIRED
>
<!ELEMENT packages EMPTY>
<!ATTLIST packages
  prefixes           CDATA #REQUIRED
>

El elemento <runtime> no tiene atributos.

Los elementos <library> definen de forma colectiva el código de tiempo de ejecución del plug-in. Debe especificarse por lo menos un elemento <library>. Cada elemento <library> tiene los siguientes atributos:

Cada elemento <library> puede especificar qué parte de la biblioteca debe exportarse. Las reglas de exportación se especifican como un conjunto de máscaras de exportación. Por omisión (no se especifican reglas de exportación), la biblioteca se considera privada. Cada máscara de exportación se especifica mediante el atributo name, que puede tener los siguientes valores:

Sólo plug-ins Eclipse 2.1: Cada biblioteca puede también especificar los prefijos de paquete. Éstos se utilizan para mejorar el rendimiento de la carga de clases del plug-in o del fragmento. Si no se especifica el elemento <packages>, por omisión no se utilizan las mejoras de carga de clases. El elemento <packages> tiene el siguiente atributo:

La arquitectura de la plataforma se basa en la noción de puntos de extensión configurables. La propia plataforma predefine un conjunto de puntos de extensión que cubren la tarea de ampliar la plataforma y el escritorio (por ejemplo, añadiendo acciones de menú, contribuyendo con un editor incorporado). Además de los puntos de extensión predefinidos, cada plug-in suministrado puede declarar puntos de extensión adicionales. Al declarar un punto de extensión, el plug-in está básicamente anunciando la capacidad de configurar la función del plug-in con extensiones suministradas desde el exterior. Por ejemplo, el plug-in de construcción de páginas puede declarar un punto de extensión para añadir nuevos controles de tiempo de diseño (DTC) a su paleta de construcción. Esto significa que el constructor de páginas ha definido una arquitectura para lo que se pretende que sea un DTC, y ha implementado el código que busca las extensiones DTC que se hayan configurado en los puntos de extensión.

<!ELEMENT extension-point EMPTY>  
<!ATTLIST extension-point 
  name                CDATA #REQUIRED 
  id                  CDATA #REQUIRED    
  schema              CDATA #IMPLIED 
>

El elemento <extension-point> tiene los siguientes atributos:

Las extensiones actuales se configuran en los puntos de extensión (predefinidos o declarados nuevamente en este plug-in) en la sección <extension>. La información de la configuración se especifica como un XML correctamente construido situado entre los códigos <extension> y </extension>. La plataforma no especifica la forma real de los códigos XML de configuración (aparte de exigir que sea un XML correctamente construido). Los códigos XML están definidos por el suministrador del plug-in que declaró el punto de extensión. La plataforma en realidad no interpreta los códigos XML de configuración. Simplemente pasa la información de configuración al plug-in como parte del proceso de punto de extensión (en el momento que la lógica del punto de extensión consulta todas las extensiones configuradas).

<!ELEMENT extension ANY> 
<!ATTLIST extension 
  point               CDATA #REQUIRED 
  id                  CDATA #IMPLIED 
  name                CDATA #IMPLIED 
>

El elemento <extension> tiene los siguientes atributos:

Importante: el contenido del elemento <extension> se declara utilizando la norma ANY. Esto significa que cualquier XML correctamente construido se puede especificar dentro de la sección de configuración de la extensión (entre los códigos <extension> y </extension>).

Los fragmentos se utilizan para aumentar el ámbito de un plug-in. Por ejemplo, para incorporar datos como mensajes o etiquetas en otro idioma.

<?xml encoding="US-ASCII"?> 
<!ELEMENT fragment (requires?, runtime?, extension-point*, extension*)>
<!ATTLIST fragment
  name                CDATA #REQUIRED
  id                  CDATA #REQUIRED
  version             CDATA #REQUIRED
  provider-name       CDATA #IMPLIED
  plugin-id           CDATA #REQUIRED
  plugin-version      CDATA #REQUIRED
  match               (perfect | equivalent | compatible | greaterOrEqual) "compatible"
>

Cada fragmento debe estar asociado a un plug-in específico. El plug-in asociado se identifica con los atributos <plugin-id>, <plugin-version> y, opcionalmente, <match>. Observe que si esta especificación coincide con más de un plug-in, se utilizará el plug-in coincidente que tenga el número de versión más alto.

Los componentes <requires>, <runtime>, <extension-point> y <extension> de un fragmento se añadirán de manera lógica al plug-in coincidente.

Los atributos de <fragment> son los siguientes: