Bundle Plugin for Maven

原文地址：

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

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

 

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

首先我们来看一个例子

...
<plugins>
  <plugin>
    <groupId>org.apache.felix</groupId>
    <artifactId>maven-bundle-plugin</artifactId>
    <extensions>true</extensions>
    <configuration>
      <instructions>
        <Export-Package>org.foo.myproject.api</Export-Package>
        <Private-Package>org.foo.myproject.*</Private-Package>
        <Bundle-Activator>org.foo.myproject.impl1.Activator</Bundle-Activator>
      </instructions>
    </configuration>
  </plugin>
</plugins>
...

 

 <Export-Package>和<Private-Package>指令告诉插件生成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

说明

<Export-Package>

<Export-Package>是导出包的列表。这些包被复制到打成的结果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的语法，指令和属性，这将被复制到适当的清单中。

 

 

 <Private-Package>

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

 

<Include-Resource>

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

   clause :: = assignment | inline | simple

   assignment ::  = PATH = 'PATH'

   simple :: =PATH

   inline ::= '@' PATH

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

 

   <Import-Package>

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

 

 

默认行为

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

<Bundle-SymbolicName>使用的共享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）的属性，你想给它添加属性或指令也存储在计算机的符号名。
<Export-Package>现在假定是在您当地的Java源代码包，但不包括默认的包'。“ 和任何包含“IMPL”或“内部”。
（之前版本的bundleplugin 2基于符号名）
自2.2.0，您还可以使用{ 当地软件包 }内<Export-Package>将扩大到本地软件包。
<Private-Package>现在假定是在您当地的Java源代码（请注意，在双方<Export-Package>和<Private-Package>任何包将出口）的一组包。
（之前版本的bundleplugin 2，它被认为是默认为空）
<Import-Package>被认为是“*”，其中进口捆绑内容所指的一切，但没有在包中包含的。
任何出口包默认情况下，也有进口，以确保一致的类空间。
<Include-Resource>从项目的Maven的资源，通常为“src /主/资源/”，这 ??将导致包JAR文件复制到指定的项目目录层次结构，反映标准的Maven的行为产生。
<Bundle-Version>假设“$ {pom.version}”，但归到OSGi的版本格式，例如“2.1-快照 ”将成为“2.1.0，”MAJOR.MINOR.MICRO.QUALIFIER“。快照 “。
<Bundle-Name>被认为是“$ {pom.name}”。
<Bundle-Description>被认为是“$ {pom.description}”。
<Bundle-License>被认为是“$ {pom.licenses}”。
<Bundle-Vendor>被认为是“$ {pom.organization.name}”。
<Bundle-DocURL>被认为是“$ {pom.organization.url}”。
由于插件创建为OSGi R4的捆绑，它硬编码束ManifestVersion，是'2'。 此外，它生成的每一个出口的进口与合作，服务工作，以确保包可替代

 

 使用插件

  在pom.xml中使用插件。

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>my-osgi-bundles</groupId>
  <artifactId>examplebundle</artifactId>
  <packaging>bundle</packaging>    <!-- (1) -->
  <version>1.0</version>
  <name>Example Bundle</name>
  <dependencies>
    <dependency>
      <groupId>org.apache.felix</groupId>
      <artifactId>org.osgi.core</artifactId>
      <version>1.0.0</version>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <plugin>    <!-- (2) START -->
        <groupId>org.apache.felix</groupId>
        <artifactId>maven-bundle-plugin</artifactId>
        <extensions>true</extensions>
        <configuration>
          <instructions>
            <Export-Package>com.my.company.api</Export-Package>
            <Private-Package>com.my.company.*</Private-Package>
            <Bundle-Activator>com.my.company.Activator</Bundle-Activator>
          </instructions>
        </configuration>
      </plugin>    <!-- (2) END -->
    </plugins>
  </build>
