Toptekster i OSGi-bundtmanifester

Version 3.1 - Sidst revideret 20. juni 2005

Et bundt kan indeholde beskrivende oplysninger om sig selv i manifestfilen ved navn META-INF/MANIFEST.MF. OSGi R4 Framework-specifikationen definerer et sæt manifesttoptekster som f.eks. Export-Package og Bundle-Classpath, som bundtudviklere bruger til at beskrive et bundt. Eclipse OSGi Framework implementerer hele OSGi R4 Framework-specifikationen og alle Core Framework-serviceprogrammerne. OSGi R4 Core Framework-serviceprogrammerne omfatter følgende:

Der er defineret et antal valgfri serviceprogrammer i OSGi R4-specifikationen. De valgfri serviceprogrammer er ikke inkluderet i Eclipse OSGi Framework-implementeringen. Der er oplysninger om OSGi R4-manifesttoptekster og -serviceprogrammer i OSGi-specifikationer.

Toptekster i Eclipse-bundtmanifester

Eclipse OSGi Framework understøtter en række ekstra bundtmanifesttoptekster og -direktiver. En bundtudvikler kan bruge de eksterne toptekster og direktiver til at udnytte nogle yderligere funktioner i Eclipse OSGi Framework, som ikke er specificeret som en del af en standard OSGi R4 Framework.

Yderligere Export-Package-direktiver

Eclipse OSGi Framework understøtter yderligere direktiver for topteksten Export-Package. Direktiverne bruges til at angive adgangsbetingelsesreglerne for en eksporteret pakke. Afsnittet osgi.resolverMode indeholder oplysninger om konfiguration af Eclipse OSGi Framework til at håndhæve adgangsbetingelsesreglerne ved runtime.

Direktivet x-internal

Direktivet x-internal kan bruges i en Export-Package-toptekst til at angive, om pakken er intern. Plugin-udviklingsmiljøet forhindrer, at andre bundter bruger en intern pakke. Hvis direktivet x-internal ikke angives, bruges standardværdien 'false'. Direktivet x-internal skal følge denne syntaks:

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

Følgende er et eksempel på direktivet x-internal:

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

Direktivet x-friends

Direktivet x-friends kan bruges i en Export-Package-toptekst til at angive en liste med bundter, som har adgang til pakken. Plugin-udviklingsmiljøet forhindrer, at andre bundter bruger pakken. Direktivet x-friends skal følge denne syntaks:

x-friends ::= '"' ( målbundt ) ( ',' målbundt ) * '"'
målbundt ::= et symbolsk bundtnavn

Følgende er et eksempel på direktivet x-friends:

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

Eksemplet angiver, at kun bundterne org.eclipse.foo.friend1 og org.eclipse.foo.friend2 må bruge pakken org.eclipse.foo.formyfriends. Pakken x-internal har højere prioritet end direktivet x-friends. Hvis direktivet x-internal angiver 'true', forhindrer plugin-udviklingsmiljøet alle bundter i at blive brugt, selvom de er angivet som venner.

Topteksten Eclipse-LazyStart

Topteksten Eclipse-LazyStart bruges til at angive, om et bundt skal startes automatisk, før der oprettes adgang til den første klasse eller ressource fra bundtet. Denne funktion giver Eclipse mulighed for at aktivere bundter efter behov, første gang der er brug for dem. Ved at bruge denne model kan Eclipse starte med så få aktive bundter som muligt. Topteksten Eclipse-LazyStart skal følge denne syntaks:

Eclipse-LazyStart ::= ( 'true' | 'false' ) ( ';' 'exceptions' '=' '"' exceptions-list '"' ) ?
undtagelsesliste ::= en kommasepareret liste af pakker

Attributten 'exceptions' bruges til at angive en liste med pakker, som ikke må få bundtet til at blive aktiveret, når der indlæses klasser eller ressourcer fra dem. Hvis topteksten Eclipse-LazyStart ikke er defineret i bundtmanifestet, bruges standardværdien 'false'. Følgende er et eksempel på topteksten Eclipse-LazyStart:

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

Eksemplet angiver, at bundtet skal aktiveres for de klasser eller ressourcer, der indlæses fra bundtet, bortset fra klasserne og ressourcerne i pakkerne 'org.eclipse.foo1' og 'org.eclipse.foo2'.

Topteksten Eclipse-AutoStart er forældet i Eclipse 3.2. Topteksten Eclipse-LazyStart bør anvendes i stedet for.

Topteksten Eclipse-PlatformFilter

Eclipse-PlatformFilter bruges til at angive et platformsfilter for et bundt. Et platformsfilter skal evalueres til true på en igangværende platform, for at et bundt må behandles. Topteksten Eclipse-PlatformFilter skal følge denne syntaks:

Eclipse-PlatformFilter ::= en gyldig LDAP-filterstreng

