Bundle Plugin for Maven

阅读更多

原文地址：

http://felix.apache.org/site/apache-felix-maven-bundle-plugin-bnd.html

翻译水平有限，大家将就着看吧。

 

今天来全面讲一下 bundle plugin for Maven 插件的使用方式

首先我们来看一个例子

...

  
    org.apache.felix
    maven-bundle-plugin
    true
    
      
        org.foo.myproject.api
        org.foo.myproject.*
        org.foo.myproject.impl1.Activator
      
    
  

...

 

 和指令告诉插件生成bundle jar包的内容。其中Export-Package是导出包，让别的bundle可以导入包。Private-Package指令为复制包和包中的类，但是不导出。如果一个包在Export-Package和Private-Package中都写了，那么该包一定会被导出，因为Export-Package优先级高。如果我们的包不需要其他bundle manifest。如果包不需要其他bundle使用，那么只写Private-Package就可以了

特别强调一点的是，Import-Package 不需在bundle manifest清单中描述。会自动智能的导入。（翻者认为还是手动写为好。例如内容为： !*,com.apache.common.files,com.equinox.osgi 开始写!*表示不导入全部，然后需要导入的一一写明。这样比较好该插件太智能，自己会导入依赖的bundle classpath中无用的包）。Bundle-Activator为此bundle激活后立即执行的方法。

 

特点

 相关插件bun库定义指令来约束插件的行为。这个Maven插件指令的使用方式请参考上面给出的例子。BND识别三种指令：

  1.Manifest headers（jar包清单文件）-- 任何一个指令都是以大写字母开头，显示的写在MANIFEST.MF文件中。清单文件中的值，根据pom文件缩写内容被复制、增强、根据由BND根据指令生成。

  2.变量 -- 任何一个小写字母开头的指令被认为是一个变量形式的名-值对。例如version=3.0。可以在pom中使用属性来替代。但是不会被复制到清单中。

  3.指令-开始使用断线字符('-')被认为是一个指令。通知BND执行一些特殊的处理。例如-osgi.bnd。该指令不会被复制到清单中。

关于BND指令的内容请参考http://www.aqute.biz/Code/Bnd

说明

是导出包的列表。这些包被复制到打成的结果bundle JAR中。导出包可以使用通配符*来匹配一些类包例如org.apache.felix.*。这表示org.apache.felix下面所有的子包。此外，排除导入包可以是!*。例如：org.foo.*,!org.foo.impl第二个模式中的种写法不起作用。因为org.foo包已经被第一个模式所选择了。正确的写法：!org.foo.impl,org.foo.*。从org.foo包中排除org.foo.impl包。包模式可以包括以下标准的OSGi R4的语法，指令和属性，这将被复制到适当的清单中。

 

 

 

指令和指令是相类似的。除了这些包不会被导出。如果一个包在和都写了。是优先的。

 

指令包含被复制到JAR包中的资源清单。被指定的资源符合以下几种形式：

   clause :: = assignment | inline | simple

   assignment ::  = PATH = 'PATH'

   simple :: =PATH

   inline ::= '@' PATH

指令，实际的文件路径是相对pom.xml。复制到目的地是相对JAR的根。例如：src/main/resources/a/b.c 将把b.c放置到JAR根目录中。如果资源中使用了{}，必须变成${} 来替换{}的内容。

 

  

   指令是导入bundle所需要的软件包列表。默认值是*，这意味着导入所有的包。然而，在某些情况下，会有不必要的包被导入。例如你想导入所有的包，但是要排除org.foo.imp。需要这样写： “!org.foo.impl,*”

 

 

默认行为

使用这个插件，信息很少需要BND。 作为Maven集成的一部分，该插件会尝试各种指令来设置合理的默认值。 例如：

