Gitiles
Code Review Sign In
gerrit.onosproject.org / onos-felix / aa24c2e58dd0a5416562a6c613481664316fe4e5 / . / main / doc / apache-felix-osgi-bundle-repository.html
blob: 825a9ff45172fa094d641d17205bce26b8c53079 [file] [log] [blame]
Karl Pauls53fb3122010-02-04 23:19:54 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2<html><head>
3
4
5
6 <title>Apache Felix - Apache Felix OSGi Bundle Repository</title>
7 <link rel="stylesheet" href="apache-felix-osgi-bundle-repository_files/site.css" type="text/css" media="all">
8 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
9 </head><body>
10 <div class="title"><div class="logo"><a href="http://felix.apache.org/site/index.html"><img alt="Apache Felix" src="apache-felix-osgi-bundle-repository_files/logo.png" border="0"></a></div><div class="header"><a href="http://www.apache.org/"><img alt="Apache" src="apache-felix-osgi-bundle-repository_files/apache.png" border="0"></a></div></div>
11 <div class="menu">
12<ul>
13 <li><a href="http://cwiki.apache.org/FELIX/news.html" title="news">news</a></li>
14 <li><a href="http://cwiki.apache.org/FELIX/license.html" title="license">license</a></li>
15 <li><a href="http://felix.apache.org/site/downloads.cgi" rel="nofollow">downloads</a></li>
16 <li><a href="http://cwiki.apache.org/FELIX/documentation.html" title="documentation">documentation</a></li>
17 <li><a href="http://cwiki.apache.org/FELIX/mailinglists.html" title="mailinglists">mailing lists</a></li>
18 <li><a href="http://cwiki.apache.org/FELIX/contributing.html" title="Contributing">contributing</a></li>
19 <li><a href="http://www.apache.org/" rel="nofollow">asf</a></li>
20 <li><a href="http://www.apache.org/foundation/sponsorship.html" rel="nofollow">sponsorship</a></li>
21 <li><a href="http://www.apache.org/foundation/thanks.html" rel="nofollow">sponsors</a>
22<!-- ApacheCon Ad -->
23<iframe src="apache-felix-osgi-bundle-repository_files/button.html" style="border-width: 0pt; float: left;" frameborder="0" height="135" scrolling="no" width="135"></iframe>
24<p style="height: 100px;">
25<!-- ApacheCon Ad -->
26</p></li></ul> </div>
27 <div class="main">
28<h1><a name="ApacheFelixOSGiBundleRepository-ApacheFelixOSGiBundleRepository(OBR)"></a>Apache Felix OSGi Bundle Repository (OBR)</h1>
29
30<div>
31<ul>
32 <li><a href="#ApacheFelixOSGiBundleRepository-Motivation">Motivation</a></li>
33 <li><a href="#ApacheFelixOSGiBundleRepository-Overview">Overview</a></li>
34 <li><a href="#ApacheFelixOSGiBundleRepository-OBRRepositoryFile">OBR Repository File</a></li>
35 <li><a href="#ApacheFelixOSGiBundleRepository-OBRServiceAPI">OBR Service API</a></li>
36 <li><a href="#ApacheFelixOSGiBundleRepository-OBRShellCommand">OBR Shell Command</a></li>
37<ul>
38 <li><a href="#ApacheFelixOSGiBundleRepository-obrhelp">obr help</a></li>
39 <li><a href="#ApacheFelixOSGiBundleRepository-obrlisturl">obr list-url</a></li>
40 <li><a href="#ApacheFelixOSGiBundleRepository-obraddurl">obr add-url</a></li>
41 <li><a href="#ApacheFelixOSGiBundleRepository-obrremoveurl">obr remove-url</a></li>
42 <li><a href="#ApacheFelixOSGiBundleRepository-obrlist">obr list</a></li>
43 <li><a href="#ApacheFelixOSGiBundleRepository-obrinfo">obr info</a></li>
44 <li><a href="#ApacheFelixOSGiBundleRepository-obrdeploy">obr deploy</a></li>
45 <li><a href="#ApacheFelixOSGiBundleRepository-obrstart">obr start</a></li>
46 <li><a href="#ApacheFelixOSGiBundleRepository-obrsource">obr source</a></li>
47 <li><a href="#ApacheFelixOSGiBundleRepository-obrjavadoc">obr javadoc</a></li>
48</ul>
49 <li><a href="#ApacheFelixOSGiBundleRepository-UsingOBRwithaProxy">Using OBR with a Proxy</a></li>
50 <li><a href="#ApacheFelixOSGiBundleRepository-BundleSourcePackaging">Bundle Source Packaging</a></li>
51 <li><a href="#ApacheFelixOSGiBundleRepository-NoteonOSGiR3Bundles">Note on OSGi R3 Bundles</a></li>
52 <li><a href="#ApacheFelixOSGiBundleRepository-Feedback">Feedback</a></li>
53</ul></div>
54
55<p><a name="ApacheFelixOSGiBundleRepository-motivation"></a></p>
56
57<h2><a name="ApacheFelixOSGiBundleRepository-Motivation"></a>Motivation</h2>
58
59<p>The goal of the Apache Felix OSGi Bundle Repository (OBR) is two-fold:</p>
60
61<ol>
62 <li>To simplify deploying and using available bundles with Felix.</li>
63 <li>To encourage independent bundle development so that communities of interest can grow.</li>
64</ol>
65
66
67<p>OBR achieves the first goal by providing a service that can
68automatically install a bundle, with its deployment dependencies, from
69a bundle repository. This makes it easier for people to experiment with
70existing bundles. The second goal is achieved by raising the visibility
71of the available bundles and providing access to both the executable
72bundle and its source code. Hopefully, by making OBR and the bundles
73themselves more visible, community members will be encouraged to
74provide or improve service implementations.</p>
75
76<p>Note: OBR provides access to the Felix' default bundle repository,
77but you can also use it to deploy your own bundles by creating a bundle
78repository meta-data file for your local bundles; see the <tt>obr list-url</tt>, <tt>obr add-url</tt>, and <tt>obr remove-url</tt> commands for more details.</p>
79
80<p><a name="ApacheFelixOSGiBundleRepository-overview"></a></p>
81
82<h2><a name="ApacheFelixOSGiBundleRepository-Overview"></a>Overview</h2>
83
84<p>For the most part, OBR is quite simple. An OBR "repository server"
85is not necessary, since all functionality may reside on the client
86side. OBR is able to provide its functionality by reading an XML-based
87meta-data file that describes the bundles available to it. The
88meta-data file essentially contains an XML encoding of the bundles'
89manifest information. From the meta-data, OBR is able to construct
90dependency information for deploying (i.e., installing and updating)
91bundles.</p>
92
93<p>OBR defines the following entities:</p>
94
95<ul>
96 <li><em><b>Repository Admin</b></em> - a service to access a federation of repositories.</li>
97 <li><em><b>Repository</b></em> - provides access to a set of resources.</li>
98 <li><em><b>Resource</b></em> - a description of an artifact to be installed on a device.</li>
99 <li><em><b>Capability</b></em> - a named set of properties.</li>
100 <li><em><b>Requirement</b></em> - an assertion on a capability.</li>
101 <li><em><b>Resolver</b></em> - an object to resolve resource dependencies and to deploy them.</li>
102 <li><em><b>Repository file</b></em> - XML file containing resource meta-data.</li>
103</ul>
104
105
106<p>The following diagram illustrates the relationships among these entities:</p>
107
108<p><img src="apache-felix-osgi-bundle-repository_files/obr-entities.png" align="absmiddle" border="0"></p>
109
110<p>The client has access to a federated set of repositories via the Repository Admin service; such as depicted in this view:</p>
111
112<p><img src="apache-felix-osgi-bundle-repository_files/obr-high-level.png" align="absmiddle" border="0"></p>
113
114<p><a name="ApacheFelixOSGiBundleRepository-repositoryfile"></a></p>
115
116<h2><a name="ApacheFelixOSGiBundleRepository-OBRRepositoryFile"></a>OBR Repository File</h2>
117
118<p>The OBR repository file is an XML-based representation of bundle
119meta-data. The goal is provide a generic model for describing
120dependencies among resources; as such, the term <em><b>resource</b></em> is used instead of <em><b>bundle</b></em> in the OBR repository syntax; a detailed description of the OBR meta-data format is available in the <a href="http://www2.osgi.org/download/rfc-0112_BundleRepository.pdf" rel="nofollow">OSGi RFC 112</a>
121document; this document is not completely in sync with the
122implementation, but the concepts are still correct. The following XML
123snippet depicts the overall structure of a repository file:</p>
124
125<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
126<pre>&lt;repository presentationname="..." symbolicname="..." ... &gt;
127 &lt;resource&gt;
128 &lt;description&gt;...&lt;/description&gt;
129 &lt;size&gt;...&lt;/size&gt;
130 &lt;documentation&gt;...&lt;/documentation&gt;
131 &lt;source&gt;...&lt;/source&gt;
132 &lt;category id="..."/&gt;
133 &lt;capability&gt;...&lt;/capability&gt;
134 ...
135 &lt;requirement&gt;...&lt;/requirement&gt;
136 ...
137 &lt;/resource&gt;
138 ...
139&lt;/repository&gt;
140</pre>
141</div></div>
142
143<p>The above repository defines a set of available resources, each
144described by a set of meta-data. Some resource meta-data is purely
145intended for human consumption; the most important aspects relate to
146the generic capability/requirement model.</p>
147
148<p>A resource can provide any number of capabilities. A capability is a
149typed set of properties. For example, the following is an exported
150package capability:</p>
151
152<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
153<pre>&lt;capability name='package'&gt;
154 &lt;p n='package' v='org.foo.bar'/&gt;
155 &lt;p n='version' t='version' v='1.0.0'/&gt;
156&lt;/capability&gt;
157</pre>
158</div></div>
159
160<p>This capability is of type 'package' and exports 'org.foo.bar' at
161version '1.0.0'. Conversely, a requirement is a typed LDAP query over a
162set of capability properties. For example, the following is an imported
163package requirement:</p>
164
165<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
166<pre>&lt;require name='package' extend='false'
167 multiple='false' optional='false'
168 filter='(&amp;amp;(package=org.foo.bar)(version&amp;gt;=1.0.0))'&gt;
169 Import package org.foo.bar
170&lt;/require&gt;
171</pre>
172</div></div>
173
174<p>This requirement is of type 'package' and imports 'org.foo.bar' at
175versions greater than '1.0.0'. Although this syntax looks rather
176complicated with the '\&amp;' and '\&gt;=' syntax, it is simply the
177standard OSGi LDAP query syntax in XML form (additionally, Peter Kriens
178has created a tool called <tt>bindex</tt> to generate this meta-data from a bundle's manifest).</p>
179
180<p>With this generic dependency model, OBR is able to provide mappings
181for the various OSGi bundle dependencies; e.g., import/export package,
182provide/require bundle, host/fragment, import/export service, execution
183environment, and native code. In addition, it is possible for bundles
184to introduce arbitrary dependencies for custom purposes.</p>
185
186<p>Two other important pieces of meta-data are <tt>Bundle-SymbolicName</tt> and <tt>Bundle-Version</tt>;
187these are standard OSGi bundle manifest attributes that OBR uses to
188uniquely identify a bundle. For example, if you want to use OBR to
189update a locally installed bundle, OBR gets its symbolic name and
190version and searches the repository metadata for a matching symbolic
191name. If the matching symbolic name is found, then OBR checks if there
192is a newer version than the local copy using the bundle version number.
193Thus, the symbolic name plus bundle version forms a unique key to match
194locally installed bundles to remotely available bundles.</p>
195
196<p><a name="ApacheFelixOSGiBundleRepository-serviceapi"></a></p>
197
198<h2><a name="ApacheFelixOSGiBundleRepository-OBRServiceAPI"></a>OBR Service API</h2>
199
200<p>Typically, OBR service clients only need to interact with the
201Repository Admin service, which provides the mechanisms necessary to
202discover available resources. The Repository Admin interface is defined
203as follows:</p>
204
205<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
206<pre class="code-java"><span class="code-keyword">public</span> <span class="code-keyword">interface</span> RepositoryAdmin
207{
208 <span class="code-keyword">public</span> Resource[] discoverResources(<span class="code-object">String</span> filterExpr);
209 <span class="code-keyword">public</span> Resolver resolver();
210 <span class="code-keyword">public</span> Repository addRepository(URL repository)?
211 <span class="code-keyword">throws</span> Exception;
212 <span class="code-keyword">public</span> <span class="code-object">boolean</span> removeRepository(URL repository);
213 <span class="code-keyword">public</span> Repository[] listRepositories();
214 <span class="code-keyword">public</span> Resource getResource(<span class="code-object">String</span> respositoryId);
215}
216</pre>
217</div></div>
218
219<p>In order to resolve and deploy available resources, the Repository
220Admin provides Resolver instances, which are defined as follows:</p>
221
222<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
223<pre class="code-java"><span class="code-keyword">public</span> <span class="code-keyword">interface</span> Resolver
224{
225 <span class="code-keyword">public</span> void add(Resource resource);
226 <span class="code-keyword">public</span> Requirement[] getUnsatisfiedRequirements();
227 <span class="code-keyword">public</span> Resource[] getOptionalResources();
228 <span class="code-keyword">public</span> Requirement[] getReason(Resource resource);
229 <span class="code-keyword">public</span> Resource[] getResources(Requirement requirement);
230 <span class="code-keyword">public</span> Resource[] getRequiredResources();
231 <span class="code-keyword">public</span> Resource[] getAddedResources();
232 <span class="code-keyword">public</span> <span class="code-object">boolean</span> resolve();
233 <span class="code-keyword">public</span> void deploy(<span class="code-object">boolean</span> start);
234}
235</pre>
236</div></div>
237
238<p>When desired resources are discovered via the query mechanisms of
239the Repository Admin, they are added to a Resolver instance which will
240can be used to resolve all transitive dependencies and to reflect on
241any resolution result. The following code snippet depicts a typical
242usage scenario:</p>
243
244<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
245<pre class="code-java">RepositoryAdmin repoAdmin = ... <span class="code-comment">// Get repo admin service
246</span>Resolver resolver = repoAdmin.resolver();
247Resource resource = repoAdmin.discoverResources(filterStr);
248resolver.add(resource);
249<span class="code-keyword">if</span> (resolver.resolve())
250{
251 resolver.deploy(<span class="code-keyword">true</span>);
252}
253<span class="code-keyword">else</span>
254{
255 Requirement[] reqs = resolver.getUnsatisfiedRequirements();
256 <span class="code-keyword">for</span> (<span class="code-object">int</span> i = 0; i &lt; reqs.length; i++)
257 {
258 <span class="code-object">System</span>.out.println(<span class="code-quote">"Unable to resolve: "</span> + reqs[i]);
259 }
260}
261</pre>
262</div></div>
263
264<p>This code gets the Repository Admin service and then gets a Resolver
265instance from it. It then discovers an available resource and adds it
266to the resolver. Then it tries to resolve the resources dependencies.
267If successful it deploys the resource to the local framework instance;
268if not successful it prints the unsatisfied requirements.</p>
269
270<p>OBR's deployment algorithm appears simple at first glance, but it is
271actually somewhat complex due to the nature of deploying independently
272developed bundles. For example, in an ideal world, if an update for a
273bundle is made available, then updates for all of the bundles
274satisfying its dependencies are also made available. Unfortunately,
275this may not be the case, thus the deployment algorithm might have to
276install new bundles during an update to satisfy either new dependencies
277or updated dependencies that can no longer be satisfied by existing
278local bundles. In response to this type of scenario, the OBR deployment
279algorithm tries to favor updating existing bundles, if possible, as
280opposed to installing new bundles to satisfy dependencies.</p>
281
282<p>In the general case, OBR user's will not use the OBR API directly,
283but will use its functionality indirectly from another tool or user
284interface. For example, interactive access to OBR is available via a
285command for Felix' <a href="http://cwiki.apache.org/confluence/display/FELIX/Apache%20Felix%20Shell%20Service" title="Apache Felix Shell Service">shell service</a>. The OBR shell command is discussed in the next section.</p>
286
287<p><a name="ApacheFelixOSGiBundleRepository-shellcommand"></a></p>
288
289<h2><a name="ApacheFelixOSGiBundleRepository-OBRShellCommand"></a>OBR Shell Command</h2>
290
291<p>Besides providing a service API, OBR implements a Felix shell
292command for accessing its functionality. For the end user, the OBR
293shell command is accessed using the text-based or GUI-based user
294interfaces for Felix' shell service. This section describes the syntax
295for the OBR shell command.</p>
296
297<p><a name="ApacheFelixOSGiBundleRepository-obrhelp"></a></p>
298
299<h3><a name="ApacheFelixOSGiBundleRepository-obrhelp"></a>obr help</h3>
300
301<p>Syntax:</p>
302<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
303<pre>obr help [add-url | remove-url | list-url | list | info | deploy | start | source | javadoc]
304</pre>
305</div></div>
306<p>This command is used to display additional information about the other OBR commands.</p>
307
308<p><a name="ApacheFelixOSGiBundleRepository-obrlisturl"></a></p>
309
310<h3><a name="ApacheFelixOSGiBundleRepository-obrlisturl"></a>obr list-url</h3>
311
312<p>Syntax:</p>
313<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
314<pre>obr list-url
315</pre>
316</div></div>
317<p>This command gets the URLs to the repository files used by the Repository Admin.</p>
318
319<p><a name="ApacheFelixOSGiBundleRepository-obraddurl"></a></p>
320
321<h3><a name="ApacheFelixOSGiBundleRepository-obraddurl"></a>obr add-url</h3>
322
323<p>Syntax:</p>
324<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
325<pre>obr add-url [&lt;repository-file-url&gt; ...]
326</pre>
327</div></div>
328<p>This command adds a repository file to the set of repository files
329for which the Repository Admin service provides access. The repository
330file is represented as a URL. If the repository file URL is already in
331the Repository Admin's set of repository files, the request is treated
332like a reload operation.</p>
333
334<p><a name="ApacheFelixOSGiBundleRepository-obrremoveurl"></a></p>
335
336<h3><a name="ApacheFelixOSGiBundleRepository-obrremoveurl"></a>obr remove-url</h3>
337
338<p>Syntax:</p>
339<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
340<pre>obr remove-url [&lt;repository-file-url&gt; ...]
341</pre>
342</div></div>
343<p>This command removes a repository file to the set of repository
344files for which the Repository Admin service provides access. The
345repository file is represented as a URL.</p>
346
347<p><a name="ApacheFelixOSGiBundleRepository-obrlist"></a></p>
348
349<h3><a name="ApacheFelixOSGiBundleRepository-obrlist"></a>obr list</h3>
350
351<p>Syntax:</p>
352<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
353<pre>obr list [&lt;string&gt; ...]
354</pre>
355</div></div>
356<p>This command lists bundles available in the bundle repository. If no
357arguments are specified, then all available bundles are listed,
358otherwise any arguments are concatenated with spaces and used as a
359substring filter on the bundle names.</p>
360
361<p><a name="ApacheFelixOSGiBundleRepository-obrinfo"></a></p>
362
363<h3><a name="ApacheFelixOSGiBundleRepository-obrinfo"></a>obr info</h3>
364
365<p>Syntax:</p>
366<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
367<pre>obr info &lt;bundle-name&gt;[;&lt;version&gt;] ...
368</pre>
369</div></div>
370<p>This command displays the meta-data for the specified bundles. If a
371bundle's name contains spaces, then it must be surrounded by quotes. It
372is also possible to specify a precise version if more than one version
373exists, such as:</p>
374<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
375<pre>obr info "Bundle Repository";1.0.0
376</pre>
377</div></div>
378<p>The above example retrieves the meta-data for version "1.0.0" of the bundle named "Bundle Repository".</p>
379
380<p><a name="ApacheFelixOSGiBundleRepository-obrdeploy"></a></p>
381
382<h3><a name="ApacheFelixOSGiBundleRepository-obrdeploy"></a>obr deploy</h3>
383
384<p>Syntax:</p>
385<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
386<pre>obr deploy &lt;bundle-name&gt;[;&lt;version&gt;] ... | &lt;bundle-id&gt; ...
387</pre>
388</div></div>
389<p>This command tries to install or update the specified bundles and
390all of their dependencies by default. You can specify either the bundle
391name or the bundle identifier. If a bundle's name contains spaces, then
392it must be surrounded by quotes. It is also possible to specify a
393precise version if more than one version exists, such as:</p>
394<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
395<pre>obr deploy "Bundle Repository";1.0.0
396</pre>
397</div></div>
398<p>For the above example, if version "1.0.0" of "Bundle Repository" is
399already installed locally, then the command will attempt to update it
400and all of its dependencies; otherwise, the command will install it and
401all of its dependencies.</p>
402
403<p><a name="ApacheFelixOSGiBundleRepository-obrstart"></a></p>
404
405<h3><a name="ApacheFelixOSGiBundleRepository-obrstart"></a>obr start</h3>
406
407<p>Syntax:</p>
408<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
409<pre>obr start [-nodeps] &lt;bundle-name&gt;[;&lt;version&gt;] ...
410</pre>
411</div></div>
412<p>This command installs and starts the specified bundles and all of
413their dependencies by default; use the "-nodeps" switch to ignore
414dependencies. If a bundle's name contains spaces, then it must be
415surrounded by quotes. If a specified bundle is already installed, then
416this command has no effect. It is also possible to specify a precise
417version if more than one version exists, such as:</p>
418<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
419<pre>obr start "Bundle Repository";1.0.0
420</pre>
421</div></div>
422<p>The above example installs and starts the "1.0.0" version of the bundle named "Bundle Repository" and its dependencies.</p>
423
424<p><a name="ApacheFelixOSGiBundleRepository-obrsource"></a></p>
425
426<h3><a name="ApacheFelixOSGiBundleRepository-obrsource"></a>obr source</h3>
427
428<p>Syntax:</p>
429<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
430<pre>obr source [-x] &lt;local-dir&gt; &lt;bundle-name&gt;[;&lt;version&gt;] ...
431</pre>
432</div></div>
433<p>This command retrieves the source archives of the specified bundles
434and saves them to the specified local directory; use the "-x" switch to
435automatically extract the source archives. If a bundle name contains
436spaces, then it must be surrounded by quotes. It is also possible to
437specify a precise version if more than one version exists, such as:</p>
438<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
439<pre>obr source /home/rickhall/tmp "Bundle Repository";1.0.0
440</pre>
441</div></div>
442<p>The above example retrieves the source archive of version "1.0.0" of
443the bundle named "Bundle Repository" and saves it to the specified
444local directory.</p>
445
446<h3><a name="ApacheFelixOSGiBundleRepository-obrjavadoc"></a>obr javadoc</h3>
447
448<p>Syntax:</p>
449<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
450<pre>obr javadoc [-x] &lt;local-dir&gt; &lt;bundle-name&gt;[;&lt;version&gt;] ...
451</pre>
452</div></div>
453<p>This command retrieves the javadoc archives of the specified bundles
454and saves them to the specified local directory; use the "-x" switch to
455automatically extract the javadoc archives. If a bundle name contains
456spaces, then it must be surrounded by quotes. It is also possible to
457specify a precise version if more than one version exists, such as:</p>
458<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
459<pre>obr javadoc /home/rickhall/tmp "Bundle Repository";1.0.0
460</pre>
461</div></div>
462<p>The above example retrieves the javadoc archive of version "1.0.0"
463of the bundle named "Bundle Repository" and saves it to the specified
464local directory.</p>
465
466<p><a name="ApacheFelixOSGiBundleRepository-proxy"></a></p>
467
468<h2><a name="ApacheFelixOSGiBundleRepository-UsingOBRwithaProxy"></a>Using OBR with a Proxy</h2>
469
470<p>If you use a proxy for Web access, then OBR will not work for you in
471its default configuration; certain system properties must be set to
472enable OBR to work with a proxy. These properties are:</p>
473
474<ul>
475 <li>http.proxyHost - the name of the proxy host.</li>
476 <li>http.proxyPort - the port of the proxy host.</li>
477 <li>http.proxyAuth
478- the user name and password to use when connecting to the proxy; this
479string should be the user name and password separated by a colon (e.g.,
480rickhall:mypassword).</li>
481</ul>
482
483
484<p>These system properties can be set directly on the command line when
485starting the JVM using the standard "-D&lt;prop&gt;=&lt;value&gt;"
486syntax or you can put them in the lib/system.properties file of your
487Felix installation; see documentation on configuring Felix for more
488information.</p>
489
490<p><a name="ApacheFelixOSGiBundleRepository-sourcepackaging"></a></p>
491
492<h2><a name="ApacheFelixOSGiBundleRepository-BundleSourcePackaging"></a>Bundle Source Packaging</h2>
493
494<p>Coming soon...</p>
495
496<p><a name="ApacheFelixOSGiBundleRepository-r3note"></a></p>
497
498<h2><a name="ApacheFelixOSGiBundleRepository-NoteonOSGiR3Bundles"></a>Note on OSGi R3 Bundles</h2>
499
500<p>In contrast to OSGi R4 the previous specifications, most notably R3, allowed bundles without the <tt>Bundle-SymbolicName</tt>
501header. The Felix OSGi Bundle Repository implementation heavily relies
502on the symbolic name being defined in bundles. As a consequence bundles
503without a symbolic name are not fully supported by the Bundle
504Repository:</p>
505
506<ul>
507 <li>Bundles installed in the framework are used by the Bundle
508Repository implementation to resolve dependencies regardless of whether
509they have a <tt>Bundle-SymbolicName</tt> header or not. Resolution of dependencies against the installed bundles takes place based on the <tt>Export-Package</tt> headers.</li>
510 <li>Bundles installed in the framework without a <tt>Bundle-SymbolicName</tt>
511header cannot be updated by the Bundle Repository implementation
512because updates from the bundle repository cannot be correlated to such
513"anonymous" bundles.</li>
514</ul>
515
516
517
518<p><a name="ApacheFelixOSGiBundleRepository-feedback"></a></p>
519
520<h2><a name="ApacheFelixOSGiBundleRepository-Feedback"></a>Feedback</h2>
521
522<p>Subscribe to the Felix users mailing list by sending a message to <a href="mailto:users-subscribe@felix.apache.org" rel="nofollow">users-subscribe@felix.apache.org</a>; after subscribing, email questions or feedback to <a href="mailto:users@felix.apache.org" rel="nofollow">users@felix.apache.org</a>.</p>
523 </div>
524 </body></html>