Author: buildbot
Date: Thu Jun 13 10:25:20 2013
New Revision: 865537
Log:
Staging update by buildbot for felix
Modified:
websites/staging/felix/trunk/content/ (props changed)
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-maven-bundle-plugin-bnd.html
Propchange: websites/staging/felix/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Thu Jun 13 10:25:20 2013
@@ -1 +1 @@
-1492609
+1492610
Modified:
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-maven-bundle-plugin-bnd.html
==============================================================================
---
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-maven-bundle-plugin-bnd.html
(original)
+++
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-maven-bundle-plugin-bnd.html
Thu Jun 13 10:25:20 2013
@@ -125,7 +125,7 @@
<h2 id="instructions">Instructions</h2>
<h3 id="export-package"><code><Export-Package></code></h3>
<p>The <code><Export-Package></code> instruction is a list of packages
for the bundle to export. These packages are copied into the resulting bundle
JAR file from the available classes (i.e., project classes, dependencies, and
class path); thus, it is possible to include classes into your bundle that are
not associated with source files in your project.
<code><Export-Package></code> can be specified with package patterns
using the '*' wildcard. Also, it is possible to exclude packages using negation
by starting the package pattern with '!'. Thus, non-negated patterns indicate
which of the available packages to include in the bundle, whereas negated
patterns indicate which should not be included in the bundle.</p>
-<p>The list of package patterns is ordered and earlier patterns are applied
before later patterns. For example, if you specify
"<code>org.foo.*,\!org.foo.impl</code>" the second pattern has no effect since
all <code>org.foo</code> packages have already been selected by the first
pattern. Instead, you should specify "<code>\!org.foo.impl,org.foo.\*</code>",
which will export all <code>org.foo</code> packages except
<code>org.foo.impl</code>.</p>
+<p>The list of package patterns is ordered and earlier patterns are applied
before later patterns. For example, if you specify
"<code>org.foo.*,!org.foo.impl</code>" the second pattern has no effect since
all <code>org.foo</code> packages have already been selected by the first
pattern. Instead, you should specify "<code>!org.foo.impl,org.foo.*</code>",
which will export all <code>org.foo</code> packages except
<code>org.foo.impl</code>.</p>
<p>Following standard OSGi R4 syntax, package patterns can include both
directives and attributes, which will be copied appropriately into the
generated Export-Package manifest header. Besides explicitly listing package
version attributes, BND will also determine package versions by examining the
source JAR file or from <code>packageinfo</code> files in the package
directory.</p>
<h3 id="private-package"><code><Private-Package></code></h3>
<p>The <code><Private-Package></code> instruction is similar in every
way to the <code><Export-Package></code> instruction, except for the fact
that these packages will <em>not</em> be exported by the bundle. If a package
is selected by both the export and private package headers, then the export
takes precedence.</p>
@@ -140,9 +140,9 @@
<p>For the <code><Include-Resource></code> instruction, actual file
paths are relative to the <code>pom.xml</code>, while file copy destinations
are relative to the root of the resulting bundle JAR file. In the case of
<code>assignment</code> or <code>simple</code> forms, the <code>PATH</code>
parameter can point to a file or directory. The <code>simple</code> form will
place the resource in the bundle JAR with only the file name, i.e., without any
path component. For example, including <code>src/main/resources/a/b.c</code>
will result in a resource <code>b.c</code> in the root of the bundle JAR. If
the <code>PATH</code> points to a directory, the entire directory hierarchy is
copied into the resulting bundle JAR file relative to the specified directory.
If a specific resource must be placed into a subdirectory of the bundle jar,
then use the <code>assignment</code> form, where the first path is the the
destination path (including file name if the resource is a file)
and the second path is the resource to copy. The <code>inline</code> form
requires a ZIP or JAR file, which will be completely expanded in the bundle
JAR.</p>
<p>If a resource clause is specified inside of "{ ... }" brackets, then
variable substitution will be performed on the resource, where variables in the
resources are denoted with "${ ... }" syntax.</p>
-<p>By default the bundle plugin converts the project's Maven resource
directories into a single <code><Include-Resource></code> instruction. If
you specify your own <code><Include-Resource></code> instruction, this
will replace the generated one. To include the generated list of Maven
resources in your own <code><Include-Resource></code> instruction just
add <code>\{maven-resources\</code>} to the list and it will be expanded
automatically.</p>
+<p>By default the bundle plugin converts the project's Maven resource
directories into a single <code><Include-Resource></code> instruction. If
you specify your own <code><Include-Resource></code> instruction, this
will replace the generated one. To include the generated list of Maven
resources in your own <code><Include-Resource></code> instruction just
add <code>{maven-resources}</code> to the list and it will be expanded
automatically.</p>
<h3 id="import-package"><code><Import-Package></code></h3>
-<p>The <code><Import-Package></code> instruction is a list of packages
that are required by the bundle's contained packages. The default for this
header is "*", resulting in importing all referred packages. This header rarely
has to be explicitly specified. However, in certain cases when there is an
unwanted import, such an import can be removed by using a negation package
pattern. The package patterns work in the same way as for
<code><Export-Package></code>, which means they are ordered. For example,
if you wanted to import all packages except <code>org.foo.impl</code> you would
specify "<code>\!org.foo.impl,\*</code>"</p>
+<p>The <code><Import-Package></code> instruction is a list of packages
that are required by the bundle's contained packages. The default for this
header is "*", resulting in importing all referred packages. This header rarely
has to be explicitly specified. However, in certain cases when there is an
unwanted import, such an import can be removed by using a negation package
pattern. The package patterns work in the same way as for
<code><Export-Package></code>, which means they are ordered. For example,
if you wanted to import all packages except <code>org.foo.impl</code> you would
specify "<code>!org.foo.impl,*</code>"</p>
<h2 id="default-behavior">Default Behavior</h2>
<p>To use this plugin, very little information is required by BND. As part of
the Maven integration, the plugin tries to set reasonable defaults for various
instructions. For example:</p>
<ul>
@@ -155,18 +155,18 @@ Get the symbolic name as groupId + "." +
The computed symbolic name is also stored in the
<code>$(maven-symbolicname)</code> property in case you want to add attributes
or directives to it.</li>
<li><code><Export-Package></code> is now assumed to be the set of
packages in your local Java sources, excluding the default package '.' and any
packages containing 'impl' or 'internal'.
<em>(before version 2 of the bundleplugin it was based on the symbolic
name)</em></li>
-<li>Since 2.2.0 you can also use <code>\{local-packages\</code>} inside
<code><Export-Package></code> and it will be expanded to the set of local
packages.</li>
+<li>Since 2.2.0 you can also use <code>{local-packages}</code> inside
<code><Export-Package></code> and it will be expanded to the set of local
packages.</li>
<li><code><Private-Package></code> is now assumed to be the set of
packages in your local Java sources (note that any packages in both
<code><Export-Package></code> and <code><Private-Package></code>
will be exported).
<em>(before version 2 of the bundleplugin it was assumed to be empty by
default)</em></li>
-<li><code><Import-Package></code> is assumed to be "<code>\*</code>",
which imports everything referred to by the bundle content, but not contained
in the bundle.
+<li><code><Import-Package></code> is assumed to be "<code>*</code>",
which imports everything referred to by the bundle content, but not contained
in the bundle.
<em>Any exported packages are also imported by default, to ensure a consistent
class space.</em></li>
<li><code><Include-Resource></code> is generated from the project's
Maven resources, typically "<code>src/main/resources/</code>", which will copy
the specified project directory hierarchy into the resulting bundle JAR file,
mirroring standard Maven behavior.</li>
-<li><code><Bundle-Version></code> is assumed to be
"<code>$\{pom.version\</code>}" but is normalized to the OSGi version format of
"<code>MAJOR.MINOR.MICRO.QUALIFIER</code>", for example
"<code>2.1-SNAPSHOT</code>" would become "<code>2.1.0.SNAPSHOT</code>".</li>
-<li><code><Bundle-Name></code> is assumed to be
"<code>$\{pom.name\</code>}".</li>
-<li><code><Bundle-Description></code> is assumed to be
"<code>$\{pom.description\</code>}".</li>
-<li><code><Bundle-License></code> is assumed to be
"<code>$\{pom.licenses\</code>}".</li>
-<li><code><Bundle-Vendor></code> is assumed to be
"<code>$\{pom.organization.name\</code>}".</li>
-<li><code><Bundle-DocURL></code> is assumed to be
"<code>$\{pom.organization.url\</code>}".</li>
+<li><code><Bundle-Version></code> is assumed to be
"<code>${pom.version}</code>" but is normalized to the OSGi version format of
"<code>MAJOR.MINOR.MICRO.QUALIFIER</code>", for example
"<code>2.1-SNAPSHOT</code>" would become "<code>2.1.0.SNAPSHOT</code>".</li>
+<li><code><Bundle-Name></code> is assumed to be
"<code>${pom.name}</code>".</li>
+<li><code><Bundle-Description></code> is assumed to be
"<code>${pom.description}</code>".</li>
+<li><code><Bundle-License></code> is assumed to be
"<code>${pom.licenses}</code>".</li>
+<li><code><Bundle-Vendor></code> is assumed to be
"<code>${pom.organization.name}</code>".</li>
+<li><code><Bundle-DocURL></code> is assumed to be
"<code>${pom.organization.url}</code>".</li>
</ul>
<p>Since the plugin creates bundles for OSGi R4, it hard-codes
<code>Bundle-ManifestVersion</code> to be '2'. Additionally, it generates
imports for every export to ensure package substitutability, which is very
important when working with collaborating services. It is possible to override
any of these values (except <code>Bundle-ManifestVersion</code>) just by
specifying the desired value in the plugin configuration section of the POM
file.</p>
<h1 id="detailed-how-to">Detailed "How To"</h1>
@@ -370,7 +370,7 @@ for them in the bundleplugin configurati
</pre></div>
-<p>You'll also need to configure the other plugin to pick up and use the
generated manifest, which is written to
<code>$\{project.build.outputDirectory}/META-INF/MANIFEST.MF</code> by default
(unless you choose a different <code>manifestLocation</code> in the
maven-bundle-plugin configuration). Continuing with our WAR example:</p>
+<p>You'll also need to configure the other plugin to pick up and use the
generated manifest, which is written to
<code>${project.build.outputDirectory}/META-INF/MANIFEST.MF</code> by default
(unless you choose a different <code>manifestLocation</code> in the
maven-bundle-plugin configuration). Continuing with our WAR example:</p>
<div class="codehilite"><pre><span class="nt"><plugin></span>
<span class="nt"><groupId></span>org.apache.maven.plugins<span
class="nt"></groupId></span>
<span class="nt"><artifactId></span>maven-war-plugin<span
class="nt"></artifactId></span>
@@ -505,7 +505,7 @@ configuration options:
</pre></div>
-<p>The plugin uses the <code><Embed-Dependency></code> instruction to
transform the project dependencies into <code><Include-Resource></code>
and <code><Bundle-ClassPath></code> clauses, which are then appended to
the current set of instructions and passed onto BND. If you want the embedded
dependencies to be at the start or middle of
<code><Include-Resource></code> or <code><Bundle-ClassPath></code>
then you can use <code>\{maven-dependencies\</code>}, which will automatically
expand to the relevant clauses.</p>
+<p>The plugin uses the <code><Embed-Dependency></code> instruction to
transform the project dependencies into <code><Include-Resource></code>
and <code><Bundle-ClassPath></code> clauses, which are then appended to
the current set of instructions and passed onto BND. If you want the embedded
dependencies to be at the start or middle of
<code><Include-Resource></code> or <code><Bundle-ClassPath></code>
then you can use <code>{maven-dependencies}</code>, which will automatically
expand to the relevant clauses.</p>
<p>The MATCH section accepts alternatives, separated by <em>|</em>, and can be
negated by using <em>!</em> at the <em>beginning</em> of the MATCH. Use
<em>*</em> to represent zero or more unknown characters and <em>?</em> to
represent zero or one character. You can also use standard Java <a
href="http://java.sun.com/javase/6/docs/api/java/util/regex/Pattern.html";>regexp</a>
constructs. There is no need to escape the <em>.</em> character inside MATCH.
The first MATCH in a clause will filter against the artifactId.</p>
<p>some examples:</p>
<div class="codehilite"><pre><span class="c"><!-- embed all compile and
runtime scope dependencies --></span>
@@ -525,7 +525,7 @@ configuration options:
</pre></div>
-<p>examples of using <code>\{maven-dependencies\</code>}:</p>
+<p>examples of using <code>{maven-dependencies}</code>:</p>
<div class="codehilite"><pre><span class="nt"><Include-Resource></span>
{maven-resources}, {maven-dependencies},
org/foo/Example.class=target/classes/org/foo/Example.class
@@ -760,7 +760,7 @@ As shown in the above example, you could
<h2 id="bundledeploy">bundle:deploy</h2>
-<p>The <em>deploy goal</em> updates the remote OBR with the details of the
deployed bundle from the local Maven repository. The remote OBR is found by
querying the <code><distributionManagement></code> section of the
project, unless <code>\-DaltDeploymentRepository</code> is set. See <a
href="http://maven.apache.org/plugins/maven-deploy-plugin/deploy-mojo.html";>http://maven.apache.org/plugins/maven-deploy-plugin/deploy-mojo.html</a>
for more details about these particular settings.</p>
+<p>The <em>deploy goal</em> updates the remote OBR with the details of the
deployed bundle from the local Maven repository. The remote OBR is found by
querying the <code><distributionManagement></code> section of the
project, unless <code>-DaltDeploymentRepository</code> is set. See <a
href="http://maven.apache.org/plugins/maven-deploy-plugin/deploy-mojo.html";>http://maven.apache.org/plugins/maven-deploy-plugin/deploy-mojo.html</a>
for more details about these particular settings.</p>
<p>(If the project has an <code>obr.xml</code> file somewhere in its
resources, then it will be automatically detected and applied.)</p>
<p>configuration:
<em> </em>remoteOBR<em> name of remote OBR, defaults to NONE (which means no
remote OBR deployment)
@@ -769,8 +769,8 @@ As shown in the above example, you could
</em> <em>ignoreLock</em> ignore remote locking when updating the OBR</p>
<p>This goal is part of the "bundle" packaging lifecycle, but is disabled by
default - to enable just set the <code>remoteOBR</code> parameter.</p>
<h2 id="bundledeploy-file">bundle:deploy-file</h2>
-<p>The <em>deploy-file</em> goal updates the remote OBR with the details of a
deployed bundle from the local filesystem. The remote OBR is found using the
<code>\-DrepositoryId</code> and <code>\-Durl</code> parameters. See <a
href="http://maven.apache.org/plugins/maven-deploy-plugin/deploy-file-mojo.html";>http://maven.apache.org/plugins/maven-deploy-plugin/deploy-file-mojo.html</a>
for more details about these particular settings.</p>
-<p>You can use the <code>\-DbundleUrl</code> parameter to give the public
location of the deployed bundle, which may differ from the remote OBR
location.</p>
+<p>The <em>deploy-file</em> goal updates the remote OBR with the details of a
deployed bundle from the local filesystem. The remote OBR is found using the
<code>-DrepositoryId</code> and <code>-Durl</code> parameters. See <a
href="http://maven.apache.org/plugins/maven-deploy-plugin/deploy-file-mojo.html";>http://maven.apache.org/plugins/maven-deploy-plugin/deploy-file-mojo.html</a>
for more details about these particular settings.</p>
+<p>You can use the <code>-DbundleUrl</code> parameter to give the public
location of the deployed bundle, which may differ from the remote OBR
location.</p>
<p>configuration:
<em> </em>remoteOBR<em> name of remote OBR, defaults to an empty string
</em> <em>obrRepository</em> used when the remoteOBR name is blank, defaults
to <code>repository.xml</code>
@@ -827,7 +827,7 @@ As shown in the above example, you could
<strong> <code>%f</code> file name
</strong> <code>%p</code> file path</p>
<h2 id="concurrent-updates">Concurrent updates</h2>
-<p>With a remote OBR, several uploads may occur at the same time. However, the
remote OBR is centralized in one file, so concurrent modification must be
avoided. To achieve this, the plug-in implements a locking system. Each time
the plug-in tries to modify the file it sets a file based lock. If it can't
take the lock, it will wait and retry. After 3 attempts the upload process
fails. To bypass this lock add <code>\-DignoreLock</code> to the command-line
(or add <code><ignoreLock>true<ignoreLock></code> to the
configuration section of your Pom).</p>
+<p>With a remote OBR, several uploads may occur at the same time. However, the
remote OBR is centralized in one file, so concurrent modification must be
avoided. To achieve this, the plug-in implements a locking system. Each time
the plug-in tries to modify the file it sets a file based lock. If it can't
take the lock, it will wait and retry. After 3 attempts the upload process
fails. To bypass this lock add <code>-DignoreLock</code> to the command-line
(or add <code><ignoreLock>true<ignoreLock></code> to the
configuration section of your Pom).</p>
<h2 id="ftp-protocol">FTP protocol</h2>
<p>Not all protocols are supported by Maven out of the box. For example the
ftp protocol requires the <em>wagon-ftp</em> component. To enable the ftp
protocol add this to your Pom:</p>
<div class="codehilite"><pre><span class="nt"><build></span>
@@ -864,7 +864,7 @@ As shown in the above example, you could
<h1 id="feedback">Feedback</h1>
<p>Subscribe to the Felix users mailing list by sending a message to <a
href="mailto:users-subscr...@felix.apache.org";>users-subscr...@felix.apache.org</a>;
after subscribing, email questions or feedback to <a
href="mailto:us...@felix.apache.org";>us...@felix.apache.org</a>.</p>
<div class="timestamp" style="margin-top: 30px; font-size: 80%;
text-align: right;">
- Rev. 1492609 by mcculls on Thu, 13 Jun 2013 10:15:10 +0000
+ Rev. 1492610 by mcculls on Thu, 13 Jun 2013 10:25:12 +0000
</div>
<div class="trademarkFooter">
Apache Felix, Felix, Apache, the Apache feather logo, and the Apache
Felix project