</project>

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

 

 真实的例子

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

 

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.apache.felix</groupId>
  <artifactId>org.apache.felix.log</artifactId>
  <packaging>bundle</packaging>
  <name>Apache Felix Log Service</name>
  <version>0.8.0-SNAPSHOT</version>
  <description>
    This bundle provides an implementation of the OSGi R4 Log service.
  </description>
  <dependencies>
    <dependency>
      <groupId>${pom.groupId}</groupId>
      <artifactId>org.osgi.core</artifactId>
      <version>0.8.0-incubator</version>
    </dependency>
    <dependency>
      <groupId>${pom.groupId}</groupId>
      <artifactId>org.osgi.compendium</artifactId>
      <version>0.9.0-incubator-SNAPSHOT</version>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.felix</groupId>
        <artifactId>maven-bundle-plugin</artifactId>
        <extensions>true</extensions>
        <configuration>
          <instructions>
            <Export-Package>org.osgi.service.log</Export-Package>
            <Private-Package>org.apache.felix.log.impl</Private-Package>
            <Bundle-SymbolicName>${pom.artifactId}</Bundle-SymbolicName>
            <Bundle-Activator>${pom.artifactId}.impl.Activator</Bundle-Activator>
            <Export-Service>org.osgi.service.log.LogService,org.osgi.service.log.LogReaderService</Export-Service>
          </instructions>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

 请注意，<Export-Package>指令指定的包导出日志服务包，即使这个包不包含在捆绑项目。 申报，该插件将导致包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。 例如：

<plugin>
  <artifactId>maven-jar-plugin</artifactId>
  <configuration>
    <archive>  
      <manifestFile>${project.build.outputDirectory}/META-INF/MANIFEST.MF</manifestFile>
    </archive> 
  </configuration>
</plugin>  
<plugin>   
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <executions>
    <execution>
      <id>bundle-manifest</id>
      <phase>process-classes</phase>
      <goals>    
        <goal>manifest</goal>
      </goals>   
    </execution>
  </executions>
</plugin>

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

 

 

<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <executions>
    <execution>
      <id>bundle-manifest</id>
      <phase>process-classes</phase>
      <goals>
        <goal>manifest</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <supportedProjectTypes>
      <supportedProjectType>jar</supportedProjectType>
      <supportedProjectType>bundle</supportedProjectType>
      <supportedProjectType>war</supportedProjectType>
    </supportedProjectTypes>
    <instructions>
      <!-- ...etc... -->
    </instructions>
  </configuration>
</plugin>

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

 嵌入依赖

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

 

 

<Embed-Dependency>dependencies</Embed-Dependency>

 其中：

 

dependencies ::= clause ( ',' clause ) *
clause ::= MATCH ( ';' attr '=' MATCH | ';inline=' inline )
attr ::= 'groupId' | 'artifactId' | 'version' | 'scope' | 'type' | 'classifier' | 'optional'
inline ::= 'true' | 'false' | PATH ( '|' PATH ) *
MATCH ::= <globbed regular expression>
PATH ::= <Ant-style path expression>

 

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

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

 

一些例子

<!-- embed all compile and runtime scope dependencies -->
<Embed-Dependency>*;scope=compile|runtime</Embed-Dependency>

<!-- embed any dependencies with artifactId junit and scope runtime -->
<Embed-Dependency>junit;scope=runtime</Embed-Dependency>

<!-- inline all non-pom dependencies, except those with scope runtime -->
<Embed-Dependency>*;scope=!runtime;type=!pom;inline=true</Embed-Dependency>

<!-- embed all compile and runtime scope dependencies, except those with artifactIds in the given list -->
<Embed-Dependency>*;scope=compile|runtime;inline=false;artifactId=!cli|lang|runtime|tidy|jsch</Embed-Dependency>

