Intestazioni di manifest di insieme OSGi

Versione 3.1 - Ultima revisione 20 giugno, 2005

Un insieme può riportare le proprie informazioni descrittive nel file manifest denominato META-INF/MANIFEST.MF. La specifica del framework OSGi R4 definisce una serie di intestazioni manifest, quali Export-Package e Bundle-Classpath, utilizzate dagli sviluppatori di insiemi per fornire informazioni descrittive su un insieme. Il framework OSGi di Eclipse implementa la specifica completa del framework OSGi R4 e tutti i servizi del framework principale. Il framework principale OSGi R4 include i seguenti elementi:

Nella specifica OSGi R4 sono definiti numerosi servizi facoltativi. I servizi facoltativi non sono inclusi nell'implementazione del framework OSGi di Eclipse. Per informazioni sulle intestazioni OSGi R4 manifest e servizi, fare riferimento alla pagina OSGi specifications.

Intestazioni di manifest di insieme Eclipse

Il framework OSGi di Eclipse supporta numerose altre intestazioni e direttive del manifest di insieme. Uno sviluppatore di insiemi può utilizzare queste ulteriori intestazioni e direttive per trarre vantaggio da alcune funzioni aggiuntive del framework OSGi di Eclipse che non sono specificate come parte del framework OSGi R4 standard.

Ulteriori direttive di Export-Package

Il framework OSGi di Eclipse supporta ulteriori direttive sull'intestazione Export-Package. Queste direttive sono utilizzate per specificare le regole sulle limitazioni di accesso di un pacchetto esportato. Per configurare il framework OSGi di Eclipse per applicare le regole sulle limitazioni di accesso al runtime, fare riferimento a osgi.resolverMode.

Direttiva x-internal

La direttiva x-internal può essere utilizzata in un'intestazione Export-Package per specificare se il pacchetto è di tipo interno. PDE (Plug-in Development Environment) sconsiglia l'utilizzo di un pacchetto interno da parte di altri insiemi. Se non è stata specificata la direttiva x-internal, viene utilizzato il valore predefinito 'false'. La direttiva x-internal deve utilizzare la seguente sintassi:

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

Di seguito è riportato un esempio di direttiva x-internal:

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

Direttiva x-friends

La direttiva x-friends può essere utilizzata in un'intestazione Export-Package per specificare un elenco di insiemi ai quali è consentito l'accesso al pacchetto. PDE (Plug-in Development Environment) sconsiglia l'utilizzo di un pacchetto da parte di altri insiemi. La direttiva x-friends deve utilizzare la seguente sintassi:

x-friends ::= '"' ( target-bundle ) ( ',' target-bundle ) * '"'
target-bundle ::= un nome simbolico di insieme

Di seguito è riportato un esempio di direttiva x-friends:

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

L'esempio specifica che solo agli insiemi org.eclipse.foo.friend1 e org.eclipse.foo.friend2 dovrebbe essere permesso l'utilizzo del pacchetto org.eclipse.foo.formyfriends. Il pacchetto x-internal ha la priorità sulla direttiva x-friends. Se la direttiva x-internal specifica 'true', PDE sconsiglierà l'utilizzo del pacchetto da parte di altri insiemi, anche se questi sono specificati come amici (friend).

The Eclipse-LazyStart Header

The Eclipse-LazyStart header is used to specify if a bundle should be started automatically before the first class or resource is accessed from that bundle. This feature allows Eclipse to activate bundles lazily the first time they are needed. Utilizzando questo modello, Eclipse può essere avviato con il minor numero possibile di insiemi. The Eclipse-LazyStart header must use the following syntax:

Eclipse-LazyStart ::= ( 'true' | 'false' ) ( ';' 'exceptions' '=' '"' exceptions-list '"' ) ?
exceptions-list ::= un elenco di pacchetti separati da virgole ','

L'attributo 'exceptions' viene utilizzato per specificare un elenco di pacchetti che non attivano l'insieme quando si caricano le relative classi o risorse. If the Eclipse-LazyStart header is not defined in the bundle manifest then a default value of 'false' is used. The following is an example of the Eclipse-LazyStart header:

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

L'esempio specifica che questo insieme deve essere attivato per qualsiasi classe o risorsa caricata dall'insieme, tranne le classi e le risorse nei pacchetti 'org.eclipse.foo1' e 'org.eclipse.foo2'.

The Eclipse-AutoStart header has been deprecated in Eclipse 3.2. The Eclipse-LazyStart header should be used instead.

Intestazione Eclipse-PlatformFilter

