OSGi-bundelmanifestheaders

Versie 3.1, laatst gewijzigd op 20 juni 2005

Een bundel kan beschrijvende informatie over zichzelf bevatten in het manifestbestand META-INF/MANIFEST.MF. De OSGi R4-frameworkspecificatie biedt de mogelijkheid om een set manifestheaders te definiëren, zoals Export-Package en Bundle-Classpath, die bundelontwikkelaars kunnen gebruiken om beschrijvende informatie over een bundel aan te leveren. Het Eclipse-OSGi-framework implementeert de volledige OSGi R4-frameworkspecificatie en alle Core Framework-services. De Core Framework-services van OSGi R4 zijn onder meer de volgende:

In de OSGi R4-specificatie zijn een aantal optionele services gedefinieerd. De services maken geen deel uit van de implementatie van het Eclipse OSGi-framework. Meer informatie over OSGi R4-manifestheaders en -services kunt u vinden in OSGi-specificaties.

Eclipse-bundelmanifestheaders

Het OSGi-framework van Eclipse ondersteunt een aantal aanvullende headers en instructies voor bundelmanifesten. Deze aanvullingen kunnen door ontwikkelaars van bundels worden gebruikt om de extra functies van het OSGi-framework van Eclipse, die geen deel uitmaken van het standaard OSGi R4-framework, te benutten.

Aanvullende instructies voor Export-Package

Het OSGi-framework van Eclipse biedt ondersteuning voor aanvullende instructies in de header Export-Package. De instructies dienen voor het instellen van de toegangsregels van een geëxporteerd pakket. Raadpleeg osgi.resolverMode voor meer informatie over het configureren van het Eclipse OSGi-framework en het instellen van toegangsregels tijdens runtime.

De instructie x-internal

De instructie x-internal kan in de header Export-Package worden gebruikt om aan te geven dat een pakket intern is. In de Plug-in Development Environment wordt niet aanbevolen interne pakketten te gebruiken met andere bundels. De standaardwaarde van de instructie x-internal is 'false'. De syntaxis van de instructie x-internal is als volgt:

x-internal ::= ( 'true' | 'false' )

Hieronder ziet u een voorbeeld van de instructie x-internal:

Export-Package: org.eclipse.foo.internal; x-internal:=true

De instructie x-friends

De instructie x-friends kan in de header Export-Package worden gebruikt om een lijst met bundels op te geven die toegang tot het pakket hebben. In de Plug-in Development Environment wordt niet aanbevolen het pakket te gebruiken met andere bundels. De syntaxis van de instructie x-friends is als volgt:

x-friends ::= '"' ( target-bundle ) ( ',' target-bundle ) * '"'
target-bundle ::= een symbolische bundelnaam

Hieronder ziet u een voorbeeld van de instructie x-friends:

Export-Package: org.eclipse.foo.formyfriends; x-friends:="org.eclipse.foo.friend1, org.eclipse.foo.friend2"

In het voorbeeld wordt toegang tot het pakket org.eclipse.foo.formyfriends alleen verleend voor de bundels org.eclispe.foo.friend1 en org.eclipse.foo.friend2. De instructie x-internal heeft meer prioriteit dan de instructie x-friends. Als x-internal op 'true' is ingesteld, hebben zelfs de pakketten die met x-friend zijn gedefinieerd, geen toegang.

De header Eclipse-LazyStart

De header Eclipse-LazyStart wordt gebruikt om aan te geven dat een bundel automatisch moet worden gestart vóór de eerste klasse of resource uit de bundel wordt opgevraagd. Zo kunnen bundels pas worden geactiveerd door Eclipse zodra ze voor het eerst nodig zijn en kan Eclipse met zo weinig mogelijk bundels worden geactiveerd. De syntaxis van de header Eclipse-LazyStart is als volgt:

Eclipse-LazyStart ::= ( 'true' | 'false' ) ( ';' 'exceptions' '=' '"' exceptions-list '"' ) ?
exceptions-list ::= een door komma's gescheiden lijst met pakketten 

