基于Karaf的项目离线打包与发布

Karaf对OSGi Bundle的组织采用Pax的maven url方式，这也隐性的继承了maven的特性，即，所有的依赖来自maven仓库，在实际开发中，这大大的便利了项目结构的组织和维护，开发人员只要指明对某个bundle的maven依赖，karaf自动去选取和下载。但是，在基于karaf的项目部署时，项目或产品的发布环境往往要求严格，不能够随意访问远程的maven仓库；那提供一个本地maven仓库？显然这也不合理，本地maven仓库的维护加重了维护的复杂性。本文主要就离线发布karaf的需求实现进行探讨。

Pax URL Mvn协议

在讨论karaf的maven依赖加载与管理之前，我们先了解一下Pax URL项目的Mvn协议：

 

mvn-uri := 'mvn:' [ repository-url '!' ] group-id '/' artifact-id [ '/' [version] [ '/' [type] [ '/' classifier ] ] ] ]
repository-url := < rfc2396 uri > ; an url that points to a maven 2 repository
group-id := < maven groupId > ; group id of maven artifact
artifact-id := < maven artifactId > ; artifact id of maven artifact
version := < maven version > | 'LATEST' | range ; version of maven artifact
range := ( '[' | '(' ) version ',' version ( ')' | ']' )
type := < maven type> ; type of maven artifact
classifier := < maven classifier> ; maven artifact classifier

假设项目需要依赖Pax Web的service-0.2.0-SNAPSHOT.jar,对应的Mvn协议示例如下：

 

mvn:org.ops4j.pax.web.bundles/service

mvn:org.ops4j.pax.web.bundles/service/LATEST

mvn:org.ops4j.pax.web.bundles/service/0.2.0-SNAPSHOT

mvn:http://repository.ops4j.org/maven2!org.ops4j.pax.web.bundles/service/0.2.0

mvn:file://c:/localRepo!org.ops4j.pax.web.bundles/service/0.2.0 - 从目录中加载

mvn:org.ops4j.pax.web/pax-web-features/3.0.4-SNAPSHOT/xml/features --标识pax-web-features-3.0.4-SNAPSHOT-features.xml构件

协议要点

1）如果版本（version）未指定，将使用默认值“LATEST”，并从可用的Maven元数据（metadata）中解析最新的版本，maven metadata的示例如下：

 

<?xml version="1.0" encoding="UTF-8"?>
<metadata modelVersion="1.1.0">
  <groupId>org.ops4j.pax.web</groupId>
  <artifactId>pax-web-features</artifactId>
  <version>3.0.4-SNAPSHOT</version>
  <versioning>
    <snapshot>
      <timestamp>20131113.170334</timestamp>
      <buildNumber>2</buildNumber>
    </snapshot>
    <lastUpdated>20131113170334</lastUpdated>
    <snapshotVersions>
      <snapshotVersion>
        <extension>pom</extension>
        <value>3.0.4-20131113.170334-2</value>
        <updated>20131113170334</updated>
      </snapshotVersion>
      <snapshotVersion>
        <classifier>features</classifier>
        <extension>xml</extension>
        <value>3.0.4-20131113.170334-2</value>
        <updated>20131113170334</updated>
      </snapshotVersion>
      <snapshotVersion>
        <classifier>jettyconfig</classifier>
        <extension>xml</extension>
        <value>3.0.4-20131113.170334-2</value>
        <updated>20131113170334</updated>
      </snapshotVersion>
    </snapshotVersions>
  </versioning>
</metadata>

 

 

2）如果version是SNAPSHOT版本，则采用与maven一致的策略来解析SNAPSHOT版本；

3）如果type未指定，默认值为JAR；

4）如果指定了一个type但没有指定version，则必须为version留有占位即：mvn:groups/artifact//type

5）Pax URL从0.3.0版本开始支持类别Classifier，如果类别classifier未指定，则不启用类别；

6）如果指定了类别，但没有指定版本version或类型type，则必须未版本和（或）类型留有占位，即：

mvn:groups/artifact///classifier

 或 

mvn:groups/artifact/version//classifier

 或 

mvn:groups/artifact//type/classifier

 

版本范围

从0.2.0版本开始，Pax URL Mvn支持版本范围，示例如下

• [1.2.3, 4.5.6) — 1.2.3 <= x < 4.5.6
• [1.2.3, 4.5.6] — 1.2.3 <= x <= 4.5.6
• (1.2.3, 4.5.6) — 1.2.3 < x < 4.5.6
• (1.2.3, 4.5.6] — 1.2.3 < x <= 4.5.6

 