使用的共享Maven2OsgiConverter组件，它使用下面的算法计算：
获取为的groupId +符号名“。” + artifactId的，但有以下例外：
如果artifact.getFile不是空的jar包含的OSGi的Bundle-SymbolicName属性舱单，然后返回值
如果的groupId只有一个部分（不点）和artifact.getFile不为空，然后用类第一包名被返回。 例如。 公共记录：公共记录 - > org.apache.commons.logging
如果artifactId的最后一节的groupId是平等的groupId是返回。 例如。 org.apache.maven：行家 - > org.apache.maven
如果artifactId的最后一节，部分被删除的groupId开始。 例如。 org.apache.maven：Maven的核心 - > org.apache.maven.core
美元的情况下（行家symbolicname）的属性，你想给它添加属性或指令也存储在计算机的符号名。
现在假定是在您当地的Java源代码包，但不包括默认的包'。“ 和任何包含“IMPL”或“内部”。
（之前版本的bundleplugin 2基于符号名）
自2.2.0，您还可以使用{ 当地软件包 }内将扩大到本地软件包。
现在假定是在您当地的Java源代码（请注意，在双方和任何包将出口）的一组包。
（之前版本的bundleplugin 2，它被认为是默认为空）
被认为是“*”，其中进口捆绑内容所指的一切，但没有在包中包含的。
任何出口包默认情况下，也有进口，以确保一致的类空间。
从项目的Maven的资源，通常为“src /主/资源/”，这 ??将导致包JAR文件复制到指定的项目目录层次结构，反映标准的Maven的行为产生。
假设“$ {pom.version}”，但归到OSGi的版本格式，例如“2.1-快照 ”将成为“2.1.0，”MAJOR.MINOR.MICRO.QUALIFIER“。快照 “。
被认为是“$ {pom.name}”。
被认为是“$ {pom.description}”。
被认为是“$ {pom.licenses}”。
被认为是“$ {pom.organization.name}”。
被认为是“$ {pom.organization.url}”。
由于插件创建为OSGi R4的捆绑，它硬编码束ManifestVersion，是'2'。 此外，它生成的每一个出口的进口与合作，服务工作，以确保包可替代

 

 使用插件

  在pom.xml中使用插件。

  4.0.0
  my-osgi-bundles
  examplebundle
  bundle    
  1.0
  Example Bundle
  
    
      org.apache.felix
      org.osgi.core
      1.0.0
    
  
  
    
          
        org.apache.felix
        maven-bundle-plugin
        true
        
          
            com.my.company.api
            com.my.company.*
            com.my.company.Activator
          
        
          
    
  

 主要有两件事情要注意：（1）符必须是“bundle”（2）插件和配置必须指定（配置节，在那里你会发出指令到插件）。

 

 真实的例子

考虑这个使用Felix日志服务实现更真实世界的例子。 日志服务项目是由一个单一的软件包：org.apache.felix.log.impl。 它有一个核心的OSGi接口的依赖，以及对特定的日志服务接口的汇编的OSGi接口的依赖。 以下是它的POM文件： 

 

  4.0.0
  org.apache.felix
  org.apache.felix.log
  bundle
  Apache Felix Log Service
  0.8.0-SNAPSHOT
  
    This bundle provides an implementation of the OSGi R4 Log service.
  
  
    
      ${pom.groupId}
      org.osgi.core
      0.8.0-incubator
    
    
      ${pom.groupId}
      org.osgi.compendium
      0.9.0-incubator-SNAPSHOT
    
  
  
    
      
        org.apache.felix
        maven-bundle-plugin
        true
        
          
            org.osgi.service.log
            org.apache.felix.log.impl
            ${pom.artifactId}
            ${pom.artifactId}.impl.Activator
            org.osgi.service.log.LogService,org.osgi.service.log.LogReaderService
          
        
      
    
  

 请注意，指令指定的包导出日志服务包，即使这个包不包含在捆绑项目。 申报，该插件将导致包JAR文件复制到日志服务包。 在这种情况下，这是非常有用的，因为现在的包可以解决，而不必下载整个汇编包。 日志服务捆绑的清单看起来像这样（注意如何进口/出口自动版本与他们相关的信息，这是从源代码包中的文件packageinfo）：

 

Manifest-Version: 1
Bundle-License: http://www.apache.org/licenses/LICENSE-2.0.txt
Bundle-Activator: org.apache.felix.log.impl.Activator
Import-Package: org.osgi.framework;version=1.3, org.osgi.service.log;v
 ersion=1.3
Include-Resource: src/main/resources
Export-Package: org.osgi.service.log;uses:=org.osgi.framework;version=
 1.3
Bundle-Version: 0.8.0.SNAPSHOT
Bundle-Name: Apache Felix Log Service
Bundle-Description: This bundle provides an implementation of the OSGi
  R4 Log service.
