Eclipse-ympäristön lisäosan manifest-tiedosto

Versio 3.0 - Viimeksi muutettu 24.6.2004

Tämä on asiakirjan arkistoitu versio. Nykyinen versio on täällä.

Alla olevissa manifest-tiedoston merkintämäärityksissä käytetään erilaisia nimeämissanakkeita ja tunnuksia. Tässä annetaan selvyyden vuoksi muutamia muodostussääntöjä [niihin viitataan alla olevassa tekstissä]. Kaikissa tunnuksissa erotellaan yleensä isot ja pienet kirjaimet.

SimpleToken := merkkien sarja ('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)

Tämän kohdan loppuosassa kuvataan plugin.xml-tiedoston rakennetta DTD-fragmenttien sarjana. Tiedostossa plugin.dtd esitetään koko DTD-määritys.

<?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 
>

Elementissä <plugin> määritetään manifest-tiedoston runko. Se sisältää valinnaisesti lisäosan ajonaikaisia määrityksiä, tämän lisäosan muiden pakollisten lisäosien määrityksiä, lisäosien lisäämien mahdollisten uusien laajennuspisteiden esittelyjä sekä toimintolaajennusten kokoonpanon (ne määritetään muiden lisäosien määrittämiksi tai tämän lisäosan lisäämiksi laajennuspisteiksi). Elementillä <plugin> on seuraavat määritteet:

XML DTD -muodostussääntö element* tarkoittaa, että elementin esiintymiä on vähintään nolla; element? tarkoittaa, että elementin esiintymiä on nolla tai yksi;element+ (alla) tarkoittaa, että elementin esiintymiä on vähintään yksi. Yllä olevan <plugin>-määrityksen perusteella tämä tarkoittaa esimerkiksi, että lisäosa, joka sisältää vain yhden ajonaikaisen määrityksen eikä yhtään laajennuspisteen esittelyä tai laajennuksen kokoonpanoa, on kelvollinen (esimerkiksi yhteiset kirjastot, joista muut lisäosat ovat riippuvaisia). Vastaavasti myös lisäosa, joka sisältää vain laajennuksen kokoonpanoja eikä yhtään ajonaikaista tai omaa laajennuspistettä, on kelvollinen (esimerkiksi kokoonpanoluokat, jotka toimitetaan muissa lisäosissa toisissa lisäosissa esiteltyihin laajennuspisteisiin).

Manifest-tiedoston osassa <requires> esitellään mahdolliset riippuvuudet muista lisäosista.

<!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"
>

Kukin riippuvuus määritetään elementin <import> avulla. Se sisältää seuraavat määritteet:

Manifest-tiedoston osa <runtime> sisältää ajonaikaisen lisäosan muodostavan yhden tai useamman kirjaston määrityksen. Ympäristön suoritusmekanismit (lisäosan luokkien lataustoiminto) käyttävät viitattuja kirjastoja lisäosan edellyttämän oikean koodin lataukseen ja suoritukseen.

<!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
>

Elementillä <runtime> ei ole määritteitä.

Ajonaikainen lisäosa määritetään <library>-elementtien avulla. On määritettävä vähintään yksi <library>. Kullakin <library>-elementillä on seuraavat määritteet:

Kunkin <library>-elementin avulla voidaan määrittää, mikä osa kirjastosta täytyy viedä. Vientisäännöt määritetään vientipeitteiden joukkona. Oletusarvoisesti (kun vientisääntöjä ei ole määritetty) kirjastoa pidetään yksityisenä. Kukin vientipeite määritetään name-määritteen avulla, jolla voi olla seuraavat arvot:

Vain Eclipse 2.1 -lisäosat: Kussakin kirjastossa voidaan määrittää myös paketin etuliitteet. Niiden avulla parannetaan lisäosan ja/tai fragmentin luokkien lataustehoa. Jos elementtiä <packages> ei ole määritetty, luokkien latausparannuksia ei oletusarvoisesti käytetä. Elementillä <packages> on seuraava määrite:

Ympäristön arkkitehtuuri perustuu laajennuspisteisiin, joiden kokoonpano voidaan määrittää. Ympäristössä on määritetty ennalta joukko laajennuspisteitä, joiden avulla voidaan laajentaa ympäristöä ja työpöytää (esimerkiksi lisätä valikkotoimintoja tai sisäinen muokkausohjelma). Ennalta määritettyjen laajennuspisteiden lisäksi kussakin toimitetussa lisäosassa voidaan esitellä lisälaajennuspisteitä. Kun lisäosassa esitellään laajennuspiste, siinä käytännössä mainostetaan, että lisäosatoiminnon kokoonpano voidaan määrittää ulkoa toimitettujen laajennusten kanssa. Esimerkiksi sivujen koontilisäosassa voidaan esitellä laajennuspiste, jonka avulla sen koontitoimintovalikoimaan lisätään uusia muokkaustilan ohjaustoimintoja (DTC-toimintoja). Tämä tarkoittaa, että sivujen koontitoiminnossa on määritetty arkkitehtuuri DTC-toimintoa varten ja toteutettu koodi, joka etsii laajennuspisteiden kokoonpanoon määritettyjä DTC-laajennuksia.

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

Elementillä <extension-point> on seuraavat määritteet:

Varsinaiset laajennukset määritetään laajennuspisteiksi (ennalta määritetyiksi tai tässä lisäosassa esitellyiksi laajennuspisteiksi) <extension>-osassa. Kokoonpanon määritystiedot annetaan oikein muotoiltuna XML-koodina tunnisteiden <extension> ja </extension> välissä. Ympäristössä ei määritetä merkintärakenteen varsinaista muotoa (paitsi että sen on oltava oikein muotoiltu XML-koodi). Laajennuspisteen esitelleen lisäosan toimittaja määrittää merkinnän. Ympäristö ei itse asiassa tulkitse merkintärakennetta. Se vain välittää lisäosan kokoonpanotiedot osana laajennuspisteen käsittelyä (silloin, kun laajennuspiste kysyy sen kaikkia määritettyjä laajennuksia).

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

Elementillä <extension> on seuraavat määritteet:

Tärkeää: Elementin <extension> sisältö esitellään ANY-sääntöä käyttäen. Tämä tarkoittaa, että kaikki oikein muotoiltu XML-koodi voidaan määrittää laajennuksen kokoonpano-osassa (tunnisteiden <extension> ja </extension> välissä).

Fragmenttien avulla laajennetaan lisäosan aluetta. Esimerkkinä on sanomien tai nimiöiden kaltaisten tietojen lisääminen toisella kielellä.

<?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"
>

Kukin fragmentti on liitettävä tiettyyn lisäosaan. Fragmenttiin liittyvä lisäosa yksilöidään elementtien <plugin-id> ja <plugin-version> sekä valinnaisesti elementin <match> avulla. Huomaa, että jos tämä määritys vastaa useampaa kuin yhtä lisäosaa, käytetään vastaavaa lisäosaa, jonka versionumero on suurin.

Fragmentin osat <requires>, <runtime>, <extension-point> ja <extension> lisätään loogisesti vastaavaan lisäosaan.

Elementin <fragment> määritteet ovat seuraavat: