Cabeçalhos de Manifesto do Pacote Configurável OSGi

Versão 3.1 - Última revisão em 20 de junho de 2005

Um pacote configurável pode transportar informações descritivas sobre ele mesmo no arquivo de manifesto denominado META-INF/MANIFEST.MF. A especificação OSGi R4 Framework define um conjunto de cabeçalhos de manifesto, como por exemplo Pacote de Exportação e Caminho de Classe do Pacote Configurável, que os desenvolvedores de pacote configurável utilizam para fornecer informações descritivas sobre um pacote configurável. O Eclipse OSGi Framework implementa a especificação completa do OSGi R4 Framework e todos os serviços do Core Framework. Os serviços do OSGi R4 Core Framework incluem o seguinte:

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

Cabeçalhos de Manifesto do Pacote Configurável do Eclipse

O Eclipse OSGi Framework suporta vários cabeçalhos e diretivas de manifesto do pacote configurável adicional. Um desenvolvedor de pacote configurável pode utilizar esses cabeçalhos e diretivas para se beneficiar de alguns recursos adicionais do Eclipse OSGi Framework, os quais não são especificados como parte de um OSGi R4 Framework padrão.

Diretivas Adicionais do Pacote de Exportação

O Eclipse OSGi Framework suporta diretivas adicionais no cabeçalho Pacote de Exportação. Essas diretivas são utilizadas para especificar as regras de restrição de acesso de um pacote exportado. Consulte osgi.resolverMode para configurar o Eclipse OSGi Framework para aplicar as regras de restrições de acesso no tempo de execução.

A Diretiva x-internal

Essa diretiva pode ser utilizada em um cabeçalho Pacote de Exportação, para especificar se o pacote é um pacote interno. O Ambiente de Desenvolvimento de Plug-in desaconselhará outros pacotes configuráveis de utilizarem um pacote interno. Se a diretiva x-internal não for especificada, um valor padrão 'false' será utilizado. Tal diretiva deve utilizar a seguinte sintaxe:

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

A seguir encontra-se um exemplo da diretiva x-internal:

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

A Diretiva x-friends

Essa diretiva pode ser utilizada em um cabeçalho Pacote de Exportação, para especificar uma lista de pacotes configuráveis que são permitidos acessar o pacote. O Ambiente de Desenvolvimento de Plug-in desaconselhará outros pacotes configuráveis de utilizarem o pacote. Tal diretiva deve utilizar a seguinte sintaxe:

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

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

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

O exemplo especifica que somente os pacotes configuráveis org.eclipse.foo.friend1 e org.eclipse.foo.friend2 devem ser encorajados a utilizar o pacote org.eclipse.foo.formyfriends. O pacote x-internal tem prioridade sobre a diretiva x-friends. Se a diretiva x-internal especificar 'true', o Ambiente de Desenvolvimento de Plug-in desaconselhará todos os pacotes configuráveis de utilizarem o pacote, mesmo se eles forem especificados como um amigo.

O Cabeçalho Eclipse-LazyStart

O cabeçalho Eclipse-LazyStart é utilizado para especificar se um pacote configurável deve ser iniciado automaticamente antes que a primeira classe ou recurso seja acessado nesse pacote configurável. Esse recurso permite ao Eclipse ativar pacotes configuráveis lentamente, na primeira necessidade deles. Utilizando esse modelo, o Eclipse pode inicializar alguns pacotes configuráveis ativos quando possível. O cabeçalho Eclipse-LazyStart deve 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 deve fazer com que o pacote configurável seja ativado, quando as classes ou recursos forem carregados deles. Se o cabeçalho Eclipse-LazyStart não estiver definido no manifesto de pacote configurável, um valor padrão 'false' será utilizado. Segue um exemplo do cabeçalho Eclipse-LazyStart:

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

O exemplo especifica que esse pacote configurável deve ser ativado por quaisquer classes ou recursos carregados desse pacote, exceto as classes e recursos nos pacotes 'org.eclipse.foo1' e 'org.eclipse.foo2'.

O cabeçalho Eclipse-AutoStart foi reprovado no Eclipse 3.2. Em seu lugar, deverá ser utilizado o cabeçalho Eclipse-LazyStart.