Private-Package: org.apache.felix.log.impl
Bundle-ManifestVersion: 2
Export-Service: org.osgi.service.log.LogService,org.osgi.service.log.L
 ogReaderService
Bundle-SymbolicName: org.apache.felix.log

 由此产生的捆绑JAR文件有以下内容（注意如何许可和公告文件自动从 src /main/resource/目录中的项目复制）：由此产生的捆绑JAR文件有以下内容（注意如何许可和公告文件自动从 src /main/resources/目录中的项目复制）：

 

META-INF/MANIFEST.MF
LICENSE
META-INF/
META-INF/maven/
META-INF/maven/org.apache.felix/
META-INF/maven/org.apache.felix/org.apache.felix.log/
META-INF/maven/org.apache.felix/org.apache.felix.log/pom.properties
META-INF/maven/org.apache.felix/org.apache.felix.log/pom.xml
NOTICE
org/
org/apache/
org/apache/felix/
org/apache/felix/log/
org/apache/felix/log/impl/
org/apache/felix/log/impl/Activator.class
org/apache/felix/log/impl/Log.class
org/apache/felix/log/impl/LogEntryImpl.class
org/apache/felix/log/impl/LogException.class
org/apache/felix/log/impl/LogListenerThread.class
org/apache/felix/log/impl/LogNode.class
org/apache/felix/log/impl/LogNodeEnumeration.class
org/apache/felix/log/impl/LogReaderServiceFactory.class
org/apache/felix/log/impl/LogReaderServiceImpl.class
org/apache/felix/log/impl/LogServiceFactory.class
org/apache/felix/log/impl/LogServiceImpl.class
org/osgi/
org/osgi/service/
org/osgi/service/log/
org/osgi/service/log/LogEntry.class
org/osgi/service/log/LogListener.class
org/osgi/service/log/LogReaderService.class
org/osgi/service/log/LogService.class
org/osgi/service/log/package.html
org/osgi/service/log/packageinfo

 OSGi元数据添加到现有的项目，不改变包装类型

 如果你想保持你的项目打包类型（例如，“jar”），但想加入OSGi元数据
您可以使用清单的目标是产生一个bundle清单。 Maven的jar插件，然后可以用来
这个清单添加到最后的artifact。 例如：

  maven-jar-plugin
  
      
      ${project.build.outputDirectory}/META-INF/MANIFEST.MF
     
  
  
   
  org.apache.felix
  maven-bundle-plugin
  
    
      bundle-manifest
      process-classes
          
        manifest
         
    
  

 如果你想使用比“jar”和“bundle”其他包装类型，那么你还需要启用支持
为他们在bundleplugin配置，例如，如果你要使用插件WAR文件：

 

 

  org.apache.felix
  maven-bundle-plugin
  
    
      bundle-manifest
      process-classes
      
        manifest
      
    
  
  
    
      jar
      bundle
      war
    
    
      
    
  

 以下功能是从1.2.0起才出现的功能

 嵌入依赖

maven bundle 插件支持Embedding指令来选择Maven bundle

 

 

dependencies

 其中：

 

dependencies ::= clause ( ',' clause ) *
clause ::= MATCH ( ';' attr '=' MATCH | ';inline=' inline )
attr ::= 'groupId' | 'artifactId' | 'version' | 'scope' | 'type' | 'classifier' | 'optional'
inline ::= 'true' | 'false' | PATH ( '|' PATH ) *
MATCH ::=
PATH ::=

 

插件使用的的指令转换成和条款，然后追加到目前的指令集，并到BND通过项目的依赖。 如果你想嵌入的依赖关系是在开始或中间的或，那么你可以使用Maven的依赖 }，它会自动扩大到有关的条文。

匹配部分接受的替代品，由|分隔，可以通过使用在本场比赛开始否定！ 用*代表零个或多个未知字符代表零或一个字符。 你也可以使用标准的Java 正则表达式构造。 有没有必要逃避内部匹配的字符 。 首场比赛中的一项条款，将筛选artifactId的反对。

 

一些例子

*;scope=compile|runtime


junit;scope=runtime


*;scope=!runtime;type=!pom;inline=true


*;scope=compile|runtime;inline=false;artifactId=!cli|lang|runtime|tidy|jsch


