Cabeçalhos de Manifesto de Agrupamento OSGi

Versão 3.1 - Revista pela última vez a 20 de Junho, 2005

Um agrupamento pode conter informações descritivas sobre si próprio no ficheiro de manifesto com o nome META-INF/MANIFEST.MF. A especificação de Enquadramento OSGi R4 define um conjunto de cabeçalhos de manifesto como Export-Package e Bundle-Classpath, que os programadores de agrupamentos utilizam para fornecer informações descritivas sobre um agrupamento. O Enquadramento OSGi do Eclipse implementa a especificação Enquadramento OSGi R4 completa e todos os serviços Core Framework. Os serviços OSGi R4 Core Framework incluem o seguinte:

Existem vários serviços opcionais definidos na especificação OSGi. Os serviços opcionais não estão incluídos na implementação de Enquadramento ESGI Eclipse. Para obter informações sobre os cabeçalhos de manifesto e serviços do OSGi R4, consulte a secção Especificações de OSGi.

Cabeçalhos de manifesto de agrupamento Eclipse

O Enquadramento OSGi Eclipse suporta vários cabeçalhos de manifesto de agrupamento e directivas adicionais. Um programador de agrupamentos poderá utilizar cabeçalhos e directivas opcionais para tirar vantagem de algumas funções adicionais do Enquadramento OSGi Eclipse, que não estão especificadas como parte de um Enquadramento OSGi R4 padrão.

Directivas Export-Package Adicionais

O Enquadramento OSGi Eclipse suporta directivas adicionais no cabeçalho Export-Package. Estas directivas são utilizadas para especificar as regras de restrição de acesso de um pacote exportado. Consulte osgi.resolverMode para configurar o Enquadramento OSGi Eclipse a forçar as regras de restrição de acesso na área de trabalho.

A Directiva x-internal

A directiva x-internal pode ser utilizada no cabeçalho Export-Package para especificar se o pacote é interno. O Ambiente de Programação de Plug-ins irá desencorajar outros agrupamentos a utilizarem um pacote interno. Se a directiva x-internal não for especificada, então é utilizado um valor predefinido "false". A directiva x-internal tem de seguir a sintaxe que se segue:

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

A seguir encontra-se um exemplo de uma directiva x-internal:

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

A Directiva x-friends

A directiva x-friends pode ser utilizada no cabeçalho Export-Package para especificar uma lista de agrupamentos que têm acesso permitido ao pacote. O Ambiente de Programação de Plug-ins irá desencorajar outros agrupamentos a utilizarem o pacote. A directiva x-friends tem de seguir a sintaxe que se segue:

x-friends ::= '"' ( target-bundle ) ( ',' target-bundle ) * '"'
target-bundle ::= a bundle symbolic name

A seguir encontra-se um exemplo da directiva x-friends:

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

O exemplo especifica que apenas os agrupamentos org.eclipse.foo.friend1 e org.eclipse.foo.friend2 devem ser incentivados a utilizar o pacote org.eclipse.foo.formyfriends. O pacote x-internal tem prioridade sobre a directiva x-friends. Se a directiva x-internal especificar o valor "true", então o Ambiente de Programação de Plug-ins irá desencorajar todos os agrupamentos de utilizarem o pacote, ainda que esteja especificado como um amigo.

O Cabeçalho Eclipse-LazyStart

O cabeçalho Eclipse-LazyStart é utilizado para especificar se um agrupamento deverá ser iniciado automaticamente antes de a primeira classe ou recurso ser acedido a partir desse agrupamento. Esta função permite que o Eclipse active os agrupamento lazily a primeira vez que foram necessários. Utilizando este modelo, o Eclipse pode arrancar com a menor quantidade de agrupamentos activos possível. O cabeçalho Eclipse-LazyStart terá de utilizar a seguinte sintaxe:

Eclipse-LazyStart ::= ( 'true' | 'false' ) ( ';' 'exceptions' '=' '"'
exceptions-list '"' ) ?
exceptions-list ::= a comma ',' separated list of packages

O atributo "exceptions" é utilizado para especificar uma lista de pacotes, que não pode causar a activação do agrupamento quando as classes ou recursos forem transferidos a partir do mesmo. Se o cabeçalho Eclipse-LazyStart não estiver definido no manifesto do agrupamento, será utilizado o valor predefinido "false". A seguir encontra-se um exemplo do cabeçalho Eclipse-LazyStart:

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

O exemplo especifica que este agrupamento tem de ser activado para quaisquer classes ou recursos que forem transferidos a partir deste agrupamento, excepto as classes e recursos nos pacotes "org.eclipse.foo1" e "org.eclipse.foo2".

O cabeçalho Eclipse-AutoStart tornou-se obsoleto no Eclipse 3.2. O cabeçalho Eclipse-LazyStart deverá ser utilizado como alternativa.

O Cabeçalho Eclipse-PlatformFilter

O cabeçalho Eclipse-PlatformFilter é utilizado para especificar um filtro de plataforma para um agrupamento. Um filtro de plataforma deve avaliar-se como true numa plataforma em execução para que seja permitido ao agrupamento ser processado. O cabeçalho Eclipse-PlatformFilter deve ter a seguinte sintaxe:

Eclipse-PlatformFilter ::= a valid LDAP filter string

O Enquadramento suporta a filtração nas seguintes propriedades do sistema:

A seguir encontra-se um exemplo do cabeçalho Eclipse-PlatformFilter:

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

