Záhlaví manifestu balíku OSGi

Verze 3.1 - Poslední revize 20.června 2005

Balík může obsahovat popisné informace o sobě, uložené v souboru s manifestem nazvaném META-INF/MANIFEST.MF. Specifikace OSGi R4 Framework definuje sadu záhlaví manifestu, např. Export-Package a Bundle-Classpath, která mohou vývojáři balíků používat, když potřebují dodat popisné informace ke konkrétnímu balíku. OSGi Framework platformy Eclipse implementuje kompletní specifikaci OSGi R4 Framework a všechny služby jádra struktury Framework. Mezi služby jádra struktury OSGi R4 Framework patří:

V rámci specifikace OSGi R4 je definována i řada volitelných služeb. Volitelné služby nejsou součástí implementace struktury OSGi Framework platformy Eclipse. Další informace o záhlavích manifestu OSGi R4 a službách najdete pod tématem Specifikace OSGi.

Záhlaví manifestu balíku Eclipse

Struktura OSGi Framework platformy Eclipse podporuje celou řadu dalších direktiv i záhlaví manifestu balíku. Tato další záhlaví a direktivy jsou k dispozici vývojářům, kteří tak mohou těžit z dalších funkcí struktury OSGi Framework platformy Eclipse, které nejsou specifikovány jako součást standardní struktury OSGi R4 Framework.

Další direktivy Export-Package

Struktura OSGi Framework platformy Eclipse podporuje další direktivy pro záhlaví Export-Package. Tyto direktivy se používají k určení pravidel omezení přístupu exportovaného balíčku. Viz téma osgi.resolverMode, kde najdete informace o konfiguraci struktury OSGi Framework platformy Eclipse pro vynucení pravidel omezení přístupu v době běhu programu.

Direktiva x-internal

Pomocí direktivy x-internal je možné v záhlaví Export-Package určit, zda je balíček interní. Vývojové prostředí modulů plug-in bude další balíky odrazovat od toho, aby interní balíček používaly. Pokud direktiva x-internal není zadána, použije se výchozí hodnota 'false'. Direktiva x-internal má následující syntaxi:

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

Následuje příklad direktivy x-internal:

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

Direktiva x-friends

Pomocí direktivy x-friends je možné v záhlaví Export-Package určit seznam balíků, které mají k balíčku povolen přístup. Vývojové prostředí modulů plug-in bude ostatní balíky odrazovat od toho, aby tento balíček používaly. Direktiva x-friends má následující syntaxi:

x-friends ::= '"' ( cílový-balík ) ( ',' cílový-balík ) * '"'
cílový-balík ::= symbolický název balíku

Následuje příklad direktivy x-friends:

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

Výše uvedený příklad ukazuje, že balíček org.eclipse.foo.formyfriends by měly používat pouze balíky org.eclispe.foo.friend1 a org.eclipse.foo.friend2. Direktiva x-internal má vyšší prioritu než direktiva x-friends. Pokud je direktiva x-internal nastavena na 'true', pak bude vývojové prostředí modulů plug-in všechny balíky od používání tohoto balíčku odrazovat, a to i v případě, že jsou určeny jako friend.

Záhlaví Eclipse-LazyStart

Záhlaví Eclipse-LazyStart určuje, zda se má balík automaticky spouštět před tím, než dojde k prvnímu přístupu ke třídě nebo k prostředku z daného balíku. Díky této funkci může platforma Eclipse aktivovat balíky pomalu a ve chvíli, kdy jsou poprvé potřeba. Při použití tohoto modelu se může Eclipse spouštět s nejmenším možným počtem aktivních balíků. Záhlaví Eclipse-LazyStart musí mít následující syntaxi:

Eclipse-LazyStart ::= ( 'true' | 'false' ) ( ';' 'exceptions' '=' '"' exceptions-list '"' ) ?
exceptions-list ::= čárkou ',' oddělený seznam balíčků

Atribut 'exceptions' se používá k určení seznamu balíčků, které nesmí způsobit aktivaci balíku ve chvíli, kdy se z nich načítají třídy nebo prostředky. Pokud záhlaví Eclipse-LazyStart není v manifestu balíku definováno, použije se výchozí hodnota 'false'. Následuje příklad záhlaví Eclipse-LazyStart:

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

Příklad určuje, že tento balík musí být aktivován pro všechny třídy a prostředky načtené z tohoto balíku, s výjimkou tříd a prostředků v balíčcích 'org.eclipse.foo1' a 'org.eclipse.foo2'.

Záhlaví Eclipse-AutoStart bylo v platformě Eclipse 3.2 nepřístupné. Namísto něj by se mělo použít záhlaví Eclipse-LazyStart.

Záhlaví Eclipse-PlatformFilter

Eclipse-PlatformFilter se používá k určení filtru platformy pro balík. Pokud se má povolit rozeznání daného balíku, filtr platformy musí být u spuštěné platformy vyhodnocen jako true. Záhlaví Eclipse-PlatformFilter má následující syntaxi:

Eclipse-PlatformFilter ::= platný řetězec filtru LDAP