Het kenmerk 'exceptions' kan een lijst met pakketten bevatten die er niet voor mogen zorgen dat de bundel wordt geactiveerd zodra klassen of resources worden opgevraagd. Als de header Eclipse-LazyStart niet in het bundelmanifest is gedefinieerd, wordt de standaardwaarde 'false' gebruikt. Dit is een voorbeeld van de header Eclipse-LazyStart:

Eclipse-LazyStart: true; exceptions="org.eclipse.foo1, org.eclipse.foo2"

In het voorbeeld wordt de bundel geactiveerd voor alle klassen of resources van de bundel, met uitzondering van de pakketten 'org.eclipse.foo1' en 'org.eclipse.foo2'.

Vanaf Eclipse 3.2 is de header Eclipse-AutoStart gedeprecieerd.Gebruik voortaan de header Eclipse-LazyStart.

De header Eclipse-PlatformFilter

De header Eclipse-PlatformFilter biedt de mogelijkheid een platformfilter op te geven. Alleen als de platformfilter in 'true' resulteert op het actieve platform, mag de bundel worden omgezet. De syntaxis van de header Eclipse-PlatformFilter is als volgt:

Eclipse-PlatformFilter ::= een geldige LDAP-filtertekenreeks

U kunt in het framework filters instellen voor de volgende systeemeigenschappen:

Hieronder ziet u een voorbeeld van de header Eclipse-PlatformFilter:

Eclipse-PlatformFilter: (& (osgi.ws=win32) (osgi.os=win32) (osgi.arch=x86))

In dit voorbeeld wordt de bundel alleen omgezet als de platformeigenschappen overeenkomen met osgi.ws=win32, osgi.os=win32 en osgi.arch=x86 (een platform met de x86-architectuur, het win32-besturingssysteem en het win32-venstersysteem).

De header Eclipse-BuddyPolicy

De header Eclipse-BuddyPolicy wordt gebruikt om het beleid voor het laden van klassen in bundels te specificeren. De syntaxis van de header Eclipse-BuddyPolicy is als volgt:

Eclipse-BuddyPolicy ::= ( policy-name ) ( ',' policy-name ) *
policy-name ::= ( 'dependent' | 'global' | 'registered' |
                  'app' | 'ext' | 'boot' | 'parent' )

Hieronder ziet u een voorbeeld van de header Eclipse-BuddyPolicy:

Eclipse-BuddyPolicy: dependent

De header Eclipse-RegisterBuddy

De header Eclipse-RegisterBuddy biedt de mogelijkheid een bundel als buddy te registreren voor een lijst met bundels. De syntaxis van de header Eclipse-RegisterBuddy is als volgt:

Eclipse-RegisterBuddy ::= ( target-bundle ) ( ',' target-bundle ) *
target-bundle ::= een symbolische bundelnaam

Hieronder ziet u een voorbeeld van de header Eclipse-RegisterBuddy:

Eclipse-RegisterBuddy: org.eclipse.foo.bundle1, org.eclipse.foo.bundle2

De header Eclipse-ExtensibleAPI

De header Eclipse-ExtensibleAPI wordt gebruikt om aan te geven of fragmentbundels aanvullende pakketten aan de API van een hostbundel mogen toevoegen. De standaardwaarde van de header is 'false'. De syntaxis van de header Eclipse-ExtensibleAPI is als volgt:

Eclipse-ExtensibleAPI ::= ( 'true' | 'false' )

Hieronder ziet u een voorbeeld van de header Eclipse-ExtensibleAPI:

Eclipse-ExtensibleAPI: true

De header Eclipse-GenericCapabilty