Eclipse-PlatformFilter viene utilizzata per specificare un filtro di piattaforma per un insieme. Un filtro di piattaforma deve essere valutato "true" in una piattaforma in esecuzione affinché sia possibile risolvere l'insieme. L'intestazione Eclipse-PlatformFilter deve utilizzare la seguente sintassi:

Eclipse-PlatformFilter ::= una stringa di filtro LDAP valida

Il framework supporta il filtro sulle seguenti proprietà di sistema:

Di seguito è riportato un esempio di intestazione Eclipse-PlatformFilter:

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

Questo esempio specifica che questo insieme può essere risolto solo se le proprietà della piattaforma sono osgi.ws=win32, osgi.os=win32 e osgi.arch=x86. In altri termini, una piattaforma in esecuzione su un'architettura x86, che utilizza un sistema operativo win32 e un sistema di finestre win32.

Intestazione Eclipse-BuddyPolicy

L'intestazione Eclipse-BuddyPolicy viene utilizzata per specificare i criteri di caricamento di un insieme (buddy loading). L'intestazione Eclipse-BuddyPolicy deve utilizzare la seguente sintassi:

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

Di seguito è riportato un esempio di intestazione Eclipse-BuddyPolicy:

Eclipse-BuddyPolicy: dependent

Intestazione Eclipse-RegisterBuddy

L'intestazione Eclipse-RegisterBuddy viene utilizzata per specificare un elenco di insiemi per i quali questo insieme è registrato come buddy. L'intestazione Eclipse-RegisterBuddy deve utilizzare la seguente sintassi:

Eclipse-RegisterBuddy ::= ( target-bundle ) ( ',' target-bundle ) *
target-bundle ::= un nome simbolico di insieme

Di seguito è riportato un esempio di intestazione Eclipse-RegisterBuddy:

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

Intestazione Eclipse-ExtensibleAPI

Eclipse-ExtensibleAPI viene utilizzato per specificare se un insieme host consente agli insiemi di frammento di aggiungere altre API all'host. Questa intestazione dovrebbe essere utilizzata se un insieme host vuole consentire ai frammenti di aggiungere ulteriori pacchetti all'API dell'host. Se non è stata specificata questa intestazione, viene utilizzato il valore predefinito 'false'. L'intestazione Eclipse-ExtensibleAPI deve utilizzare la seguente sintassi:

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

Di seguito è riportato un esempio di intestazione Eclipse-ExtensibleAPI:

Eclipse-ExtensibleAPI: true

The Eclipse-GenericCapabilty Header

The Eclipse-GenericCapability header is used to specify a generic capability of a bundle. Generic capabilities can be used to describe features of your bundle which can be required by other bundles in the system (using the Eclipse-GenericRequire header). Generic capabilities are given a name and a capability type. Capability types are defined by the bundle which is offering the capability. Capabilities can also have a set of typed matching attributes which are used to match against when resolving Eclipse-GenericRequire headers. Matching attributes may be one of the following types; [string | version | uri | long | double | set]. The set type can be used to define a set of strings as a comma separated list of strings. The Eclipse-GenericCapability header must use the following syntax:

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

The following is an example of the Eclipse-GenericCapabilty header that could be used to specify a bundle with an OSGi service org.acme.stuff.SomeService implementation:

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

The Eclipse-GenericRequire Header

The Eclipse-GenericRequire header is used to specify a requirement on ageneric capability which is offered by another bundle (using the Eclipse-GenericCapability header). Generic requirements are given a name and a capability type. Capability types are defined by the bundle which is offering the capability. Generic requirements can specify an LDAP filter string which is used as a selection filter to resolve against matching generic capabilities. The Eclipse-GenericRequire header must use the following syntax:

  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 )

The following is an example of the Eclipse-GenericRequire header that could be used to specify a bundle that depends on an OSGi service org.acme.stuff.SomeService implementation:

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

Generic Aliases

The osgi.genericAliases option can be used to map existing OSGi manifest headers onto Eclipse-GenericCapability and Eclipse-GenericRequire manifest headers. For example, consider the following manifest headers

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

These headers can be mapped to Eclipse-GenericCapability and Eclipse-GenericRequire headers using the following property:

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

Under the covers this would translate into the following generic headers:

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

Intestazione Plugin-Class

L'intestazione Plugin-Class è utilizzata solo per supportare i plugin sviluppati per la piattaforma Eclipse 2.1. This header is used to specify a class name that will be used to activate a plug-in using the old Eclipse 2.1 activation model. New bundles developed for Eclipse 3.0 or greater should not use this header. Di seguito è riportato un esempio di intestazione Plugin-Class:

Plugin-Class: org.eclipse.foo.FooPlugin