Mvn协议的参数配置

可以通过两种方式来配置Mvn协议：1）通过OSGi CM；2）通过框架/系统变量。通过CM配置的参数具有高优先级。

参数名称	描述
org.ops4j.pax.url.mvn.certificateCheck	optional; true/false if the SSL certificate check should be done. Default false.
org.ops4j.pax.url.mvn.globalUpdatePolicy	optional; 控制远程maven仓库的更新策略，maven通过本地POM的时间戳比对为依据。可选的策略包括： always, daily (default), interval:X (where X is an integer in minutes) or never.
org.ops4j.pax.url.mvn.localRepository	optional; 指向本地仓库目录的路径
org.ops4j.pax.url.mvn.repositories	optional; 以逗号分隔的仓库URL列表
org.ops4j.pax.url.mvn.defaultRepositories	optional; 以逗号分隔的默认仓库URL列表
org.ops4j.pax.url.mvn.settings	optional; 指向maven settings.xml的路径
org.ops4j.pax.url.mvn.proxySupport	optional; true/false if the proxy support is enabled . Default true.

 

Settings.xml

如果有必要且maven settings.xml可用，Pax URL Mvn按如下步骤查找settings.xml：

1. 查找配置参数
2. 如果未找到，查找 ${user.home}/.m2/settings.xml
3. 如果未找到，查找 ${maven.home}/conf/settings.xml
4. 如果未找到，查找 ${M2_HOME}/conf/settings.xml

Local repository

Maven本地仓库的查找顺序如下：

1. 查找配置参数定义；
2. 如果未找到，在settings.xml中进行查找
3. 如果未找到，默认认为仓库位于${user.home}/.m2/repository.

Repositories

Maven仓库的解析顺序如下:

1. 在配置参数中查找
2. 在settings.xml中查找

如果配置参数中org.ops4j.pax.url.mvn.repositories的值以'+'开始，则来自settings.xml中的仓库地址也将附加到此配置的仓库列表中。

 

设定仓库包含release/snapshot

可以在参数配置的仓库URL中通过添加如下标识来指定仓库所含有的构件类型（不区分大小写）：

• 启用snapshots — 添加 @snapshots
• 禁用releases — 添加 @noreleases

示例如下:

http://repository.ops4j.org ; 默认不包含任何标识，只查找releases, 不包括snapshots

http://repository.ops4j.org/mvn-snapshots@snapshots ; 同时在此仓库查找releases和snapshots

http://repository.ops4j.org/mvn-snapshots@snapshots@noreleases ; 仅查找snapshots,
不查找releases

默认仓库

在某些情况下，通过默认仓库配置，可以防止用户配置对下载构件造成影响。如果对org.ops4j.pax.url.mvn.defaultRepositories进行了设置，则Pax URL Mvn首先检查此参数设定的默认仓库列表，如果未找到，则继续查找本地仓库和其它在org.ops4j.pax.url.mvn.repositories中配置的仓库。

 

Karaf中Maven仓库处理策略的配置

 

Karaf通过CM（config admin）服务对Pax URL Mvn协议处理进行参数配置，具体的配置是位于${karaf.home}/etc下的

org.ops4j.pax.url.mvn.cfg文件：

#
# If set to true, the following property will not allow any certificate to be used
# when accessing Maven repositories through SSL
#
#org.ops4j.pax.url.mvn.certificateCheck=
 
#
# Path to the local Maven settings file.
# The repositories defined in this file will be automatically added to the list
# of default repositories if the 'org.ops4j.pax.url.mvn.repositories' property
# below is not set.
# The following locations are checked for the existence of the settings.xml file
#   * 1. looks for the specified url
#   * 2. if not found looks for ${user.home}/.m2/settings.xml
#   * 3. if not found looks for ${maven.home}/conf/settings.xml
#   * 4. if not found looks for ${M2_HOME}/conf/settings.xml
#
#org.ops4j.pax.url.mvn.settings=
 
#
# Path to the local Maven repository which is used to avoid downloading
# artifacts when they already exist locally.
# The value of this property will be extracted from the settings.xml file
# above, or defaulted to:
#     System.getProperty( "user.home" ) + "/.m2/repository"
#
#org.ops4j.pax.url.mvn.localRepository=
 
#
# Default this to false. It's just weird to use undocumented repos
#
org.ops4j.pax.url.mvn.useFallbackRepositories=false
 
