blob: e56b32eb71c5cd7e90377318ef6d8f7d8539d457 [file] [log] [blame]
Stuart McCulloch7c961f52008-01-02 08:56:07 +00001<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
Stuart McCulloch282f1122008-02-06 05:12:24 +00002<html><head><title>Apache Felix - Maven OBR Plugin</title>
Stuart McCulloch7c961f52008-01-02 08:56:07 +00003
4
5
6
7 <link rel="stylesheet" href="maven-obr-plugin_files/site.css" type="text/css" media="all">
8 <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"></head><body>
9 <div class="title"><div class="logo"><a href="http://felix.apache.org/site/index.html"><img alt="Apache Felix" src="maven-obr-plugin_files/logo.png" border="0"></a></div><div class="header"><a href="http://www.apache.org/"><img alt="Apache" src="maven-obr-plugin_files/apache.png" border="0"></a></div></div>
10 <div class="menu">
11<ul>
12 <li><a href="http://felix.apache.org/site/index.html" title="Index">home</a></li>
13 <li><a href="http://felix.apache.org/site/news.html" title="news">news</a></li>
14 <li><a href="http://felix.apache.org/site/status.html" title="status">status</a></li>
15 <li><a href="http://felix.apache.org/site/license.html" title="license">license</a></li>
Stuart McCulloch282f1122008-02-06 05:12:24 +000016 <li><span class="nobr"><a href="http://felix.apache.org/site/downloads.cgi">downloads<sup><img class="rendericon" src="maven-obr-plugin_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span></li>
Stuart McCulloch7c961f52008-01-02 08:56:07 +000017 <li><a href="http://felix.apache.org/site/documentation.html" title="documentation">documentation</a></li>
18 <li><a href="http://felix.apache.org/site/mailinglists.html" title="mailinglists">mailing lists</a></li>
Stuart McCulloch282f1122008-02-06 05:12:24 +000019 <li><span class="nobr"><a href="http://cwiki.apache.org/confluence/x/O-">wiki<sup><img class="rendericon" src="maven-obr-plugin_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span></li>
Stuart McCulloch7c961f52008-01-02 08:56:07 +000020 <li><a href="http://felix.apache.org/site/committers.html" title="committers">committers</a></li>
21 <li><a href="http://felix.apache.org/site/faq.html" title="faq">faq</a></li>
22 <li><a href="http://felix.apache.org/site/roadmap.html" title="roadmap">roadmap</a></li>
23 <li><a href="http://felix.apache.org/site/sourcecode.html" title="sourcecode">source code</a></li>
24 <li><a href="http://felix.apache.org/site/codingstandards.html" title="codingstandards">coding standards</a></li>
25 <li><a href="http://felix.apache.org/site/issuetracking.html" title="issuetracking">issue tracking</a></li>
26 <li><a href="http://felix.apache.org/site/dependencies.html" title="dependencies">dependencies</a></li>
Stuart McCulloch282f1122008-02-06 05:12:24 +000027 <li><span class="nobr"><a href="http://www.apache.org/">apache software foundation<sup><img class="rendericon" src="maven-obr-plugin_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span></li>
28 <li><span class="nobr"><a href="http://www.apache.org/foundation/sponsorship.html">sponsorship<sup><img class="rendericon" src="maven-obr-plugin_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span></li>
29 <li><span class="nobr"><a href="http://www.apache.org/foundation/thanks.html">sponsors<sup><img class="rendericon" src="maven-obr-plugin_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span></li>
Stuart McCulloch7c961f52008-01-02 08:56:07 +000030</ul> </div>
31 <div class="main">
Stuart McCulloch282f1122008-02-06 05:12:24 +000032<p>This Maven plug-in aims to automate OBR (OSGi Bundle Repository)
33management. It helps manage a local OBR for your local Maven
34repository, and also supports remote OBRs for bundle distribution. The
35plug-in automatically computes bundle capabilities and requirements,
36using a combination of Bindex and Maven metadata.</p>
Stuart McCulloch7c961f52008-01-02 08:56:07 +000037
Stuart McCulloch282f1122008-02-06 05:12:24 +000038<h2><a name="MavenOBRPlugin-Features"></a>Features</h2>
Stuart McCulloch7c961f52008-01-02 08:56:07 +000039
Stuart McCulloch282f1122008-02-06 05:12:24 +000040<p>The maven-obr-plugin supports:</p>
41
Stuart McCulloch7c961f52008-01-02 08:56:07 +000042<ul>
Stuart McCulloch282f1122008-02-06 05:12:24 +000043 <li>Management of both local and remote OBRs</li>
44 <li>Registering Maven and non-Maven artifacts with OBRs</li>
45 <li>Automatically discovering bundle capabilities and requirements</li>
Stuart McCulloch7c961f52008-01-02 08:56:07 +000046 <li>Customizing bundle descriptions</li>
47</ul>
48
49
Stuart McCulloch282f1122008-02-06 05:12:24 +000050<h2><a name="MavenOBRPlugin-Howtousethemavenobrplugin?"></a>How to use the maven-obr-plugin?</h2>
Stuart McCulloch7c961f52008-01-02 08:56:07 +000051
52<p>The plug-in offers five Maven goals:</p>
Stuart McCulloch282f1122008-02-06 05:12:24 +000053
Stuart McCulloch7c961f52008-01-02 08:56:07 +000054<ul>
Stuart McCulloch282f1122008-02-06 05:12:24 +000055 <li><b>install</b> adds the current bundle project to the local OBR</li>
56 <li><b>install-file</b> adds a local bundle file to the local OBR</li>
57 <li><b>deploy</b> adds the current bundle project to a remote OBR</li>
58 <li><b>deploy-file</b> adds a local bundle file to a remote OBR</li>
59 <li><b>clean</b> cleans the local OBR, removing missing bundles</li>
Stuart McCulloch7c961f52008-01-02 08:56:07 +000060</ul>
61
62
Stuart McCulloch282f1122008-02-06 05:12:24 +000063<p>Any of these goals can be disabled by setting <tt>-DobrRepository=NONE</tt></p>
Stuart McCulloch7c961f52008-01-02 08:56:07 +000064
Stuart McCulloch282f1122008-02-06 05:12:24 +000065<h2><a name="MavenOBRPlugin-obr:install"></a>obr:install</h2>
Stuart McCulloch7c961f52008-01-02 08:56:07 +000066
Stuart McCulloch282f1122008-02-06 05:12:24 +000067<p>The <b>install</b> goal updates the local OBR with the details of the installed bundle from the local Maven repository.</p>
Stuart McCulloch7c961f52008-01-02 08:56:07 +000068
Stuart McCulloch282f1122008-02-06 05:12:24 +000069<p>(If the project has an <tt>obr.xml</tt> file somewhere in its resources, then it will be automatically detected and applied.)</p>
Stuart McCulloch7c961f52008-01-02 08:56:07 +000070
Stuart McCulloch282f1122008-02-06 05:12:24 +000071<p>configuration:</p>
Stuart McCulloch7c961f52008-01-02 08:56:07 +000072
Stuart McCulloch7c961f52008-01-02 08:56:07 +000073<ul>
Stuart McCulloch282f1122008-02-06 05:12:24 +000074 <li><em>obrRepository</em> path to local OBR, defaults to <em>&lt;local-maven-repository&gt;</em><tt>/repository.xml</tt></li>
Stuart McCulloch7c961f52008-01-02 08:56:07 +000075</ul>
76
77
Stuart McCulloch282f1122008-02-06 05:12:24 +000078<p>To attach this goal to your project's lifecycle, use:</p>
79
80<div class="code"><div class="codeContent">
81<pre class="code-xml"><span class="code-tag">&lt;plugin&gt;</span>
82 <span class="code-tag">&lt;groupId&gt;</span>org.apache.felix<span class="code-tag">&lt;/groupId&gt;</span>
83 <span class="code-tag">&lt;artifactId&gt;</span>maven-obr-plugin<span class="code-tag">&lt;/artifactId&gt;</span>
84 <span class="code-tag">&lt;version&gt;</span>1.2.0-SNAPSHOT<span class="code-tag">&lt;/version&gt;</span>
85 <span class="code-tag">&lt;executions&gt;</span>
86 <span class="code-tag">&lt;execution&gt;</span>
87 <span class="code-tag">&lt;goals&gt;</span>
88 <span class="code-tag">&lt;goal&gt;</span>install<span class="code-tag">&lt;/goal&gt;</span>
89 <span class="code-tag">&lt;/goals&gt;</span>
90 <span class="code-tag">&lt;/execution&gt;</span>
91 <span class="code-tag">&lt;/executions&gt;</span>
92<span class="code-tag">&lt;/plugin&gt;</span></pre>
93</div></div>
94
95<h2><a name="MavenOBRPlugin-obr:installfile"></a>obr:install-file</h2>
96
97<p>The <b>install-file</b> goal updates the local OBR with the details of a bundle from the local filesystem.</p>
98
99<p>configuration:</p>
100
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000101<ul>
Stuart McCulloch282f1122008-02-06 05:12:24 +0000102 <li><em>obrRepository</em> path to local OBR, defaults to <em>&lt;local-maven-repository&gt;</em><tt>/repository.xml</tt></li>
103 <li><em>groupId</em> Maven groupId for the bundle, taken from <em>pomFile</em> if given</li>
104 <li><em>artifactId</em> Maven artifactId for the bundle, taken from <em>pomFile</em> if given</li>
105 <li><em>version</em> Maven version for the bundle, taken from <em>pomFile</em> if given</li>
106 <li><em>packaging</em> Maven packaging type for the bundle, taken from <em>pomFile</em> if given</li>
107 <li><em>classifier</em> Maven classifier type, defaults to none</li>
108 <li><em>pomFile</em> optional Pom file describing the bundle</li>
109 <li><em>file</em> bundle file, defaults to the bundle from the local Maven repository</li>
110 <li><em>obrXml</em> optional additional properties for the bundle</li>
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000111</ul>
112
113
Stuart McCulloch282f1122008-02-06 05:12:24 +0000114<p>Example:</p>
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000115
Stuart McCulloch282f1122008-02-06 05:12:24 +0000116<div class="preformatted"><div class="preformattedContent">
117<pre>mvn org.apache.felix:maven-obr-plugin:1.2.0-SNAPSHOT:install-file \
118 -DpomFile=myPom.xml -Dfile=foo-1.0.jar
119</pre>
120</div></div>
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000121
Stuart McCulloch282f1122008-02-06 05:12:24 +0000122<h2><a name="MavenOBRPlugin-obr:deploy"></a>obr:deploy</h2>
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000123
Stuart McCulloch282f1122008-02-06 05:12:24 +0000124<p>The <b>deploy goal</b> updates the remote OBR with the details of
125the deployed bundle from the local Maven repository. The remote OBR is
126found by querying the <tt>&lt;distributionManagement&gt;</tt> section of the project, unless <tt>-DaltDeploymentRepository</tt> is set. See <span class="nobr"><a href="http://maven.apache.org/plugins/maven-deploy-plugin/deploy-mojo.html" title="Visit page outside Confluence" rel="nofollow">http://maven.apache.org/plugins/maven-deploy-plugin/deploy-mojo.html<sup><img class="rendericon" src="maven-obr-plugin_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span> for more details about these particular settings.</p>
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000127
Stuart McCulloch282f1122008-02-06 05:12:24 +0000128<p>(If the project has an <tt>obr.xml</tt> file somewhere in its resources, then it will be automatically detected and applied.)</p>
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000129
Stuart McCulloch282f1122008-02-06 05:12:24 +0000130<p>configuration:</p>
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000131
Stuart McCulloch282f1122008-02-06 05:12:24 +0000132<ul>
133 <li><em>obrRepository</em> name of remote OBR, defaults to <tt>repository.xml</tt></li>
134 <li><em>altDeploymentRepository</em> alternative remote repository, <em>id::layout::url</em></li>
135 <li><em>ignoreLock</em> ignore remote locking when updating the OBR</li>
136</ul>
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000137
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000138
Stuart McCulloch282f1122008-02-06 05:12:24 +0000139<p>To attach this goal to your project's lifecycle, use:</p>
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000140
Stuart McCulloch282f1122008-02-06 05:12:24 +0000141<div class="code"><div class="codeContent">
142<pre class="code-xml"><span class="code-tag">&lt;plugin&gt;</span>
143 <span class="code-tag">&lt;groupId&gt;</span>org.apache.felix<span class="code-tag">&lt;/groupId&gt;</span>
144 <span class="code-tag">&lt;artifactId&gt;</span>maven-obr-plugin<span class="code-tag">&lt;/artifactId&gt;</span>
145 <span class="code-tag">&lt;version&gt;</span>1.2.0-SNAPSHOT<span class="code-tag">&lt;/version&gt;</span>
146 <span class="code-tag">&lt;executions&gt;</span>
147 <span class="code-tag">&lt;execution&gt;</span>
148 <span class="code-tag">&lt;goals&gt;</span>
149 <span class="code-tag">&lt;goal&gt;</span>deploy<span class="code-tag">&lt;/goal&gt;</span>
150 <span class="code-tag">&lt;/goals&gt;</span>
151 <span class="code-tag">&lt;/execution&gt;</span>
152 <span class="code-tag">&lt;/executions&gt;</span>
153<span class="code-tag">&lt;/plugin&gt;</span></pre>
154</div></div>
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000155
Stuart McCulloch282f1122008-02-06 05:12:24 +0000156<h2><a name="MavenOBRPlugin-obr:deployfile"></a>obr:deploy-file</h2>
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000157
Stuart McCulloch282f1122008-02-06 05:12:24 +0000158<p>The <b>deploy-file</b> goal updates the remote OBR with the details of a deployed bundle from the local filesystem. The remote OBR is found using the <tt>-DrepositoryId</tt> and <tt>-Durl</tt> parameters. See <span class="nobr"><a href="http://maven.apache.org/plugins/maven-deploy-plugin/deploy-file-mojo.html" title="Visit page outside Confluence" rel="nofollow">http://maven.apache.org/plugins/maven-deploy-plugin/deploy-file-mojo.html<sup><img class="rendericon" src="maven-obr-plugin_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span> for more details about these particular settings.</p>
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000159
Stuart McCulloch282f1122008-02-06 05:12:24 +0000160<p>You can use the <tt>-DbundleUrl</tt> parameter to give the public location of the deployed bundle, which may differ from the remote OBR location.</p>
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000161
Stuart McCulloch282f1122008-02-06 05:12:24 +0000162<p>configuration:</p>
163
164<ul>
165 <li><em>obrRepository</em> name of remote OBR, defaults to <tt>repository.xml</tt></li>
166 <li><em>repositoryId</em> optional repository id, used to lookup authentication settings</li>
167 <li><em>url</em> remote repository transport URL, like <div class="preformatted"><div class="preformattedContent">
168<pre>scpexe://host/path/to/obr</pre>
169</div></div></li>
170 <li><em>bundleUrl</em> public URL of deployed bundle, like <div class="preformatted"><div class="preformattedContent">
171<pre>http://www.foo.org/bundles/foo.jar</pre>
172</div></div></li>
173 <li><em>groupId</em> Maven groupId for the bundle, taken from <em>pomFile</em> if given</li>
174 <li><em>artifactId</em> Maven artifactId for the bundle, taken from <em>pomFile</em> if given</li>
175 <li><em>version</em> Maven version for the bundle, taken from <em>pomFile</em> if given</li>
176 <li><em>packaging</em> Maven packaging type for the bundle, taken from <em>pomFile</em> if given</li>
177 <li><em>classifier</em> Maven classifier type, defaults to none</li>
178 <li><em>pomFile</em> optional Pom file describing the bundle</li>
179 <li><em>file</em> bundle file, defaults to the bundle from the local Maven repository</li>
180 <li><em>obrXml</em> optional additional properties for the bundle</li>
181 <li><em>ignoreLock</em> ignore remote locking when updating the OBR</li>
182</ul>
183
184
185<p>Example:</p>
186
187<div class="preformatted"><div class="preformattedContent">
188<pre>mvn org.apache.felix:maven-obr-plugin:1.2.0-SNAPSHOT:deploy-file \
189 -DpomFile=myPom.xml -Dfile=foo-1.0.jar -Durl=file:/tmp/example/OBR \
190 -DbundleUrl=http://www.foo.org/bundles/foo.jar
191</pre>
192</div></div>
193
194<h2><a name="MavenOBRPlugin-obr:clean"></a>obr:clean</h2>
195
196<p>Sometimes you would like to clean your local OBR because it contains
197bundles that are no longer in your local Maven repository. This case
198often occurs when artifacts were deleted manually. The maven-obr-plugin
199provides a simple goal to check for missing bundles, and remove them
200from the local OBR.</p>
201
202<p>configuration:</p>
203
204<ul>
205 <li><em>obrRepository</em> path to local OBR, defaults to <em>&lt;local-maven-repository&gt;<tt></tt></em><tt>/repository.xml</tt></li>
206</ul>
207
208
209<p>To attach this goal to your project's lifecycle, use:</p>
210
211<div class="code"><div class="codeContent">
212<pre class="code-xml"><span class="code-tag">&lt;plugin&gt;</span>
213 <span class="code-tag">&lt;groupId&gt;</span>org.apache.felix<span class="code-tag">&lt;/groupId&gt;</span>
214 <span class="code-tag">&lt;artifactId&gt;</span>maven-obr-plugin<span class="code-tag">&lt;/artifactId&gt;</span>
215 <span class="code-tag">&lt;version&gt;</span>1.2.0-SNAPSHOT<span class="code-tag">&lt;/version&gt;</span>
216 <span class="code-tag">&lt;executions&gt;</span>
217 <span class="code-tag">&lt;execution&gt;</span>
218 <span class="code-tag">&lt;goals&gt;</span>
219 <span class="code-tag">&lt;goal&gt;</span>clean<span class="code-tag">&lt;/goal&gt;</span>
220 <span class="code-tag">&lt;/goals&gt;</span>
221 <span class="code-tag">&lt;/execution&gt;</span>
222 <span class="code-tag">&lt;/executions&gt;</span>
223<span class="code-tag">&lt;/plugin&gt;</span></pre>
224</div></div>
225
226<h2><a name="MavenOBRPlugin-Concurrentupdates"></a>Concurrent updates</h2>
227
228<p>With a remote OBR, several uploads may occur at the same time.
229However, the remote OBR is centralized in one file, so concurrent
230modification must be avoided. To achieve this, the plug-in implements a
231locking system. Each time the plug-in tries to modify the file it sets
232a file based lock. If it can't take the lock, it will wait and retry.
233After 3 attempts the upload process fails. To bypass this lock add <tt>-DignoreLock</tt> to the command-line (or add <tt>&lt;ignoreLock&gt;true&lt;ignoreLock&gt;</tt> to the configuration section of your Pom).</p>
234
235<h2><a name="MavenOBRPlugin-FTPprotocol"></a>FTP protocol</h2>
236
237<p>Not all protocols are supported by Maven out of the box. For example the ftp protocol requires the <b>wagon-ftp</b> component. To enable the ftp protocol add this to your Pom:</p>
238
239<div class="code"><div class="codeContent">
240<pre class="code-xml"><span class="code-tag">&lt;build&gt;</span>
241 <span class="code-tag">&lt;extensions&gt;</span>
242 <span class="code-tag">&lt;extension&gt;</span>
243 <span class="code-tag">&lt;groupId&gt;</span>org.apache.maven.wagon<span class="code-tag">&lt;/groupId&gt;</span>
244 <span class="code-tag">&lt;artifactId&gt;</span>wagon-ftp<span class="code-tag">&lt;/artifactId&gt;</span>
245 <span class="code-tag">&lt;version&gt;</span>1.0-alpha-6<span class="code-tag">&lt;/version&gt;</span>
246 <span class="code-tag">&lt;/extension&gt;</span>
247 <span class="code-tag">&lt;/extensions&gt;</span>
248<span class="code-tag">&lt;/build&gt;</span></pre>
249</div></div>
250
251<h2><a name="MavenOBRPlugin-Howtheplugincomputesthedescriptionofthebundle"></a>How the plug-in computes the description of the bundle</h2>
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000252
253<p>The description of the bundle comes from three different sources:</p>
Stuart McCulloch282f1122008-02-06 05:12:24 +0000254
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000255<ul>
Stuart McCulloch282f1122008-02-06 05:12:24 +0000256 <li>Bindex : Bindex is a tool that analyzes a bundle manifest to generate OBR description</li>
257 <li>pom.xml : by analyzing the pom file, various information is collected (symbolic name ...)</li>
258 <li>obr.xml : this file contains customized description and capabilities for the bundle</li>
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000259</ul>
260
261
Stuart McCulloch282f1122008-02-06 05:12:24 +0000262<p>These sources are merged together using the following precedence:</p>
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000263
Stuart McCulloch282f1122008-02-06 05:12:24 +0000264<div class="preformatted"><div class="preformattedContent">
265<pre>Bindex
266| (overrides)
267pom.xml
268| (overrides)
269obr.xml
270</pre>
271</div></div>
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000272
Stuart McCulloch282f1122008-02-06 05:12:24 +0000273<p>A warning message is displayed when existing information is overridden.</p>
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000274
Stuart McCulloch282f1122008-02-06 05:12:24 +0000275<h2><a name="MavenOBRPlugin-Knownissues&amp;limitations"></a>Known issues &amp; limitations</h2>
276
277<ol>
278 <li>obr.xml (file given by the user to add properties not found
279by Bindex) must be correct, because the plug-in does not check its
280syntax.</li>
281</ol>
282
Stuart McCulloch7c961f52008-01-02 08:56:07 +0000283 </div>
Stuart McCulloch282f1122008-02-06 05:12:24 +0000284 </body></html>