<!-- inline contents of selected folders from all dependencies -->
<Embed-Dependency>*;inline=images/**|icons/**</Embed-Dependency>

 使用{maven-dependecies}的例子

 

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

<Bundle-ClassPath>.,{maven-dependencies},some.jar</Bundle-ClassPath>

 

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

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

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

 

<Embed-Transitive>true</Embed-Transitive>

 

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

<Embed-Dependency>*;scope=compile|runtime;inline=true</Embed-Dependency>

 

 

嵌入依赖和导出包

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

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

 

OBR 整合

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

 

<LOCAL-MAVEN-REPOSITORY>/repository.xml

使用配置可以配置OBR 库

mvn clean install -DobrRepository=<PATH_TO_OBR>

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

<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
<extensions>true</extensions>
<configuration>
  <obrRepository>PATH_TO_OBR</obrRepository>
  <instructions>
    <!-- bnd instructions -->
  </instructions>
</configuration>

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

 

<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
<extensions>true</extensions>
<configuration>
  <obrRepository>NONE</obrRepository>
  <instructions>
    <!-- bnd instructions -->
  </instructions>
</configuration>

 

Eclipse/PDE的集成

 

 

<project>

  <properties>
    <bundle.symbolicName>org.example</bundle.symbolicName>
    <bundle.namespace>org.example</bundle.namespace>
  </properties>

  <modelVersion>4.0.0</modelVersion>
  <groupId>examples</groupId>
  <artifactId>org.example</artifactId>
  <version>1.0-SNAPSHOT</version>

  <name>${bundle.symbolicName} [${bundle.namespace}]</name>

  <packaging>bundle</packaging>

  <build>
    <resources>
      <resource>
        <directory>src/main/resources</directory>
      </resource>
      <resource>
        <directory>.</directory>
        <includes>
          <include>plugin.xml</include>
        </includes>
      </resource>
    </resources>
    <plugins>
      <plugin>
        <groupId>org.apache.felix</groupId>
        <artifactId>maven-bundle-plugin</artifactId>
        <version>1.2.1</version>
        <extensions>true</extensions>
        <!--
          the following instructions build a simple set of public/private classes into an OSGi bundle
        -->
        <configuration>
          <manifestLocation>META-INF</manifestLocation>
          <instructions>
            <Bundle-SymbolicName>${bundle.symbolicName}</Bundle-SymbolicName>
            <Bundle-Version>${pom.version}</Bundle-Version>
            <!--
              assume public classes are in the top package, and private classes are under ".internal"
            -->
            <Export-Package>!${bundle.namespace}.internal.*,${bundle.namespace}.*;version="${pom.version}"</Export-Package>
            <Private-Package>${bundle.namespace}.internal.*</Private-Package>
            <Bundle-Activator>${bundle.namespace}.internal.ExampleActivator</Bundle-Activator>
            <!--
              embed compile/runtime dependencies using path that matches the copied dependency folder
            -->
            <Embed-Dependency>*;scope=compile|runtime;inline=false</Embed-Dependency>
            <Embed-Directory>target/dependency</Embed-Directory>
            <Embed-StripGroup>true</Embed-StripGroup>
          </instructions>
        </configuration>
      </plugin>
      <plugin>
        <artifactId>maven-dependency-plugin</artifactId>
        <executions>
          <execution>
            <id>copy-dependencies</id>
            <phase>package</phase>
            <goals>
              <goal>copy-dependencies</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>

  <dependencies>
    <dependency>
      <groupId>org.osgi</groupId>
      <artifactId>osgi_R4_core</artifactId>
      <version>1.0</version>
      <scope>provided</scope>
      <optional>true</optional>
    </dependency>
    <dependency>
      <groupId>org.osgi</groupId>
      <artifactId>osgi_R4_compendium</artifactId>
      <version>1.0</version>
      <scope>provided</scope>
      <optional>true</optional>
    </dependency>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>compile</scope>
      <optional>true</optional>
    </dependency>
  </dependencies>
</project>

 

要生成的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的地方希望他们会发现额外的类。 幸好现在有一个简单的选项做捆绑插件：

<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
<extensions>true</extensions>
<configuration>
  <unpackBundle>true</unpackBundle>
  <instructions>
    <!-- bnd instructions -->
  </instructions>
</configuration>

 使用存在的 MANIFEST.MF 文件

 

 

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

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