Este exemplo especifica que este agrupamento apenas pode ser processador se as propriedades da plataforma forem osgi.ws=win32 e osgi.os=win32 and osgi.arch=x86. Por outras palavras, uma plataforma com arquitectura x86, utilizando um sistema operativo win32 e um sistema de janelas win32.

O Cabeçalho Eclipse-BuddyPolicy

O cabeçalho Eclipse-BuddyPolicy é utilizado para especificar as políticas de carregamento de classes amigas para um agrupamento. O cabeçalho Eclipse-BuddyPolicy tem de utilizar a seguinte sintaxe:

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

A seguir encontra-se um exemplo do cabeçalho Eclipse-BuddyPolicy:

Eclipse-BuddyPolicy: dependent

O Cabeçalho Eclipse-RegisterBuddy

O cabeçalho Eclipse-RegisterBuddy é utilizado para especificar uma lista de agrupamentos na qual este agrupamento é um amigo registado. O cabeçalho Eclipse-RegisterBuddy deve ter a seguinte sintaxe:

Eclipse-RegisterBuddy ::= ( target-bundle ) ( ',' target-bundle ) *
target-bundle ::= a bundle symbolic name

A seguir encontra-se um exemplo do cabeçalho Eclipse-RegisterBuddy:

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

O Cabeçalho Eclipse-ExtensibleAPI

O cabeçalho Eclipse-ExtensibleAPI é utilizado para especificar se um agrupamento do sistema central permite aos agrupamentos de fragmentos adicionar a API adicionar ao sistema central. Este cabeçalho deve ser utilizado se um agrupamento do sistema central quiser permitir os fragmentos para adicionar pacotes adicionais à API do sistema central. Se este cabeçalho não estiver especificado, então é utilizado o valor predefinido "false". O cabeçalho Eclipse-ExtensibleAPI tem de utilizar a seguinte sintaxe:

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

A seguir encontra-se um exemplo do cabeçalho Eclipse-ExtensibleAPI:

Eclipse-ExtensibleAPI: true

O Cabeçalho Eclipse-GenericCapabilty

O cabeçalho Eclipse-GenericCapability é utilizado para especificar uma capacidade genérica de um agrupamento. As capacidades genéricas podem ser utilizadas para descrever funções do agrupamento que podem ser requeridas por outros agrupamentos contidos no sistema (através da utilização do cabeçalho Eclipse-GenericRequire). É atribuído um nome e um tipo de capacidade às capacidades genéricas. Os tipos de capacidades são definidos pelo agrupamento que oferece essa capacidade. As capacidades podem também conter um conjunto de atributos correspondentes tipificados que são utilizados para corresponder a estas capacidades ao processar os cabeçalhos Eclipse-GenericRequire. Os atributos correspondentes podem ser de um dos seguintes tipos; [string | version | uri | long | double | set]. O tipo definido pode ser utilizado para definir um conjunto de cadeias como sendo uma lista de cadeias separadas por vírgulas. O cabeçalho Eclipse-GenericCapability terá de utilizar a seguinte sintaxe:

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

Em seguida é apresentado um exemplo do cabeçalho Eclipse-GenericCapabilty que pode ser utilizado para especificar um agrupamento através da implementação org.acme.stuff.SomeService do serviço OSGi:

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

O Cabeçalho Eclipse-GenericRequire

O cabeçalho Eclipse-GenericRequire é utilizado para especificar um requisito de uma capacidade não genérica que é oferecida por outro agrupamento (através da utilização do cabeçalho Eclipse-GenericCapability). É atribuído um nome e um tipo de capacidade aos requisitos genéricos. Os tipos de capacidades são definidos pelo agrupamento que oferece essa capacidade. Os requisitos genéricos podem especificar uma cadeia de filtros LDAP utilizada como sendo um filtro de selecção que processa em relação às capacidades genéricas correspondentes. O cabeçalho Eclipse-GenericRequire terá de utilizar a seguinte sintaxe:

  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 )

Em seguida é apresentado um exemplo do cabeçalho Eclipse-GenericRequire que pode ser utilizado para especificar um agrupamento que depende de uma implementação org.acme.stuff.SomeService do serviço OSGi:

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

Nomes Alternativos Genéricos

A opção osgi.genericAliases pode ser utilizada para correlacionar cabeçalhos de manifestos OSGi existentes com cabeçalhos de manifestos Eclipse-GenericCapability e Eclipse-GenericRequire. Por exemplo, considere os seguintes cabeçalhos de manifestos

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

Estes cabeçalhos podem ser correlacionados com cabeçalhos Eclipse-GenericCapability e Eclipse-GenericRequire, através da utilização da seguinte propriedade:

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

Abaixo da superfície, isto seria traduzido para os seguintes cabeçalhos genéricos:

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

O Cabeçalho Plugin-Class

O cabeçalho Plugin-Class é utilizado apenas para suportar os plug-ins desenvolvidos para a plataforma Eclipse 2.1. Este cabeçalho é utilizado para especificar um nome de classe que será utilizado para activar um plug-in através da utilização do antigo modelo de activação do Eclipse 2.1. Os novos agrupamentos desenvolvidos para o Eclipse 3.0 ou versões posteriores não deverão utilizar este cabeçalho. A seguir encontra-se um exemplo do cabeçalho Plugin-Class:

Plugin-Class: org.eclipse.foo.FooPlugin