Strukturen understøtter filtrering af følgende systemegenskaber:

Følgende er et eksempel på topteksten Eclipse-PlatformFilter:

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

Eksemplet angiver, at bundtet kun må behandles, hvis platformsegenskaberne er osgi.ws=win32 og osgi.os=win32 og osgi.arch=x86. Det vil med andre ord sige en platform, der afvikles på en x86-arkitektur og bruger et win32-styresystem og win32-vinduessystemet.

Topteksten Eclipse-BuddyPolicy

Topteksten Eclipse-BuddyPolicy bruges til at angive buddy-klasseindlæsningspolitikkerne for et bundt. Topteksten Eclipse-BuddyPolicy skal følge denne syntaks:

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

Følgende er et eksempel på topteksten Eclipse-BuddyPolicy:

Eclipse-BuddyPolicy: dependent

Topteksten Eclipse-RegisterBuddy

Topteksten Eclipse-RegisterBuddy bruges til at angive en liste med bundter, som dette bundt er en registreret buddy for. Topteksten Eclipse-RegisterBuddy skal følge denne syntaks:

Eclipse-RegisterBuddy ::= ( målbundt ) ( ',' målbundt ) *
målbundt ::= et symbolsk bundtnavn

Følgende er et eksempel på topteksten Eclipse-RegisterBuddy:

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

Topteksten Eclipse-ExtensibleAPI

Eclipse-ExtensibleAPI bruges til at angive, om et værtsbundt tillader, at fragmentbundter tilføjer yderligere API til værten. Topteksten skal bruges, hvis et værtsbundt vil tillade, at fragmenter tilføjer flere pakker til værtens API. Hvis topteksten ikke angives, bruges standardværdien 'false'. Topteksten Eclipse-ExtensibleAPI skal følge denne syntaks:

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

Følgende er et eksempel på topteksten Eclipse-ExtensibleAPI:

Eclipse-ExtensibleAPI: true

Topteksten Eclipse-GenericCapabilty

Topteksten Eclipse-GenericCapability bruges til at angive en generisk mulighed for et bundt. Generiske muligheder kan anvendes til at beskrive funktioner for et bundt, der kan være påkrævet af andre bundter på systemet (vha. topteksten Eclipse-GenericRequire). Generiske muligheder får et navn og en mulighedstype. Mulighedstyper defineres af bundet, der tilbyder muligheden. Muligheder kan også have et sæt indtastede matchende attributter, der anvendes til at matche mod de opløsende Eclipse-GenericRequire-toptekster. Matchende attributter kan have en af følgende typer [string | version | uri | long | double | set]. Sættypen kan anvendes til at definere et sæt strenge som en kommasepareret liste med strenge. Topteksten Eclipse-GenericCapability skal anvende følgende syntaks:

  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] )

Det følgende er et eksempel på en Eclipse-GenericCapabilty-toptekst, der kan anvendes til at angive et bundt med en implementering af et OSGi-serviceprogram org.acme.stuff.SomeService:

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

Topteksten Eclipse-GenericRequire

Topteksten Eclipse-GenericRequire anvendes til at angive et krav på en generisk mulighed, der tilbydes af et andet bundt (vha. topteksten Eclipse-GenericCapability). Generiske krav får et navn og en mulighedstype. Mulighedstyper defineres af bundtet, der tilbyder muligheden. Generiske krav kan angive en LDAP-filterstreng, der anvendes som et valgfilter til at opløse mod matchende generiske muligheder. Topteksten Eclipse-GenericRequire skal følge denne syntaks:

  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 )

Det følgende er et eksempel på en Eclipse-GenericCapabilty-toptekst, der kan anvendes til at angive et bundt med en implementering af et OSGi-serviceprogram org.acme.stuff.SomeService:

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

Generiske aliaser

Indstillingen osgi.genericAliases kan anvendes til at tilknytte eksisterende OSGi-manifesttoptekster vha. mapping til Eclipse-GenericCapability- og Eclipse-GenericRequire-manifesttoptekster. Se f.eks. på følgende manifesttoptekster:

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

Topteksterne kan knyttes til Eclipse-GenericCapability- og Eclipse-GenericRequire-toptekster vha. følgende egenskab:

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

Under overfladen konverteres dette til følgende generiske toptekster:

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

Topteksten Plugin-Class

Topteksten Plugin-Class bruges kun til at understøtte plugins, der er udviklet til Eclipse 2.1-platformen. Topteksten bruges til at angive et klassenavn, der bliver brugt til at aktivere en plugin med den gamle aktiveringsmodel i Eclipse 2.1. Nye bundter, der er udviklet til Eclipse 3.0 eller nyere, skal ikke bruge denne toptekst. Følgende er et eksempel på topteksten Plugin-Class:

Plugin-Class: org.eclipse.foo.FooPlugin