#
# Uncomment if you don't wanna use the proxy settings
# from the Maven conf/settings.xml file
#
# org.ops4j.pax.url.mvn.proxySupport=false
 
#
# Disable aether support by default.  This ensure that the defaultRepositories
# below will be used
#
#org.ops4j.pax.url.mvn.disableAether=true
 
#
# Comma separated list of repositories scanned when resolving an artifact.
# Those repositories will be checked before iterating through the
#    below list of repositories and even before the local repository
# A repository url can be appended with zero or more of the following flags:
#    @snapshots  : the repository contains snaphots
#    @noreleases : the repository does not contain any released artifacts
#
# The following property value will add the system folder as a repo.
#
#org.ops4j.pax.url.mvn.defaultRepositories=
 
# Use the default local repo (e.g.~/.m2/repository) as a "remote" repo
org.ops4j.pax.url.mvn.defaultLocalRepoAsRemote=false
 
#
# Comma separated list of repositories scanned when resolving an artifact.
# The default list includes the following repositories containing releases:
#    http://repo1.maven.org/maven2
#    http://repository.apache.org/content/groups/snapshots-group
#    http://svn.apache.org/repos/asf/servicemix/m2-repo
#    http://repository.springsource.com/maven/bundles/release
#    http://repository.springsource.com/maven/bundles/external
# To add repositories to the default ones, prepend '+' to the list of repositories
# to add.
# A repository url can be appended with zero or more of the following flags:
#    @snapshots  : the repository contains snaphots
#    @noreleases : the repository does not contain any released artifacts
#    @id=reponid : the id for the repository, just like in the settings.xml this is optional but recomendet
#
# The default list doesn't contain any repository containing snapshots as it can impact the artifacts resolution.
# You may want to add the following repositories containing snapshots:
#    http://repository.apache.org/content/groups/snapshots-group@id=apache@snapshots@noreleases
#    http://oss.sonatype.org/content/repositories/snapshots@id=sonatype.snapshots.deploy@snapshots@norelease
#    http://oss.sonatype.org/content/repositories/ops4j-snapshots@id=ops4j.sonatype.snapshots.deploy@snapshots@noreleases
#
org.ops4j.pax.url.mvn.repositories= \
    http://repo1.maven.org/maven2@id=central, \
    http://repository.springsource.com/maven/bundles/release@id=spring.ebr, \
    file:${karaf.home}/${karaf.default.repository}@id=system.repository, \
    file:${karaf.data}/kar@id=kar.repository@multi

 

下面我们来看一下如何通过调整此配置文件，使得Karaf不再依赖远程Maven仓库和本地Maven仓库，让Karaf发布包随意离线部署成为现实。

首先我们来看一下在org.ops4j.pax.url.mvn.repositories配置中存在两个指向目录路径的仓库URL，即：

 file:${karaf.home}/${karaf.default.repository}@id=system.repository, 和 file:${karaf.data}/kar@id=kar.repository@multi。file:${karaf.home}/${karaf.default.repository}@id=system.repository 实际指向的是karaf安装目录下的system目录（也可以根据需要自行调整，karaf.default.repository参数位于etc/system.properties文件中）；file:${karaf.data}/kar@id=kar.repository@multi实际指向的是karaf安装目录下的data/kar目录。

通过禁用其他仓库URL，只启用这两个位置仓库，则karaf发布程序即可实现离线部署。

具体配置调整如下：

# Path to the local Maven settings file.
# The repositories defined in this file will be automatically added to the list
# of default repositories if the 'org.ops4j.pax.url.mvn.repositories' property
# below is not set.
# The following locations are checked for the existence of the settings.xml file
#   * 1. looks for the specified url
#   * 2. if not found looks for ${user.home}/.m2/settings.xml
#   * 3. if not found looks for ${maven.home}/conf/settings.xml
#   * 4. if not found looks for ${M2_HOME}/conf/settings.xml
#
org.ops4j.pax.url.mvn.settings=
 
#
# Path to the local Maven repository which is used to avoid downloading
# artifacts when they already exist locally.
# The value of this property will be extracted from the settings.xml file
# above, or defaulted to:
#     System.getProperty( "user.home" ) + "/.m2/repository"
#
org.ops4j.pax.url.mvn.localRepository=file:${karaf.home}/${karaf.default.repository}@id=system.repository@snapshots
 
# Use the default local repo (e.g.~/.m2/repository) as a "remote" repo
org.ops4j.pax.url.mvn.defaultLocalRepoAsRemote=true
 
