Bundle Plugin for Maven

原文地址：

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

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

 

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

首先我们来看一个例子

Xml代码   ...   <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中使用插件。

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文件： 

 

Xml代码   <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）：

 

Xml代码   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/目录中的项目复制）：

 

Xml代码   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。 例如：

Xml代码   <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文件：

 

 

Xml代码   <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

 

 

Xml代码   <span style="font-size: small;"><Embed-Dependency>dependencies</Embed-Dependency></span>  

 其中：

 

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的反对。

 

一些例子

Xml代码   <!-- 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}的例子

 

Xml代码   <span style="font-size: small;"><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></span>  

 

默认情况下，匹配的依赖是嵌入在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）

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

 

Xml代码   <Embed-Transitive>true</Embed-Transitive>  

 

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

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

Xml代码      

 

 

嵌入依赖和导出包

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

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

 

OBR 整合

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

 

Xml代码   <LOCAL-MAVEN-REPOSITORY>/repository.xml  

使用配置可以配置OBR 库

Xml代码   mvn clean install -DobrRepository=<PATH_TO_OBR>  

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

Xml代码   <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，例如

 

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

 

Eclipse/PDE的集成

 

 

Xml代码   <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使用元数据：

Xml代码   mvn clean package eclipse:eclipse -Declipse.pde install  

 PAX组织来创建POM的例子：

Xml代码   mvn clean package pax:eclipse  

 不打包 bundle 内容 target/classes

 

 

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

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

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

 使用存在的 MANIFEST.MF 文件

 

 

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

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