Framework podporuje filtrování na následujících vlastnostech systému:

Následuje příklad záhlaví Eclipse-PlatformFilter:

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

Tento příklad určuje, že daný balík může být vyřešen pouze v případě, že vlastnosti platformy jsou osgi.ws=win32 a osgi.os=win32 a osgi.arch=x86. Jinými slovy, musí se jednat o platformu běžící na architektuře x86, používající operační systém win32 a systém oken win32.

Záhlaví Eclipse-BuddyPolicy

Záhlaví Eclipse-BuddyPolicy se používá k určení zásad načítání tříd buddy pro daný balík. Záhlaví Eclipse-BuddyPolicy má následující syntaxi:

Eclipse-BuddyPolicy ::= ( název-zásady ) ( ',' název-zásady ) *
název-zásady ::= ( 'dependent' | 'global' | 'registered' |
                  'app' | 'ext' | 'boot' | 'parent' )

Následuje příklad záhlaví Eclipse-BuddyPolicy:

Eclipse-BuddyPolicy: dependent

Záhlaví Eclipse-RegisterBuddy

Záhlaví Eclipse-RegisterBuddy se používá k určení seznamu balíků, pro který bude tento balík registrovaným buddy. Záhlaví Eclipse-RegisterBuddy má následující syntaxi:

Eclipse-RegisterBuddy ::= ( cílový-balík ) ( ',' cílový-balík ) *
cílový-balík ::= symbolický název balíku

Následuje příklad záhlaví Eclipse-RegisterBuddy:

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

Záhlaví Eclipse-ExtensibleAPI

Eclipse-ExtensibleAPI určuje, zda hostitelský balík umožňuje dílčím balíkům přidávat další rozhraní API do hostitele. Toto záhlaví by se mělo použít v případě, kdy hostitelský balík chce povolit dílčím balíkům přidávat další balíčky do rozhraní API hostitele. Pokud toto záhlaví není zadáno, použije se výchozí hodnota 'false'. Záhlaví Eclipse-ExtensibleAPI má následující syntaxi:

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

Následuje příklad záhlaví Eclipse-ExtensibleAPI:

Eclipse-ExtensibleAPI: true

Záhlaví Eclipse-GenericCapabilty

Záhlaví Eclipse-GenericCapability se používá k určování generické schopnosti balíku. Generické schopnosti mohou být použity k popisu funkcí vašeho balíku, který může být vyžadován jinými balíky v systému (využívajícími záhlaví Eclipse-GenericRequire). Generickým schopnostem je určen název a typ. Typy schopností jsou definovány balíkem, který nabízí danou schopnost. Schopnosti mohou mít také množinu typových porovnávacích atributů, které se používají k porovnání při řešení záhlaví Eclipse-GenericRequire. Porovnávací atributy mohou odpovídat jednomu z následujících typů: [string | version | uri | long | double | set]. Nastavený typ lze použít k definování množiny řetězců ve formě čárkami odděleného seznamu řetězců. Záhlaví Eclipse-GenericCapability musí mít následující syntaxi:

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

Následuje příklad záhlaví Eclipse-GenericCapabilty, které lze použít k určení balíku s implementací org.acme.stuff.SomeService služby OSGi:

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

Záhlaví Eclipse-GenericRequire

Záhlaví Eclipse-GenericRequire se používá k určení požadavku na generickou schopnost, kterou nabízí jiný balík (se záhlavím Eclipse-GenericCapability). Generické požadavky mají určen název a typ schopnosti. Typy schopností jsou definovány balíkem, který nabízí danou schopnost. Generické požadavky mohou určovat řetězec filtru LDAP používaný jako filtr pro výběr k řešení dle odpovídajících generických schopností. Záhlaví Eclipse-GenericRequire musí mít následující syntaxi:

  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 )

Následuje příklad záhlaví Eclipse-GenericRequire, které lze použít k určení balíku závisejícího na implementaci org.acme.stuff.SomeService služby OSGi:

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

Generické aliasy

Volba osgi.genericAliases může být použita k mapování stávajících záhlaví manifestů OSGi na záhlaví manifestů Eclipse-GenericCapability a Eclipse-GenericRequire. Prohlédněte si například následující záhlaví manifestů:

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

Tato záhlaví mohou být mapována na záhlaví Eclipse-GenericCapability a Eclipse-GenericRequire s použitím následující vlastnosti:

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

Pod obálkami by se překládala jako následující generická záhlaví:

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

Záhlaví Plugin-Class

Záhlaví Plugin-Class se používá pouze pro podporu modulů plug-in vyvinutých pro platformu Eclipse 2.1. Toto záhlaví se používá k určení názvu třídy, která bude použita k aktivaci modulu plug-in za použití starého modelu aktivace platformy Eclipse 2.1. Nové balíky vyvinuté pro platformu Eclipse verze 3.0 nebo vyšší by toto záhlaví neměly používat. Následuje příklad záhlaví Plugin-Class:

Plugin-Class: org.eclipse.foo.FooPlugin