De header Eclipse-GenericCapability dient om een generieke voorziening van een bundel op te geven. Generieke voorzieningen dienen ter beschrijving van bundelfeatures, die mogelijk vereist zijn voor andere bundels in het systeem (met de header Eclipse-GenericRequire). Generieke voorzieningen krijgen een naam en een type. De voorzieningstypen worden gedefinieerd door de bundel die de voorziening biedt. Verder kan een verzameling kenmerken met een type bevatten voor vergelijkingsdoeleinden bij het omzetten van de header Eclipse-GenericRequire. Voor overeenkomende kenmerken kunnen een van deze typen worden gebruikt: [string | version | uri | long | double | set]. Het type 'set' dient om een verzameling tekenreeksen (van elkaar gescheiden met een komma) te definiëren. De syntaxis van de header Eclipse-GenericCapability is als volgt:

  Eclipse-GenericCapability ::= capability ( ',' capability ) *
  capability                ::= typed-name ( ';' typed-name ) *
                                ( ';' typed-param ) *
  typed-name                ::= name ( ':' capability-type )
  typed-param               ::= typed-key '=' quoted-string
  typed-key                 ::= name ( ':'
                                [string | version | uri | long | double | set] )

Dit is een voorbeeld van de header Eclipse-GenericCapability waarmee een bundel met een implementatie van een OSGi-service (org.acme.stuff.SomeService) kan worden opgegeven:

  Eclipse-GenericCapability:
   org.acme.stuff.SomeService:osgi.service;
   version:version="1.0.1"

De header Eclipse-GenericRequire

De header Eclipse-GenericRequire dient om een vereiste op te geven voor een voorziening die door een andere bundel wordt aangeboden (met de header Eclipse-GenericCapability). Generieke vereisten krijgen een naam en een type. De voorzieningstypen worden gedefinieerd door de bundel die de voorziening biedt. Voor generieke vereisten kan een LDAP-filterreeks worden opgegeven voor vergelijkingsdoeleinden bij het zoeken van generieke voorzieningen. De syntaxis van de header Eclipse-GenericRequire is als volgt:

  Eclipse-GenericRequire   ::= generic-require ( ',' generic-require ) *
  generic-require          ::= typed-name ( ';' typed-name ) *
                               ( ';' selection-filter '=' quoated-ldapFilter )
                               ( ';' optional '=' [true|false] )
                               ( ';' multiple '=' [true|false] )
  typed-name                ::= name ( ':' capability-type )

Dit is een voorbeeld van de header Eclipse-GenericRequire waarmee een bundel kan worden opgegeven die afhankelijk is van een implementatie van een OSGi-service (org.acme.stuff.SomeService):

  Eclipse-GenericRequire:
   org.acme.stuff.SomeService:osgi.service;
   selection-filter="(version>=1.0.1)"

Generieke aliassen

Middels de optie osgi.genericAliases kunt u bestaande OSGi-manifestheaders aan de manifestheaders Eclipse-GenericCapability en Eclipse-GenericRequire toewijzen. Zie bijvoorbeeld de volgende manifestheaders:

  Export-Service: org.acme.stuff.SomeService
  Import-Service: org.acme.stuff.SomeService

Deze headers kunnen met de volgende eigenschap aan de headers Eclipse-GenericCapability en Eclipse-GenericRequire worden toegewezen:

  osgi.genericAliases=Export-Service:Import-Service:osgi.service

Dit komt in feite op het volgende neer:

  Eclipse-GenericRequire: org.acme.stuff.SomeService:osgi.service
  Eclipse-GenericCapability: org.acme.stuff.SomeService:osgi.service

De header Plugin-Class

De header Plugin-Class wordt alleen gebruikt ter ondersteuning van plugins die voor het Eclipse 2.1-platform zijn ontwikkeld. Deze header dient om de naam op te geven van een klasse voor het activeren van een plugin op basis van het verouderde activeringsmodel van Eclipse 2.1. Gebruik deze header niet voor nieuwe bundels die voor Eclipse 3.0 of later zijn ontwikkeld. Hieronder ziet u een voorbeeld van de header Plugin-Class:

Plugin-Class: org.eclipse.foo.FooPlugin