*;inline=images/**|icons/**

 使用{maven-dependecies}的例子

 

  {maven-resources}, {maven-dependencies},
  org/foo/Example.class=target/classes/org/foo/Example.class


.,{maven-dependencies},some.jar

 

默认情况下，匹配的依赖是嵌入在artifactId的，version.jar束。 这种行为可以被修改，使用下列指令：

• true -删除文件（即artifactId.jar）的版本
• false -增加了一个子目录（即的groupId / artifactId的version.jar）的groupId
• directory -增加了一个子目录（即目录/ artifactId的version.jar）

插件通常只检查直接依赖，但这是可以改变的包括一套完整的传递依赖以下选项：

 

true

 

 如果你想依赖联，而不是嵌入添加内嵌= TRUE。 例如，内联所有的编译和运行的范围依赖使用：

*;scope=compile|runtime;inline=true

 

 

嵌入依赖和导出包

如果嵌入依赖与，您的或说明符合内嵌入的JAR包，你会看到一些内部捆绑的重复。 这是，因为和指示将导致在被捆绑在联类，尽管他们也存在着内部嵌入的JAR。 如果你想从没有这样的重复嵌入依赖出口包，那么你可以内联的依赖，或使用一个新的BND指令称为<_exportcontents>。

<_exportcontents>行为就像进出口包装，除了它不改变内容的捆绑，只是哪些内容应出口。

 

OBR 整合

    在bundle install期，最新的Maven Bundle插件自动升级本地OBR库 repository.xml 文件

 

/repository.xml

使用配置可以配置OBR 库

mvn clean install -DobrRepository=

 或者写到maven-bundle-plugin插件中，例如：

org.apache.felix
maven-bundle-plugin
true

  PATH_TO_OBR
  
    
  

 禁止使用OBR 安装OBR库中使用NONE，例如

 

org.apache.felix
maven-bundle-plugin
true

  NONE
  
    
  

 

Eclipse/PDE的集成

 

 

  
    org.example
    org.example
  

  4.0.0
  examples
  org.example
  1.0-SNAPSHOT

  ${bundle.symbolicName} [${bundle.namespace}]

  bundle

  
    
      
        src/main/resources
      
      
        .
        
          plugin.xml
        
      
    
    
      
        org.apache.felix
        maven-bundle-plugin
        1.2.1
        true
        
        
          META-INF
          
            ${bundle.symbolicName}
            ${pom.version}
            
            !${bundle.namespace}.internal.*,${bundle.namespace}.*;version="${pom.version}"
            ${bundle.namespace}.internal.*
            ${bundle.namespace}.internal.ExampleActivator
            
            *;scope=compile|runtime;inline=false
            target/dependency
            true
          
        
      
      
        maven-dependency-plugin
        
          
            copy-dependencies
            package
            
              copy-dependencies
            
          
        
      
    
  

  
    
      org.osgi
      osgi_R4_core
      1.0
      provided
      true
    
    
      org.osgi
      osgi_R4_compendium
      1.0
      provided
      true
    
    
      junit
      junit
      3.8.1
      compile
      true
    
  

 

要生成的Eclipse使用元数据：

mvn clean package eclipse:eclipse -Declipse.pde install

 PAX组织来创建POM的例子：

mvn clean package pax:eclipse

 不打包 bundle 内容 target/classes

 

 

一旦在，而你可以创建一个包，其中包含附加的类编译src /主/ Java中 ，例如，当你从另一个JAR嵌入类。 这有时会导致在Maven中的不可预见的问题，因为它会使用输出目录（ 目标/班 ），而不是最终束，对在同一反应器（即同一版本）的项目进行编译时。

最简单的方法来解决这个Maven的“功能”是解开束输出目录的内容，包装后的第一步，所以Maven的地方希望他们会发现额外的类。 幸好现在有一个简单的选项做捆绑插件：

org.apache.felix
maven-bundle-plugin
true

  true
  
    
  

 使用存在的 MANIFEST.MF 文件

 

 

<_include>src/main/resources/META-INF/MANIFEST.MF
org.example.*

 BND将用它计算包内容时，也将复制一个大写字母开始的所有清单属性。 
在上面的例子所示，你可以使用这个包括非OSGi的清单，你再额外OSGi的属性定制。