#
# Comma separated list of repositories scanned when resolving an artifact.
# The default list includes the following repositories:
#    http://repo1.maven.org/maven2@id=central
#    http://repository.apache.org/content/groups/snapshots-group@id=apache@snapshots@noreleases
#    http://repository.springsource.com/maven/bundles/release@id=spring.ebr
#    http://oss.sonatype.org/content/repositories/snapshots@id=sonatype.snapshots.deploy@snapshots@norelease
#    http://oss.sonatype.org/content/repositories/ops4j-snapshots@id=ops4j.sonatype.snapshots.deploy@snapshots@noreleases
#    file:${karaf.home}/${karaf.default.repository}@id=system.repository
#    file:${karaf.data}/kar@id=kar.repository@multi
# To add repositories to the default ones, prepend '+' to the list of repositories
# to add.
# A repository url can be appended with zero or more of the following flags:
#    @snapshots  : the repository contains snapshots
#    @noreleases : the repository does not contain any released artifacts
#    @id=repository.id : the id for the repository, just like in the settings.xml this is optional but recommended
#
org.ops4j.pax.url.mvn.repositories= \ file:${karaf.home}/${karaf.default.repository}@id=system.repository@snapshots, \ file:${karaf.data}/kar@id=kar.repository@multi

 

 

在此模式下，Pax URL Mvn优先检查system仓库，如果不存在，则检查${user.home}/.m2下的配置，如果没有settings.xml和repository目录，则加载依赖失败。当system库下不存在org.apache.servicemix.specs.activation-api-1.1-1.9.0.jar时，运行日志如下：

46 -
org.ops4j.pax.url.mvn - 1.6.0 | Resolving
[mvn:org.apache.servicemix.specs/org.apache.servicemix.specs.activation-api-1.1/1.9.0]

46 -
org.ops4j.pax.url.mvn - 1.6.0 | Using manager SimpleLocalRepositoryManager with
priority 0 for D:\Projects\karaf\assemblies\apache-karaf\target\assembly\system

46 - org.ops4j.pax.url.mvn - 1.6.0 | Using connector
WagonRepositoryConnector with priority 0 for file:/C:/Users/xxxx/.m2/repository/

46 -
org.ops4j.pax.url.mvn - 1.6.0 | Using connector WagonRepositoryConnector with
priority 0 for file:D:/Projects/karaf/assemblies/apache-karaf/target/assembly/system/

46 - org.ops4j.pax.url.mvn - 1.6.0 | Error resolving
artifactorg.apache.servicemix.specs:org.apache.servicemix.specs.activation-api-1.1:jar:1.9.0:Could
not find artifact
org.apache.servicemix.specs:org.apache.servicemix.specs.activation-api-1.1:jar:1.9.0
in defaultlocal (file:/C:/Users/xxxx/.m2/repository/)

 

通过此方案，如果发布包中的system目录包含了系统运行所需的所有依赖，则karaf将不再寻求从远程仓库加载依赖，从而实现离线部署。

 

通过上述方案实现karaf离线部署的同时产生了新的问题，如何确保system目录包含所有的依赖同时又不包含无用的冗余依赖？这个问题可以通过karaf-maven-plugin获得解决。下面来看一下配置：

<plugin>
                <groupId>org.apache.karaf.tooling</groupId>
                <artifactId>karaf-maven-plugin</artifactId>
                <executions>
                    <execution>
                        <id>install-kar</id>
                        <phase>compile</phase>
                        <goals>
                            <goal>install-kars</goal>
                        </goals>
                    </execution>
                    <execution>
                        <id>features-add-to-repo</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>features-add-to-repository</goal>
                        </goals>
                        <configuration>
                            <descriptors>
                                <descriptor>mvn:org.apache.karaf.features/standard/${karaf.version}/xml/features</descriptor> <descriptor>mvn:org.apache.karaf.features/spring/${karaf.version}/xml/features</descriptor>
                                ……                          
                            </descriptors>
                            <features>
                                <feature>http</feature> <feature>spring</feature>
                                …
                            </features>
                            <repository>target/assembly/system</repository>
                        </configuration>
                    </execution>
                    <execution>
                        <id>package</id>
                        <goals>
                            <goal>instance-create-archive</goal>
                        </goals>
                    </execution>
                </executions>               
            </plugin>

 

通过此配置，系统在打包时，自动将karaf的standard feature库中的http feature及其依赖和spring feature库中的spring feature及其依赖下载到system目录中一起打包发布。

结论

 

通过上述方案，我们即可实现基于Karaf的项目自动打包、测试及发布。