O Cabeçalho Eclipse-PlatformFilter

O Eclipse-PlatformFilter é utilizado para especificar um filtro de plataforma para um pacote configurável. Um filtro de plataforma deve ser avaliado como verdadeiro em uma plataforma em execução, para que seja permitido um pacote configurável para resolução. Esse cabeçalho deve utilizar a seguinte sintaxe:

Eclipse-PlatformFilter ::= a valid LDAP filter string

O Framework suporta a filtragem nas seguintes propriedades de sistema:

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

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

Esse exemplo especifica que esse pacote configurável apenas poderá ser resolvido, se as propriedades da plataforma forem osgi.ws=win32, osgi.os=win32 e osgi.arch=x86. Em outras palavras, um a plataforma sendo executada em uma arquitetura x86, utilizando um sistema operacional win32 e um sistema de janelas win32.

O Cabeçalho Eclipse-BuddyPolicy

Esse cabeçalho é utilizado para especificar as políticas de carregamento de classe de parceria para um pacote configurável. Ele deve 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

Esse cabeçalho é utilizado para especificar uma lista de pacotes configuráveis, para os quais esse pacote configurável é uma parceria registrada. Esse cabeçalho deve utilizar 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 Eclipse-ExtensibleAPI é utilizado para especificar se um pacote configurável do host permite que os pacotes configuráveis de fragmentos incluam a API adicional no host. Esse cabeçalho deve ser utilizado se um pacote configurável do host quiser permitir que os fragmentos incluam pacotes adicionais na API do host. Se esse cabeçalho não for especificado, um valor padrão 'false' será utilizado. Ele deve 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 um recurso genérico de um pacote configurável. Recursos genéricos podem ser utilizados para descrever recursos de pacote configurável que podem ser exigidos por outros pacotes no sistema (utilizando o cabeçalho Eclipse-GenericRequire). Recursos genéricos recebem um nome e um tipo. Tipos de recurso são definidos pelo pacote configurável que está oferecendo o recurso. Os recursos também podem ter um conjunto de atributos de correspondência de tipos, utilizados para comparação ao resolver os cabeçalhos Eclipse-GenericRequire. Os atributos de correspondência podem ser um dos seguintes tipos: [string | version | uri | long | double | set]. O tipo set pode ser utilizado para definir um conjunto de cadeias como uma lista de cadeias separadas por vírgula. O cabeçalho Eclipse-GenericCapability deve 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] )

Segue um exemplo do cabeçalho Eclipse-GenericCapabilty que poderia ser utilizado para especificar um pacote configurável, com uma implementação do serviço OSGi org.acme.stuff.SomeService:

  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 sobre o recurso genérico oferecido por outro pacote configurável (utilizando o cabeçalho Eclipse-GenericCapability). Requisitos genéricos recebem um nome e um tipo de recurso. Tipos de recurso são definidos pelo pacote configurável que está oferecendo o recurso. Requisitos genéricos podem especificar uma cadeia de filtros LDAP utilizada como filtro de seleção para resolver em comparação com recursos genéricos de correspondência. O cabeçalho Eclipse-GenericRequire deve 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 )

Segue um exemplo do cabeçalho Eclipse-GenericRequire que poderia ser utilizado para especificar um pacote configurável que depende de uma implementação do serviço OSGi org.acme.stuff.SomeService:

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

Aliases Genéricos

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

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

Esses cabeçalhos podem ser mapeados para os cabeçalhos Eclipse-GenericCapability e Eclipse-GenericRequire utilizando a seguinte propriedade:

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

Sob proteções, isso se converteria nos 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

Esse cabeçalho apenas é utilizado para suportar plug-ins desenvolvidos para a plataforma Eclipse 2.1. Esse cabeçalho é utilizado para especificar um nome de classe que será utilizado para ativar um plug-in utilizando o modelo de ativação antigo do Eclipse 2.1. Os novos pacotes configuráveis desenvolvidos para o Eclipse 3.0 ou superior não deverão utilizar esse cabeçalho. A seguir encontra-se um exemplo do cabeçalho Plugin-Class:

Plugin-Class: org.eclipse.foo.FooPlugin