Table of Contents
Copyright 2008-2012, VMware Inc.
Licensed Under the terms and conditions of the Eclipse Public License Version 1.0 ("EPL"). A copy of the EPL is available at http://www.eclipse.org/legal/epl-v10.html.
Eclipse Public License - v 1.0
THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE
PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR
DISTRIBUTION OF THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS
AGREEMENT.
1. DEFINITIONS
"Contribution" means:
a) in the case of the initial Contributor, the initial
code and documentation distributed under this Agreement, and
b) in the case of each subsequent Contributor:
i) changes to the Program, and
ii) additions to the Program;
where such changes and/or additions to the Program
originate from and are distributed by that particular Contributor. A
Contribution 'originates' from a Contributor if it was added to the
Program by such Contributor itself or anyone acting on such
Contributor's behalf. Contributions do not include additions to the
Program which: (i) are separate modules of software distributed in
conjunction with the Program under their own license agreement, and (ii)
are not derivative works of the Program.
"Contributor" means any person or entity that distributes
the Program.
"Licensed Patents" mean patent claims licensable by a
Contributor which are necessarily infringed by the use or sale of its
Contribution alone or when combined with the Program.
"Program" means the Contributions distributed in accordance
with this Agreement.
"Recipient" means anyone who receives the Program under
this Agreement, including all Contributors.
2. GRANT OF RIGHTS
a) Subject to the terms of this Agreement, each
Contributor hereby grants Recipient a non-exclusive, worldwide,
royalty-free copyright license to reproduce, prepare derivative works
of, publicly display, publicly perform, distribute and sublicense the
Contribution of such Contributor, if any, and such derivative works, in
source code and object code form.
b) Subject to the terms of this Agreement, each
Contributor hereby grants Recipient a non-exclusive, worldwide,
royalty-free patent license under Licensed Patents to make, use, sell,
offer to sell, import and otherwise transfer the Contribution of such
Contributor, if any, in source code and object code form. This patent
license shall apply to the combination of the Contribution and the
Program if, at the time the Contribution is added by the Contributor,
such addition of the Contribution causes such combination to be covered
by the Licensed Patents. The patent license shall not apply to any other
combinations which include the Contribution. No hardware per se is
licensed hereunder.
c) Recipient understands that although each Contributor
grants the licenses to its Contributions set forth herein, no assurances
are provided by any Contributor that the Program does not infringe the
patent or other intellectual property rights of any other entity. Each
Contributor disclaims any liability to Recipient for claims brought by
any other entity based on infringement of intellectual property rights
or otherwise. As a condition to exercising the rights and licenses
granted hereunder, each Recipient hereby assumes sole responsibility to
secure any other intellectual property rights needed, if any. For
example, if a third party patent license is required to allow Recipient
to distribute the Program, it is Recipient's responsibility to acquire
that license before distributing the Program.
d) Each Contributor represents that to its knowledge it
has sufficient copyright rights in its Contribution, if any, to grant
the copyright license set forth in this Agreement.
3. REQUIREMENTS
A Contributor may choose to distribute the Program in object code
form under its own license agreement, provided that:
a) it complies with the terms and conditions of this
Agreement; and
b) its license agreement:
i) effectively disclaims on behalf of all Contributors
all warranties and conditions, express and implied, including warranties
or conditions of title and non-infringement, and implied warranties or
conditions of merchantability and fitness for a particular purpose;
ii) effectively excludes on behalf of all Contributors
all liability for damages, including direct, indirect, special,
incidental and consequential damages, such as lost profits;
iii) states that any provisions which differ from this
Agreement are offered by that Contributor alone and not by any other
party; and
iv) states that source code for the Program is available
from such Contributor, and informs licensees how to obtain it in a
reasonable manner on or through a medium customarily used for software
exchange.
When the Program is made available in source code form:
a) it must be made available under this Agreement; and
b) a copy of this Agreement must be included with each
copy of the Program.
Contributors may not remove or alter any copyright notices contained
within the Program.
Each Contributor must identify itself as the originator of its
Contribution, if any, in a manner that reasonably allows subsequent
Recipients to identify the originator of the Contribution.
4. COMMERCIAL DISTRIBUTION
Commercial distributors of software may accept certain
responsibilities with respect to end users, business partners and the
like. While this license is intended to facilitate the commercial use of
the Program, the Contributor who includes the Program in a commercial
product offering should do so in a manner which does not create
potential liability for other Contributors. Therefore, if a Contributor
includes the Program in a commercial product offering, such Contributor
("Commercial Contributor") hereby agrees to defend and
indemnify every other Contributor ("Indemnified Contributor")
against any losses, damages and costs (collectively "Losses")
arising from claims, lawsuits and other legal actions brought by a third
party against the Indemnified Contributor to the extent caused by the
acts or omissions of such Commercial Contributor in connection with its
distribution of the Program in a commercial product offering. The
obligations in this section do not apply to any claims or Losses
relating to any actual or alleged intellectual property infringement. In
order to qualify, an Indemnified Contributor must: a) promptly notify
the Commercial Contributor in writing of such claim, and b) allow the
Commercial Contributor to control, and cooperate with the Commercial
Contributor in, the defense and any related settlement negotiations. The
Indemnified Contributor may participate in any such claim at its own
expense.
For example, a Contributor might include the Program in a commercial
product offering, Product X. That Contributor is then a Commercial
Contributor. If that Commercial Contributor then makes performance
claims, or offers warranties related to Product X, those performance
claims and warranties are such Commercial Contributor's responsibility
alone. Under this section, the Commercial Contributor would have to
defend claims against the other Contributors related to those
performance claims and warranties, and if a court requires any other
Contributor to pay any damages as a result, the Commercial Contributor
must pay those damages.
5. NO WARRANTY
EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS
PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS
OF ANY KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION,
ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY
OR FITNESS FOR A PARTICULAR PURPOSE. Each Recipient is solely
responsible for determining the appropriateness of using and
distributing the Program and assumes all risks associated with its
exercise of rights under this Agreement , including but not limited to
the risks and costs of program errors, compliance with applicable laws,
damage to or loss of data, programs or equipment, and unavailability or
interruption of operations.
6. DISCLAIMER OF LIABILITY
EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT
NOR ANY CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING
WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OR
DISTRIBUTION OF THE PROGRAM OR THE EXERCISE OF ANY RIGHTS GRANTED
HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
7. GENERAL
If any provision of this Agreement is invalid or unenforceable under
applicable law, it shall not affect the validity or enforceability of
the remainder of the terms of this Agreement, and without further action
by the parties hereto, such provision shall be reformed to the minimum
extent necessary to make such provision valid and enforceable.
If Recipient institutes patent litigation against any entity
(including a cross-claim or counterclaim in a lawsuit) alleging that the
Program itself (excluding combinations of the Program with other
software or hardware) infringes such Recipient's patent(s), then such
Recipient's rights granted under Section 2(b) shall terminate as of the
date such litigation is filed.
All Recipient's rights under this Agreement shall terminate if it
fails to comply with any of the material terms or conditions of this
Agreement and does not cure such failure in a reasonable period of time
after becoming aware of such noncompliance. If all Recipient's rights
under this Agreement terminate, Recipient agrees to cease use and
distribution of the Program as soon as reasonably practicable. However,
Recipient's obligations under this Agreement and any licenses granted by
Recipient relating to the Program shall continue and survive.
Everyone is permitted to copy and distribute copies of this
Agreement, but in order to avoid inconsistency the Agreement is
copyrighted and may only be modified in the following manner. The
Agreement Steward reserves the right to publish new versions (including
revisions) of this Agreement from time to time. No one other than the
Agreement Steward has the right to modify this Agreement. The Eclipse
Foundation is the initial Agreement Steward. The Eclipse Foundation may
assign the responsibility to serve as the Agreement Steward to a
suitable separate entity. Each new version of the Agreement will be
given a distinguishing version number. The Program (including
Contributions) may always be distributed subject to the version of the
Agreement under which it was received. In addition, after a new version
of the Agreement is published, Contributor may elect to distribute the
Program (including its Contributions) under the new version. Except as
expressly stated in Sections 2(a) and 2(b) above, Recipient receives no
rights or licenses to the intellectual property of any Contributor under
this Agreement, whether expressly, by implication, estoppel or
otherwise. All rights in the Program not expressly granted under this
Agreement are reserved.
This Agreement is governed by the laws of the State of New York and
the intellectual property laws of the United States of America. No party
to this Agreement will bring a legal action under this Agreement more
than one year after the cause of action arose. Each party waives its
rights to a jury trial in any resulting litigation.
With the increasing focus on OSGi in Enterprise Java, there has been increasing focus on creating OSGi bundles for deployment. When a development team is creating their own bundles, bundlor simplifies the creation and maintenance of the OSGi metadata of each bundle.
Bundlor also helps in the use of third-party enterprise libraries, many of which are not packaged as OSGi bundles. In this case, developers must add OSGi metadata to the library before use.
Bundlor helps in both these scenarios. It can be very hard for developers to keep track of the dependencies needed by a JAR file. Bundlor is a tool that automates the detection of dependencies and the creation of OSGi manifest directives for JARs after their creation. Bundlor takes as input a JAR and a template consisting of a superset of the standard OSGi manifest headers. Bundlor analyses the source code and support files contained in the JAR, applies the template to the results, and generates a manifest.
The use of Bundlor can take different forms, from an Apache ANT task and an Apache Maven plugin, to simple command line execution.
Eclipse Virgo Bundlor is distributed as a ZIP file.
Download the ZIP file from the Virgo download page.
The Virgo download page is located at http://www.eclipse.org/virgo/download/.
Eclipse Virgo Bundlor can be obtained from an Ivy repository.
Add the Virgo resolver to the ivysettings.xml
file
<url name="eclipse.virgo.build.read.resolver"> <ivy pattern="http://build.eclipse.org/rt/virgo/ivy/bundles/release/[organisation]/[module]/[revision]/[artifact]-[revision].[ext]"/> <artifact pattern="http://build.eclipse.org/rt/virgo/ivy/bundles/release/[organisation]/[module]/[revision]/[artifact]-[revision].[ext]"/> </url>
Download the Eclipse Virgo Bundlor dependency in the build.xml file
<ivy:cachepath resolveId="bundlor.classpath" pathid="bundlor.classpath" organisation="org.eclipse.virgo.bundlor" module="org.eclipse.virgo.bundlor.ant" revision="1.1.2.RELEASE" conf="ant" inline="true" type="jar" log="download-only"/>
Eclipse Virgo Bundlor can be obtained from a Maven repository.
Add the Eclipse Virgo build and SpringSource Enterprise Bundle Repository resolvers to the pom.xml file
<repository> <id>eclipse.virgo.build.bundles.release</id> <name>Eclipse Virgo Build</name> <url>http://build.eclipse.org/rt/virgo/maven/bundles/release</url> </repository> <repository> <id>com.springsource.repository.bundles.external</id> <name>SpringSource Enterprise Bundle Repository - External Bundle Releases</name> <url>http://repository.springsource.com/maven/bundles/external</url> </repository>
Add a dependency to the pom.xml file
<dependencies> <dependency> <groupId>org.eclipse.virgo.bundlor</groupId> <artifactId>org.eclipse.virgo.bundlor.maven</artifactId> <version>1.1.2.RELEASE</version> <scope>compile</scope> </dependency> </dependencies>
The command line client allows Bundlor to be run from the command line.
Change directory to the $BUNDLOR_HOME/bin directory where $BUNDLOR_HOME
is a directory into which the bundlor ZIP file distribution has been unzipped.
Run bundlor.sh or bundlor.bat scripts. See
Section 4.1, “Command-Line Usage” for details.
% ./bundlor.sh \ -i ./org.springframework.integration.jar \ -m ./template.mf \ -o ./target/org.springframework.integration.jar Transformed bundle written to ./target/org.springframework.integration.jar %
The ANT task allows Bundlor to be run from inside any ANT based build system.
Define a bundlor namespace
<project name="bundlor-sample-ant" xmlns:bundlor="antlib:org.eclipse.virgo.bundlor.ant">
Import the bundlor task into your build
<target name="bundlor.init"> <ivy:cachepath resolveId="bundlor.classpath" pathid="bundlor.classpath" organisation="org.eclipse.virgo.bundlor" module="org.eclipse.virgo.bundlor.ant" revision="1.1.2.RELEASE" conf="ant" inline="true" type="jar" log="download-only"/> <taskdef resource="org/eclipse/virgo/bundlor/ant/antlib.xml" uri="antlib:org.eclipse.virgo.bundlor.ant" classpathref="bundlor.classpath"/> </target>
Use the bundlor task. See Section 4.2, “Apache ANT Usage” for details about the
parameters of the task.
<bundlor:bundlor inputPath="${basedir}/target/classes" outputPath="${basedir}/target/classes" bundleVersion="1.0.2.BUILD-${timestamp}" manifestTemplatePath="${basedir}/template.mf"/>
The Maven plugin allows Bundlor to be run from inside any Maven project.
Add the Eclipse Virgo build and SpringSource Enterprise Bundle Repository to the pom.xml file
<pluginRepositories> <pluginRepository> <id>eclipse.virgo.build.bundles.release</id> <name>Eclipse Virgo Build</name> <url>http://build.eclipse.org/rt/virgo/maven/bundles/release</url> </pluginRepository> <pluginRepository> <id>com.springsource.repository.bundles.external</id> <name>SpringSource Enterprise Bundle Repository - External Bundle Releases</name> <url>http://repository.springsource.com/maven/bundles/external</url> </pluginRepository> ... </pluginRepositories>
Use the bundlor plugin in the pom.xml file. See
Section 4.3, “Apache Maven Usage” for details about the parameters of the plugin.
<build> <plugins> <plugin> <groupId>org.eclipse.virgo.bundlor</groupId> <artifactId>org.eclipse.virgo.bundlor.maven</artifactId> <version>1.1.2.RELEASE</version> <executions> <execution> <id>bundlor</id> <goals> <goal>bundlor</goal> </goals> </execution> </executions> </plugin> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-jar-plugin</artifactId> <version>2.4</version> <configuration> <archive> <manifestFile> target/classes/META-INF/MANIFEST.MF </manifestFile> </archive> </configuration> </plugin> ... </plugins> ... </build>
The command line client allows Bundlor to be run from the command line of any platform
To use Bundlor run the following for UNIX and Windows respectively.
$BUNDLOR_HOME/bin/bundlor.sh [options]
%BUNDLOR_HOME%\bin\bundlor.bat [options]
The following table lists all the parameters that you can specify for the bundlor
command line client.
Table 4.1. Attributes
| Attribute | Description | Required |
|---|---|---|
| -f | Whether Bundlor should cause a build failure when there are warnings about the resulting manifest | No - defaults to false |
| -i <path> | The path to the input to create a manifest for. This can either be a directory or a JAR file. | Yes |
| -m <path> | The path to the manifest template. See Chapter 5, Manifest Templates for details. | No |
| -p <path> | The path to the OSGi profile. See Chapter 6, OSGi Profiles and Bundlor for details. | No |
| -o <path> |
The path to write the manifest to. This can either be a directory, a JAR file, or not specified.
If a directory is specified, the manifest will be written to
If a JAR file is specified, the manifest will be written as the manifest for that JAR file.
If nothing is specified, the manifest will be written to
| No - defaults to System.out |
| -r <path> | The path to a properties file used for substitution. See Section 5.3, “Specifying property placeholders” for details. | No |
Property substitution values can be optionally specified on the command line instead of as an external file
using the -Dproperty=value parameter.
% ./bundlor.sh \ -i ./org.springframework.integration.jar \ -m ./template.mf \ -o ./target/org.springframework.integration.jar \ -Dname="Spring Integration" Transformed bundle written to ./target/org.springframework.integration.jar %
See Section 5.3, “Specifying property placeholders” for details.
The ANT task allows you to run Bundlor from inside any ANT based build system
The following procedure shows how to set up Bundlor inside of an existing ANT build file
Define a bundlor namespace
<project name="bundlor-sample-ant" xmlns:bundlor="antlib:org.eclipse.virgo.bundlor.ant">
Import the bundlor task into your build
<target name="bundlor.init"> <ivy:cachepath resolveId="bundlor.classpath" pathid="bundlor.classpath" organisation="org.eclipse.virgo.bundlor" module="org.eclipse.virgo.bundlor.ant" revision="1.1.2.RELEASE" conf="ant" inline="true" type="jar" log="download-only"/> <taskdef resource="org/eclipse/virgo/bundlor/ant/antlib.xml" uri="antlib:org.eclipse.virgo.bundlor.ant" classpathref="bundlor.classpath"/> </target>
This example uses a very simplistic method for building the bundlor task
classpath. It is possible to use a dependency manager such as Ivy to better manage the classpath of
Bundlor.
Use the bundlor task, as shown in the following example. See
Section 4.2.2, “ANT Task Reference” for details about the parameters of the task.
<bundlor:bundlor inputPath="${basedir}/target/classes" outputPath="${basedir}/target/classes" bundleVersion="1.0.2.BUILD-${timestamp}" manifestTemplatePath="${basedir}/template.mf" > <property name="name" value="${ant.project.name}" /> </bundlor:bundlor>
The following table lists all the attributes that you can specify for the bundlor
ANT task.
Table 4.2. Attributes
| Attribute | Description | Required |
|---|---|---|
| bundleSymbolicName | The OSGi Bundle-SymbolicName for the resulting manifest | No |
| bundleVersion | The OSGi Bundle-Version for the resulting manifest | No |
| enabled | Whether Bundlor should create a manifest | No - defaults to true |
| failOnWarnings | Whether Bundlor should cause a build failure when there are warnings about the resulting manifest | No - defaults to false |
| inputPath | The path to the input to create a manifest for. This can either be a directory or a JAR file. | Yes |
| manifestTemplatePath | The path to the manifest template. See Chapter 5, Manifest Templates for details. | No |
| OSGiProfilePath | The path to the OSGi profile. See Chapter 6, OSGi Profiles and Bundlor for details. | No |
| outputPath |
The path to write the manifest to. This can either be a directory, a JAR file, or not specified.
If a directory is specified, the manifest will be written to
If a JAR file is specified, the manifest will be written as the manifest for that JAR file.
If nothing is specified, the manifest will be written to
| No - defaults to System.out |
| propertiesPath | The path to a properties file used for substitution. See Section 5.3, “Specifying property placeholders” for details. | No |
Manifest templates can be optionally specified inline instead of as an external file using the
<manifestTemplate/> element.
<bundlor:bundlor> <manifestTemplate> Bundle-ManifestVersion: 2 Bundle-Name: Bundlor Core Bundle-SymbolicName: org.eclipse.virgo.bundlor Bundle-Version: 0 </manifestTemplate> </bundlor:bundlor>
See Chapter 5, Manifest Templates for details.
OSGi profiles can be optionally specified inline instead of as an external file using the
<OSGiProfile/> element.
<bundlor:bundlor> <OSGiProfile> org.OSGi.framework.system.packages = \ org.eclipse.virgo.osgi.extensions.equinox.hooks,\ javax.accessibility,\ javax.activation,\ javax.activation;version="1.1.1",\ javax.activity,\ javax.annotation,\ ... org.OSGi.framework.bootdelegation = \ org.eclipse.virgo.kernel.authentication,\ com.sun.*,\ javax.xml.*,\ ... </OSGiProfile> </bundlor:bundlor>
See Chapter 6, OSGi Profiles and Bundlor for details.
Property substitution values can be optionally specified inline instead of as an external file using the
<property/> and <propertySet/> elements.
<bundlor:bundlor> <property name="bundle.name" value="Kernel test bundle"/> <property name="bundle.version" value="1.0.2.BUILD-${timestamp}"/> <propertyset> <propertyref builtin="all"/> </propertyset> </bundlor:bundlor>
See Section 5.3, “Specifying property placeholders” for details.
<bundlor:bundlor inputPath="${basedir}/target/classes" outputPath="${basedir}/target/classes" bundleVersion="1.0.2.BUILD-${timestamp}" manifestTemplatePath="${basedir}/template.mf"/>
<bundlor:bundlor inputPath="${basedir}/target/classes" outputPath="${basedir}/target/target/classes" bundleVersion="1.0.2.BUILD-${timestamp}" manifestTemplatePath="${basedir}/template.mf"> <property name="bundle.name" value="Kernel test bundle"/> <property name="bundle.version" value="1.0.2.BUILD-${timestamp}"/> </bundlor:bundlor>
The Maven plugin allows Bundlor to be run from inside any Maven project.
The following procedure shows how to set up Bundlor inside of an existing Maven POM file.
Add the Eclipse Virgo build and SpringSource Enterprise Bundle Repository to the pom.xml file.
<pluginRepositories> <pluginRepository> <id>eclipse.virgo.build.bundles.release</id> <name>Eclipse Virgo Build</name> <url>http://build.eclipse.org/rt/virgo/maven/bundles/release</url> </pluginRepository> <pluginRepository> <id>com.springsource.repository.bundles.external</id> <name>SpringSource Enterprise Bundle Repository - External Bundle Releases</name> <url>http://repository.springsource.com/maven/bundles/external</url> </pluginRepository> ... </pluginRepositories>
Use the bundlor plugin, as shown in the following example. See
Section 4.3.2, “Maven Plugin Reference” for details about the parameters of the plugin.
<build> <plugins> <plugin> <groupId>org.eclipse.virgo.bundlor</groupId> <artifactId>org.eclipse.virgo.bundlor.maven</artifactId> <version>1.1.2.RELEASE</version> <executions> <execution> <id>bundlor</id> <goals> <goal>bundlor</goal> </goals> </execution> </executions> </plugin> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-jar-plugin</artifactId> <version>2.4</version> <configuration> <archive> <manifestFile> target/classes/META-INF/MANIFEST.MF </manifestFile> </archive> </configuration> </plugin> ... </plugins> ... </build>
The following table lists all the elements that you can specify for the bundlor
Maven plugin.
Table 4.3. Elements
| Attribute | Description | Required |
|---|---|---|
| bundleSymbolicName | The OSGi Bundle-SymbolicName for the resulting manifest | No - defaults to ${project.artifactId} |
| bundleVersion | The OSGi Bundle-Version for the resulting manifest | No - defaults to ${project.version} |
| enabled | Whether Bundlor should create a manifest | No - defaults to true |
| failOnWarnings | Whether Bundlor should cause a build failure when there are warnings about the resulting manifest | No - defaults to false |
| inputPath | The path to the input to create a manifest for. This can either be a directory or a JAR file. | No - defaults to ${project.build.outputDirectory} |
| manifestTemplate | An inline manifest template. See Section 4.3.2.2, “Inline Manifest Template” for details. | No |
| manifestTemplatePath | The path to the manifest template. See Chapter 5, Manifest Templates for details. | No - defaults to ${basedir}/template.mf |
| OSGiProfilePath | The path to the OSGi profile. See Chapter 6, OSGi Profiles and Bundlor for details. | No |
| outputPath |
The path to write the manifest to. This can either be a directory, a JAR file, or not specified.
If a directory is specified, the manifest will be written to
If a JAR file is specified, the manifest will be written as the manifest for that JAR file. | No - defaults to ${project.build.outputDirectory} |
| propertiesPath | The path to a properties file used for substitution. See Section 5.3, “Specifying property placeholders” for details. | No |
Manifest templates can be optionally specified inline instead of as an external file using the
<manifestTemplate/> element.
For example:
<execution> <id>bundlor</id> <goals> <goal>bundlor</goal> </goals> <configuration> <manifestTemplate> Bundle-ManifestVersion: 2 Bundle-Name: Bundlor Core Bundle-SymbolicName: org.eclipse.virgo.bundlor Bundle-Version: 0 </manifestTemplate> </configuration> </execution>
See Chapter 5, Manifest Templates for details.
If a <manifestTemplate/> element is specified,
any <manifestTemplatePath/> element is ignored.
OSGi profiles can be optionally specified inline instead of as an external file using the
<OSGiProfile/> element.
<execution> <id>bundlor</id> <goals> <goal>bundlor</goal> </goals> <configuration> <OSGiProfile> org.OSGi.framework.system.packages = \ org.eclipse.virgo.osgi.extensions.equinox.hooks,\ javax.accessibility,\ javax.activation,\ javax.activation;version="1.1.1",\ javax.activity,\ javax.annotation,\ ... org.OSGi.framework.bootdelegation = \ org.eclipse.virgo.kernel.authentication,\ com.sun.*,\ javax.xml.*,\ ... </OSGiProfile> </configuration> </execution>
See Chapter 6, OSGi Profiles and Bundlor for details.
Property substitution values can be optionally specified inline instead of as an external file using the
<properties/> element.
<project> ... <properties> <bundle.name>${project.name}</bundle.name> <bundle.version>2.0.0.RELEASE</bundle.version> </properties> ... </project>
See Section 5.3, “Specifying property placeholders” for details.
<project> ... <build> <plugins> <plugin> <groupId>org.eclipse.virgo.bundlor</groupId> <artifactId>org.eclipse.virgo.bundlor.maven</artifactId> <executions> <execution> <id>bundlor</id> <goals> <goal>bundlor</goal> </goals> </execution> </executions> </plugin> </plugins> </build> ... </project>
<project> ... <properties> <bundle.name>${project.name}</bundle.name> <bundle.version>2.0.0.RELEASE</bundle.version> </properties> ... <build> <plugins> <plugin> <groupId>org.eclipse.virgo.bundlor</groupId> <artifactId>org.eclipse.virgo.bundlor.maven</artifactId> <executions> <execution> <id>bundlor</id> <goals> <goal>bundlor</goal> </goals> </execution> </executions> </plugin> </plugins> </build> ... </project>
A manifest template is a file that Bundlor uses during the generation of OSGi-compliant manifest entries in
a JAR's manifest. The format of the manifest template is the same as that of a standard Java manifest file,
i.e. a series of 'key: value' pairs.
From this template, Bundlor recognizes a specific set of directives and uses them to generate the OSGi-compliant manifest entries. Bundlor will also add any other headers that are specified in the template to the generated manifest. This is typically used to specify things like the bundle's symbolic name and version.
You can also specify property placeholders, or variables, in your manifest template that Bundlor substitutes with actual values at runtime. With this feature, your manifest templates become more dynamic and useful across a variety of your projects. A particularly handy use for this feature is to tell Bundlor to automatically expand versions of imports based on a pattern of your choosing. See Section 5.3, “Specifying property placeholders” for details.
The following table lists the headers you can add to the manifest template, in addition to the standard manifest headers.
Table 5.1. Headers for Manifest Template
| Header | Description |
|---|---|
Excluded-Exports |
A comma-separated list of packages that must not be added to the manifest's
Export-Package header. This is useful for preventing implementation
packages from being exported.
|
Excluded-Imports | By default, Bundlor adds imports for every package that Bundlor determines is referenced by the code or for special files in the jar. Use this header to specify a comma-separated list of packages for which imports Bundlor will not generate. |
Export-Template |
By default, Bundlor versions all exported packages at the specified
Bundle-Version. Use this header to specify that individual exported
packages be exported at different versions. For example,
Export-Template com.foo.*;version="1.5" results in Bundlor versioning any
Export-Package entries for com.foo or its subpackages
at 1.5.
|
Ignored-Existing-Headers | If the JAR for which you are generating a manifest already contains an OSGi-compliant manifest, use this template header to list headers in the original manifest which Bundlor should ignore. |
Import-Template | Use this header to augment package imports that Bundlor generates via bytecode and special file analysis. Typically you use the header to version the import and, in some cases, to mark them as optional. When you use this header to version the import, you can optionally specify a version expansion pattern so that Bundlor sets the version to a range rather than a single version. To use the header, set its value to a comma-separated list of package names and attributes. |
Version-Patterns |
Use this header to declare one or more version expansion patterns and give each one a name.
You can then use these named patterns in the Import-Template header if
you want to specify an expansion pattern for the version of an imported
package. This feature is described in detail later in this section.
|
A wilcard '*' at the end of the package name is supported to match multiple packages. For
example, the header Import-Template: com.foo;version=[1.0,2.0);resolution:=optional,com.bar.*;version="[1.5,1.6)"
will cause any import generated for the com.foo package to be versioned at 1.0
(inclusive) to 2.0 (exclusive) and to be considered optional, and for any import of
com.bar or its sub-packages to be versioned at 1.5 (inclusive) to 1.6 (exclusive).
To specify a property placeholder in your manifest template, use the form
${property.name}, where property.name refers to the name of the
property placeholder. The method in which the manifest template actually gets the value of the property
placeholder at runtime depends on the Bundlor front end you use (command line, ANT, or Maven); the details
are described later.
The following example shows how to use a property placeholder for the Bundle-Name
manifest header rather than a literal.
Bundle-Name: ${bundle.name}
When you use the Import-Template template header to augment package imports that Bundlor
generates in the manifest file, you use the version attribute to specify a
version range of the imported package.
Import-Template: org.eclipse.virgo.kernel.*;version="[1.2.0, 2.0.0)" org.apache.commons.logging;version="[1.1.1, 2.0.0)"
The preceding example specifies that Bundlor should import the org.eclipse.virgo.kernel.*
packages in the range [1.2.0, 2.0.0) and the org.apache.commons.logging
package in the range [1.1.1, 2.0.0) in the generated manifest file. This works just fine for many
use cases, but sometimes the use of literal versions in this manner can be restrictive.
In order to make the manifest template more dynamic and useful, you can specify that Bundlor automatically expand the package version into a version range using an expansion pattern of your choosing. The pattern uses as a base a property placeholder that you define (as described in Section 5.3, “Specifying property placeholders”) and set to a valid OSGi version number. Then, based on the expansion pattern you specify, Bundlor generates a version range using the 4 parts of an OSGi version: major, minor, micro, and qualifier.
The way to tell Bundlor to automatically expand a package import version is to specify the property
placeholder to the right of the version directive of the package in the
Import-Template header, and then within the property placeholder, specify the pattern for
both sides of the version range. The following manifest template snippet shows how to use this feature; the
example is described in detail after the table.
Import-Template:
org.eclipse.virgo.kernel.*;version="${org.eclipse.virgo.kernel:[=.=.=.=, +1.0.0)}",
org.apache.commons.logging.*;version="${org.apache.commons.logging:[=.=.=.=, =.=.+1)}"The following table lists the symbols you can use in the expansion pattern.
Table 5.2. Expansion Pattern Symbols
| Symbol | Description | Location Allowed |
|---|---|---|
| = | Use the same value from the variable. | Valid only in the first three segments (major, minor, micro) of the version pattern. |
| [+/-]n |
Adjust the value from the variable by this amount. For example, +1 means
to add 1 to the value from the variable.
| Valid only in the first three segments (major, minor, micro) of the version pattern. |
| n |
Substitute this value for the one in the variable. Typically you only use this for putting
in a 0.
| Valid only in the first three segments (major, minor, micro) of the version pattern. |
| Any legal qualifier value | Substitute this value for the one in the variable. | Valid only in the fourth (qualifier) segment of the version pattern. |
Based on the descriptions of the symbols, we can now understand how the examples above work. First assume
that you have set the property ${org.eclipse.virgo.kernel} to the value
1.2.0. Based on the expansion pattern, Bundlor sets the version range of the imported
org.eclipse.virgo.kernel.* packages to [1.2.0, 2.0.0). The pattern in
this case first specifies that the beginning of the version range stay exactly the same as the value of the
property. The pattern then specifies that at the end of the version range, the major part of the version
should be one integer larger than what the property is originally set to (1); the pattern
then specifies that the minor and micro segments of the version both be set to 0.
Similarly, assume that you set the ${org.apache.commons.logging} property to
1.4.0. Bundlor generates a version range of [1.4.0, 1.4.1). Again,
the beginning of the range is exactly the same as the property value. The pattern specifies that, in the end
of the range, only the micro segment of the version increase by one; the major and minor segments stay the
same.
If you use the same version expansion pattern for several imports, you can name the pattern using the
Version-Patterns header in the manifest template, and then use this name in the
particular import of Import-Template.
Use the form pattern.name;pattern="pattern"
to specify a named pattern, where pattern.name is the name of the pattern and
pattern is the pattern, such as [=.=.=.=, +1.0.0).
Version-Patterns: apache;pattern="[=.=.=.=, +1.0.0)", hibernate;pattern="[=.=.=.=, =.=.+1)"
The preceding example shows two named patterns: apache and
hibernate. The apache pattern specifies a version range from the
one provided in the property up to but not including the next major version. The
hibernate pattern specifies a version range of the one provided up to but not
including the next micro version.
To use a named pattern, simply substitute it in the Import-Template header in the
place where you would put the in-line pattern.
Import-Template:
org.apache.commons.codec.*;version="${org.apache.commons.codec:apache}",
org.apache.commons.logging.*;version="${org.apache.commons.logging:apache}",
org.hibernate.*;version="${org.hibernate:hibernate}"
org.myorg.*;version="${org.myorg:[]=.=.=.=, =.+1.0.=)}"
In the example, the apache named pattern is used twice, for the two
org.apache imports, and the hibernate pattern is used once. Also
note that you can also include an import whose version is specified with an in-line pattern.
The following shows a simple example of a Bundlor manifest template file, with a description after the sample.
Bundle-ManifestVersion: 2 Bundle-SymbolicName: org.springframework.binding Bundle-Name: ${bundle.name} Import-Package: ognl;version="[2.6.9, 3.0.0)";resolution:=optional, org.jboss.el;version="[2.0.0, 3.0.0)";resolution:=optional Import-Template: org.springframework.*;version="[2.5.4.A, 3.0.0)", org.apache.commons.logging;version="[1.1.1, 2.0.0)", javax.el;version="[2.1.0, 3.0.0)";resolution:=optional, ognl;version="[2.6.9, 3.0.0)";resolution:=optional, org.jboss.el;version="[2.0.0, 3.0.0)";resolution:=optional
The headers marked in bold are required in all manifest templates unless the jar already contains a manifest with those headers.
Bundle-ManifestVersion: This should always be 2Bundle-SymbolicName: specifies a unique name for the bundle of
org.springframework.bindingBundle-Name: specifies a human-readable name for the bundle. The example shows how to
use a property placeholder ${bundle.name}, which at runtime Bundlor will substitute
with an actual value, such as Spring Binding.
Import-Package: hard-codes two packages that will be imported (
ognl and org.jboss.el in the generated manifest. Bundlor isn't
infallible; this lets you add imports that it misses.
Import-Template: specifies the versions for the package imports that Bundlor
generates, marking javax.el, ognl, and
org.jboss.el optional.
When managing and transforming bundles it
can become difficult to remember which packages are boot delegated, which are exported from the system bundle,
and which are from other bundles in your system. This information is important because you typically do not want
to import packages into your own application that are boot delegated, you want to import system bundle packages
at version 0, and you want to define custom imports for all the rest of the bundles. Trying
to keep track of which packages are in each of these categories can be error prone; similarly, defining template
entries for them in your manifest template can be time-consuming and tedious.
To solve this problem, you can specify that Bundlor take an
OSGi profile as input and automatically add template entries for boot
delegated packages and system bundles. These import entries would ignore boot-delegated packages and set the
version of system bundles to version="0". This feature is available for all Bundlor front
ends: command-line, ANT and Maven.
An OSGi profile defines the packages that a particular OSGi runtime (such as Virgo) exports from the system bundle and the packages that it delegates to the boot class loader. An OSGi profile isn't an actual file; rather, it is two properties that are well known to an OSGi runtime. However, when you pass these properties to Bundlor, you pass them as a file, as described in the next section. The properties that make up an OSGi profile are as follows.
org.OSGi.framework.system.packages property defines the packages exported from
the system bundle.
org.OSGi.framework.bootdelegation property defines the packages that are boot
delegated.
If you are using Virgo as your OSGi runtime, see the file
$VIRGO_HOME/configuration/java6-server.profile for its OSGi profile, where
$VIRGO_HOME refers to the main installation directory of Virgo. If you are using
another OSGi runtime, such as Equinox, then see their documentation for their OSGi profile.
For additional information about the syntax of the values of these properties, see the OSGi Core specification.
The first step in using OSGi profiles with Bundlor is to create a file that contains a textual
representation of the two properties that make up an OSGi profile:
org.OSGi.framework.system.packages and
org.OSGi.framework.bootdelegation. What you include in this file is up to you, but
typically you start with the OSGi profile of the OSGi runtime you are using, and then customize it to fit
your environment.
If you are using Virgo as your OSGi runtime, you can start by copying the section of the file
$VIRGO_HOME/configuration/java6-server.profile that refers to the two properties and pasting it
into your text file. If you are using another runtime, consult their documentation.
The following snippet shows a partial OSGi profile for Virgo; for clarity only a few packages are shown. The example shows the format in which you should create your own OSGi profile file.
org.OSGi.framework.system.packages = \ org.eclipse.virgo.osgi.extensions.equinox.hooks,\ javax.accessibility,\ javax.activation,\ javax.activation;version="1.1.1",\ javax.activity,\ javax.annotation,\ ... org.OSGi.framework.bootdelegation = \ org.eclipse.virgo.kernel.authentication,\ com.sun.*,\ javax.xml.*,\ ...
Once you've created your OSGi profile file, the method of passing it to Bundlor depends on the front end you are using to generate a manifest. For detailed information about using the various front ends, see Chapter 4, Usage.
Bundlor's main function is to scan an existing JAR file and determine its runtime dependencies. With this information it can then generate the OSGi-compliant manifest headers needed for proper runtime operation. This analysis is comprised of looking for class references and class names in Java classes and certain well-known file types.
Bundlor scans any Java class it can find in the artifact created by the underlying build system. This means
that if a build process has custom behavior (i.e. weaving with AspectJ or jarjaring),
Bundlor will be able to see and analyze the changes made by that process as long as the changes are in the
artifact created by the build system.
There are a number of places in a Java class that another Java type can be referenced from. Bundlor detects these references and adds manifest requirements for them.
The following is a list of the places that Bundlor will search for type names
Bundlor scans for Spring context configuration files. If it detects this file type, it scans the file for a number of values that contain class names.
Using XPath syntax, the following is a list of values searched for type names
//beans:bean/@class//aop:declare-parents/@implement-interface//aop:declare-parents/@default-impl//context:load-time-weaver/@weaver-class//context:component-scan/@name-generator//context:component-scan/@scope-resolver//jee:jndi-lookup/@expected-type//jee:jndi-lookup/@proxy-interface//jee:remote-slsb/@home-interface//jee:remote-slsb/@business-interface//jee:local-slsb/@business-interface//jms:listener-container/@container-class//lang:jruby/@script-interfaces//lang:bsh/@script-interfaces//oxm:class-to-be-bound/@name//oxm:jibx-marshaller/@target-class//osgi:reference/@interface//osgi:service/@interface//util:list/@list-class//util:map/@map-class//util:set/@set-class//webflow:flow-builder/@class//webflow:attribute/@type//osgi:service/osgi:interfaces/beans:value//osgi:reference/osgi:interfaces/beans:value//context:component-scan/@base-package
Bundlor scans for Blueprint Service configuration files. If it detects this file type, it scans the file for a number of values that contain class names.
Using XPath syntax, the following is a list of values searched for type names
//bp:bean/bp:argument/@type//bp:bean/@class//bp:service/@interface//bp:reference/@interface//bp:reference-list/@interface//bp:map/@key-type//bp:map/@value-type//bp:list/@value-type//bp:set/@value-type//bp:array/@value-type//bp:interfaces/bp:value
Bundlor scans for the Servlet web.xml file located in the WEB-INF
directory. If it detects this file, it scans the file for a number of values that contain class names.
Using XPath syntax, the following is a list of values searched for type names
//context-param/param-values//filter/filter-classs//filter/init-param/param-values//listener/listener-classs//servlet/servlet-classs//servlet/init-param/param-values//error-page/exception-types//env-entry/env-entry-types//ejb-ref/homes//ejb-ref/remotes//ejb-local-ref/local-homes//ejb-local-ref/locals//service-ref/service-interfaces//resource-ref/res-types//resource-env-ref/resource-env-ref-types//message-destination-ref/message-destination-type
Bundlor scans for JAR files located anywhere in the bundle. If it detects this file, it runs the entire set of
analyzers against it. The imports and exports of the JAR file are added to the bundle's manifest and the
JAR file is placed on the bundle's Bundle-Classpath.
Bundlor scans for the JPA persistence.xml and orm.xml files located in the
META-INF directory. If it detects this file it scans the file for a number of values that
contain class names and package names. If the class name is unqualified (i.e. has no '.' in
it), the classname is prepended with the content of the entity-mapping tag's
package element.
Using XPath syntax, the following is a list of values searched for type names
//persistence-unit/provider//persistence-unit/class
Using XPath syntax, the following is a list of values searched for type names
//element-collection/@target-class//embeddable/@class//entity/@class//entity-listener/@class//entity-result/@entity-class//id-class/@class//many-to-many/@target-entity//many-to-one/@target-entity//map-key-class/@class//mapped-superclass/@class//named-native-query/@result-class//one-to-many/@target-entity//one-to-one/@target-entity
Bundlor scans for the EclipseLink eclipselink-orm.xml files located in the
META-INF directory. If it detects this file it scans the file for a number of values that
contain class names and package names. If the class name is unqualified (i.e. has no '.' in
it), the classname is prepended with the content of the entity-mapping tag's
package element.
Using XPath syntax, the following is a list of values searched for type names
//cache-interceptor/@class//converter/@class//copy-policy/@class//customizer/@class//discriminator-class/@value//id-class/@class//element-collection/@target-class//entity/@class//entity-listener/@class//entity-result/@entity-class//embeddable/@class//many-to-many/@target-entity//many-to-one/@target-entity//map-key-class/@class//mapped-superclass/@class//named-native-query/@result-class//named-stored-procedure-query/@result-class//object-type-converter/@data-type//object-type-converter/@object-type//one-to-many/@target-entity//one-to-one/@target-entity//property/@value-type//query-redirectors/@all-queries//query-redirectors/@read-all//query-redirectors/@read-object//query-redirectors/@report//query-redirectors/@update//query-redirectors/@insert//query-redirectors/@delete//read-transformer/@transformer-class//stored-procedure-parameter/@type//struct-converter/@converter//type-converter/@data-type//type-converter/@object-type//variable-one-to-one/@target-interface//write-transformer/@transformer-class
Bundlor scans for any file that ends with a .hbm extension. If it detects one of these files
it scans the file for a number of attributes that can contain class names. If the class name is unqualified
(i.e. has no '.' in it), the classname is prepended with the content of the
hibernate-mapping tag's package attribute. Many of the attributes that can
contain class names can also contain Hibernate keywords corresponding to Hibernate-known types. When these are
detected, no manifest requirements are added.
Using XPath syntax, the following is a list of attributes searched for type names
//class/@name//id/@type//generator/@class//composite-id/@class//discriminator/@type//property/@type//many-to-one/@class//one-to-one/@class//one-to-many/@class//many-to-many/@class//version/@type//component/@class//dynamic-component/@class//subclass/@name//joined-subclass/@name//union-subclass/@name//import/@class
The following is a list of reserved Hibernate keywords that will not trigger the addition of manifest requirements
assignedbig_decimalbig_integerbinaryblobbooleanbytecalendarcalendar_datecharacterclassclobcurrencydatedoublefloatforeignguidhiloidentityimm_binaryimm_calendarimm_calendar_dateimm_dateimm_serializableimm_timeimm_timestampincrementintegerlocalelongnativeselectseqhilosequencesequence-identityserializableshortstringtexttimetimestamptimezonetrue_falseuuidyes_no
Bundlor scans for the JSP files. If it detects this file, it scans the file for a number of values that contain class names.
Bundlor scans for Log4J configuration files. If it detects this file type, it scans the file for a number of values that contain class names.
Bundlor's second function is to scan an existing manifest and identify any potential issues with it.
Bundlor checks that all entries in the Import-Package header have a sensible version range
declared. This ensures that there are no version ranges that are reversed ([2, 1)), and no
version ranges that are empty ([1, 1)).
Bundlor checks that the manifest does not import any package that it exports. This behavior is usually indicative of a package split between two bundles.
Bundlor checks that the manifest does not contain headers indicating that it is from a signed JAR. Running Bundlor against a signed JAR will render that JAR invalid as the manifest will have changed from when it was signed.
Bundlor checks that all entries in the Import-Package header have a version range declared.
Bundlor checks that all entries in the Export-Package header have a version declared.
Bundlor checks that the manifest contains a Bundle-SymbolicName header.