Author: rickhall
Date: Tue Jul 10 08:29:11 2007
New Revision: 554975
URL: http://svn.apache.org/viewvc?view=rev&rev=554975
Log:
Added documentation to the shell and bundlerepository sub-projects in
preparation for release.
Added:
felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr.html
(with props)
felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/
felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/apache-felix-small.png
(with props)
felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/linkext7.gif
(with props)
felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/mail_small.gif
(with props)
felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/obr-entities.png
(with props)
felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/obr-high-level.png
(with props)
felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/print.css
(with props)
felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/site.css
(with props)
felix/trunk/shell/doc/apache-felix-shell-service.html (with props)
felix/trunk/shell/doc/apache-felix-shell-service_files/
felix/trunk/shell/doc/apache-felix-shell-service_files/apache-felix-small.png
(with props)
felix/trunk/shell/doc/apache-felix-shell-service_files/mail_small.gif
(with props)
felix/trunk/shell/doc/apache-felix-shell-service_files/print.css (with
props)
felix/trunk/shell/doc/apache-felix-shell-service_files/site.css (with
props)
Added:
felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr.html
URL:
http://svn.apache.org/viewvc/felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr.html?view=auto&rev=554975
==============================================================================
---
felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr.html
(added)
+++
felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr.html
Tue Jul 10 08:29:11 2007
@@ -0,0 +1,483 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";>
+<html><head><title>Apache Felix</title>
+
+
+
+
+ <link rel="stylesheet"
href="apache-felix-osgi-bundle-repository-obr_files/site.css" type="text/css"
media="all">
+ <link rel="stylesheet"
href="apache-felix-osgi-bundle-repository-obr_files/print.css" type="text/css"
media="print">
+ <meta http-equiv="Content-Type"
content="text/html;charset=UTF-8"></head><body linkifytime="102" linkified="0"
linkifying="false">
+ <div class="title">
+ <img alt="Logo"
src="apache-felix-osgi-bundle-repository-obr_files/apache-felix-small.png"
align="right">
+ </div>
+ <div class="menu">
+ <ul>
+ <li><a href="http://cwiki.apache.org/FELIX/index.html";>home</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/news.html";>news</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/status.html";>status</a></li>
+ <li><a
href="http://cwiki.apache.org/FELIX/license.html";>license</a></li>
+ <li><a
href="http://cwiki.apache.org/FELIX/downloads.html";>downloads</a></li>
+ <li><a
href="http://cwiki.apache.org/FELIX/documentation.html";>documentation</a></li>
+ <li><a
href="http://cwiki.apache.org/FELIX/committers.html";>committers</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/mailinglists.html";>mailing
lists</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/faq.html";>faq</a></li>
+ <li><a
href="http://cwiki.apache.org/FELIX/roadmap.html";>roadmap</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/sourcecode.html";>source
code</a></li>
+ <li><a
href="http://cwiki.apache.org/FELIX/codingstandards.html";>coding
standards</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/issuetracking.html";>issue
tracking</a></li>
+ <li><a
href="http://cwiki.apache.org/FELIX/dependencies.html";>dependencies</a></li>
+ </ul>
+ </div>
+ <div class="main">
+<h1><a
name="ApacheFelixOSGiBundleRepository(OBR)-ApacheFelixOSGiBundleRepository(OBR)"></a>Apache
Felix OSGi Bundle Repository (OBR)</h1>
+
+<ul>
+ <li><a href="#ApacheFelixOSGiBundleRepository%2528OBR%2529-motivation"
title="motivation on Apache Felix OSGi Bundle Repository
(OBR)">Motivation</a></li>
+ <li><a href="#ApacheFelixOSGiBundleRepository%2528OBR%2529-overview"
title="overview on Apache Felix OSGi Bundle Repository (OBR)">Overview</a></li>
+ <li><a
href="#ApacheFelixOSGiBundleRepository%2528OBR%2529-repositoryfile"
title="repository-file on Apache Felix OSGi Bundle Repository (OBR)">OBR
Repository File</a></li>
+ <li><a href="#ApacheFelixOSGiBundleRepository%2528OBR%2529-serviceapi"
title="service-api on Apache Felix OSGi Bundle Repository (OBR)">OBR Service
API</a></li>
+ <li><a
href="#ApacheFelixOSGiBundleRepository%2528OBR%2529-shellcommand"
title="shell-command on Apache Felix OSGi Bundle Repository (OBR)">OBR Shell
Command</a>
+ <ul>
+ <li><a
href="#ApacheFelixOSGiBundleRepository%2528OBR%2529-obrhelp" title="obr-help on
Apache Felix OSGi Bundle Repository (OBR)"><tt>obr help</tt></a></li>
+ <li><a
href="#ApacheFelixOSGiBundleRepository%2528OBR%2529-obrlisturl"
title="obr-list-url on Apache Felix OSGi Bundle Repository (OBR)"><tt>obr
list-url</tt></a></li>
+ <li><a
href="#ApacheFelixOSGiBundleRepository%2528OBR%2529-obraddurl"
title="obr-add-url on Apache Felix OSGi Bundle Repository (OBR)"><tt>obr
add-url</tt></a></li>
+ <li><a
href="#ApacheFelixOSGiBundleRepository%2528OBR%2529-obrremoveurl"
title="obr-remove-url on Apache Felix OSGi Bundle Repository (OBR)"><tt>obr
remove-url</tt></a></li>
+ <li><a
href="#ApacheFelixOSGiBundleRepository%2528OBR%2529-obrlist" title="obr-list on
Apache Felix OSGi Bundle Repository (OBR)"><tt>obr list</tt></a></li>
+ <li><a
href="#ApacheFelixOSGiBundleRepository%2528OBR%2529-obrinfo" title="obr-info on
Apache Felix OSGi Bundle Repository (OBR)"><tt>obr info</tt></a></li>
+ <li><a
href="#ApacheFelixOSGiBundleRepository%2528OBR%2529-obrdeploy"
title="obr-deploy on Apache Felix OSGi Bundle Repository (OBR)"><tt>obr
deploy</tt></a></li>
+ <li><a
href="#ApacheFelixOSGiBundleRepository%2528OBR%2529-obrstart" title="obr-start
on Apache Felix OSGi Bundle Repository (OBR)"><tt>obr start</tt></a></li>
+ <li><a
href="#ApacheFelixOSGiBundleRepository%2528OBR%2529-obrsource"
title="obr-source on Apache Felix OSGi Bundle Repository (OBR)"><tt>obr
source</tt></a></li>
+ </ul>
+ </li>
+ <li><a href="#ApacheFelixOSGiBundleRepository%2528OBR%2529-proxy"
title="proxy on Apache Felix OSGi Bundle Repository (OBR)">Using OBR with a
Proxy</a></li>
+ <li><a
href="#ApacheFelixOSGiBundleRepository%2528OBR%2529-sourcepackaging"
title="source-packaging on Apache Felix OSGi Bundle Repository (OBR)">Bundle
Source Packaging</a></li>
+ <li><a href="#ApacheFelixOSGiBundleRepository%2528OBR%2529-feedback"
title="feedback on Apache Felix OSGi Bundle Repository (OBR)">Feedback</a></li>
+</ul>
+
+
+<p><a name="ApacheFelixOSGiBundleRepository(OBR)-motivation"></a></p>
+
+<h2><a
name="ApacheFelixOSGiBundleRepository(OBR)-Motivation"></a>Motivation</h2>
+
+<p>The goal of the Apache Felix OSGi Bundle Repository (OBR) is two-fold:</p>
+
+<ol>
+ <li>To simplify deploying and using available bundles with Felix.</li>
+ <li>To encourage independent bundle development so that communities of
interest can grow.</li>
+</ol>
+
+
+<p>OBR achieves the first goal by providing a service that can
+automatically install a bundle, with its deployment dependencies, from
+a bundle repository. This makes it easier for people to experiment with
+existing bundles. The second goal is achieved by raising the visibility
+of the available bundles and providing access to both the executable
+bundle and its source code. Hopefully, by making OBR and the bundles
+themselves more visible, community members will be encouraged to
+provide or improve service implementations.</p>
+
+<p>Note: OBR provides access to the Felix' default bundle repository,
+but you can also use it to deploy your own bundles by creating a bundle
+repository 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>
+
+<p><a name="ApacheFelixOSGiBundleRepository(OBR)-overview"></a></p>
+
+<h2><a name="ApacheFelixOSGiBundleRepository(OBR)-Overview"></a>Overview</h2>
+
+<p>For the most part, OBR is quite simple. An OBR "repository server"
+is not necessary, since all functionality may reside on the client
+side. OBR is able to provide its functionality by reading an XML-based
+meta-data file that describes the bundles available to it. The
+meta-data file essentially contains an XML encoding of the bundles'
+manifest information. From the meta-data, OBR is able to construct
+dependency information for deploying (i.e., installing and updating)
+bundles.</p>
+
+<p>OBR defines the following entities:</p>
+
+<ul>
+ <li><em><b>Repository Admin</b></em> - a service to access a federation
of repositories.</li>
+ <li><em><b>Repository</b></em> - provides access to a set of
resources.</li>
+ <li><em><b>Resource</b></em> - a description of an artifact to be
installed on a device.</li>
+ <li><em><b>Capability</b></em> - a named set of properties.</li>
+ <li><em><b>Requirement</b></em> - an assertion on a capability.</li>
+ <li><em><b>Resolver</b></em> - an object to resolve resource
dependencies and to deploy them.</li>
+ <li><em><b>Repository file</b></em> - XML file containing resource
meta-data.</li>
+</ul>
+
+
+<p>The following diagram illustrates the relationships among these
entities:</p>
+
+<p><img src="apache-felix-osgi-bundle-repository-obr_files/obr-entities.png"
align="absmiddle" border="0"></p>
+
+<p>The client has access to a federated set of repositories via the Repository
Admin service; such as depicted in this view:</p>
+
+<p><img src="apache-felix-osgi-bundle-repository-obr_files/obr-high-level.png"
align="absmiddle" border="0"></p>
+
+<p><a name="ApacheFelixOSGiBundleRepository(OBR)-repositoryfile"></a></p>
+
+<h2><a name="ApacheFelixOSGiBundleRepository(OBR)-OBRRepositoryFile"></a>OBR
Repository File</h2>
+
+<p>The OBR repository file is an XML-based representation of bundle
+meta-data. The goal is provide a generic model for describing
+dependencies 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 <span
class="nobr"><a
href="http://www2.osgi.org/download/rfc-0112_BundleRepository.pdf"; title="Visit
page outside Confluence" rel="nofollow">OSGi RFC 112<sup><img
class="rendericon"
src="apache-felix-osgi-bundle-repository-obr_files/linkext7.gif" alt=""
align="absmiddle" border="0" height="7" width="7"></sup></a></span>
+document; this document is not completely in sync with the
+implementation, but the concepts are still correct. The following XML
+snippet depicts the overall structure of a repository file:</p>
+
+<div class="preformatted"><div class="preformattedContent">
+<pre><repository presentationname="..." symbolicname="..." ... >
+ <resource>
+ <description>...</description>
+ <size>...</size>
+ <documentation>...</documentation>
+ <source>...</source>
+ <category id="..."/>
+ <capability>...</capability>
+ ...
+ <requirement>...</requirement>
+ ...
+ </resource>
+ ...
+</repository>
+</pre>
+</div></div>
+
+<p>The above repository defines a set of available resources, each
+described by a set of meta-data. Some resource meta-data is purely
+intended for human consumption; the most important aspects relate to
+the generic capability/requirement model.</p>
+
+<p>A resource can provide any number of capabilities. A capability is a
+typed set of properties. For example, the following is an exported
+package capability:</p>
+
+<div class="preformatted"><div class="preformattedContent">
+<pre><capability name='package'>
+ <p n='package' v='org.foo.bar'/>
+ <p n='version' t='version' v='1.0.0'/>
+</capability>
+</pre>
+</div></div>
+
+<p>This capability is of type 'package' and exports 'org.foo.bar' at
+version '1.0.0'. Conversely, a requirement is a typed LDAP query over a
+set of capability properties. For example, the following is an imported
+package requirement:</p>
+
+<div class="preformatted"><div class="preformattedContent">
+<pre><require name='package' extend='false'
+ multiple='false' optional='false'
+ filter='(&amp;(package=org.foo.bar)(version&gt;=1.0.0))'>
+ Import package org.foo.bar
+</require>
+</pre>
+</div></div>
+
+<p>This requirement is of type 'package' and imports 'org.foo.bar' at
+versions greater than '1.0.0'. Although this syntax looks rather
+complicated with the '\&' and '\>=' syntax, it is simply the
+standard OSGi LDAP query syntax in XML form (additionally, Peter Kriens
+has created a tool called <tt>bindex</tt> to generate this meta-data from a
bundle's manifest).</p>
+
+<p>With this generic dependency model, OBR is able to provide mappings
+for the various OSGi bundle dependencies; e.g., import/export package,
+provide/require bundle, host/fragment, import/export service, execution
+environment, and native code. In addition, it is possible for bundles
+to introduce arbitrary dependencies for custom purposes.</p>
+
+<p>Two other important pieces of meta-data are <tt>Bundle-SymbolicName</tt>
and <tt>Bundle-Version</tt>;
+these are standard OSGi bundle manifest attributes that OBR uses to
+uniquely identify a bundle. For example, if you want to use OBR to
+update a locally installed bundle, OBR gets its symbolic name and
+version and searches the repository metadata for a matching symbolic
+name. If the matching symbolic name is found, then OBR checks if there
+is a newer version than the local copy using the bundle version number.
+Thus, the symbolic name plus bundle version forms a unique key to match
+locally installed bundles to remotely available bundles.</p>
+
+<p><a name="ApacheFelixOSGiBundleRepository(OBR)-serviceapi"></a></p>
+
+<h2><a name="ApacheFelixOSGiBundleRepository(OBR)-OBRServiceAPI"></a>OBR
Service API</h2>
+
+<p>Typically, OBR service clients only need to interact with the
+Repository Admin service, which provides the mechanisms necessary to
+discover available resources. The Repository Admin interface is defined
+as follows:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">public</span> <span
class="code-keyword">interface</span> RepositoryAdmin
+{
+ <span class="code-keyword">public</span> Resource[]
discoverResources(<span class="code-object">String</span> filterExpr);
+ <span class="code-keyword">public</span> Resolver resolver();
+ <span class="code-keyword">public</span> Repository addRepository(URL
repository)‏
+ <span class="code-keyword">throws</span> Exception;
+ <span class="code-keyword">public</span> <span
class="code-object">boolean</span> removeRepository(URL repository);
+ <span class="code-keyword">public</span> Repository[] listRepositories();
+ <span class="code-keyword">public</span> Resource getResource(<span
class="code-object">String</span> respositoryId);
+}</pre>
+</div></div>
+
+<p>In order to resolve and deploy available resources, the Repository
+Admin provides Resolver instances, which are defined as follows:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">public</span> <span
class="code-keyword">interface</span> Resolver
+{
+ <span class="code-keyword">public</span> void add(Resource resource);
+ <span class="code-keyword">public</span> Requirement[]
getUnsatisfiedRequirements();
+ <span class="code-keyword">public</span> Resource[] getOptionalResources();
+ <span class="code-keyword">public</span> Requirement[] getReason(Resource
resource);
+ <span class="code-keyword">public</span> Resource[]
getResources(Requirement requirement);
+ <span class="code-keyword">public</span> Resource[] getRequiredResources();
+ <span class="code-keyword">public</span> Resource[] getAddedResources();
+ <span class="code-keyword">public</span> <span
class="code-object">boolean</span> resolve();
+ <span class="code-keyword">public</span> void deploy(<span
class="code-object">boolean</span> start);
+}</pre>
+</div></div>
+
+<p>When desired resources are discovered via the query mechanisms of
+the Repository Admin, they are added to a Resolver instance which will
+can be used to resolve all transitive dependencies and to reflect on
+any resolution result. The following code snippet depicts a typical
+usage scenario:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">RepositoryAdmin repoAdmin = ... <span
class="code-comment">// Get repo admin service
+</span>Resolver resolver = repoAdmin.resolver();
+Resource resource = repoAdmin.discoverResources(filterStr);
+resolver.add(resource);
+<span class="code-keyword">if</span> (resolver.resolve())
+{
+ resolver.deploy();
+}
+<span class="code-keyword">else</span>
+{
+ Requirement[] reqs = resolver.getUnsatisfiedRequirements();
+ <span class="code-keyword">for</span> (<span
class="code-object">int</span> i = 0; i < reqs.length; i++)
+ {
+ <span class="code-object">System</span>.out.println(<span
class="code-quote">"Unable to resolve: "</span> + reqs[i]);
+ }
+}</pre>
+</div></div>
+
+<p>This code gets the Repository Admin service and then gets a Resolver
+instance from it. It then discovers an available resource and adds it
+to the resolver. Then it tries to resolve the resources dependencies.
+If successful it deploys the resource to the local framework instance;
+if not successful it prints the unsatisfied requirements.</p>
+
+<p>OBR's deployment algorithm appears simple at first glance, but it is
+actually somewhat complex due to the nature of deploying independently
+developed bundles. For example, in an ideal world, if an update for a
+bundle is made available, then updates for all of the bundles
+satisfying its dependencies are also made available. Unfortunately,
+this may not be the case, thus the deployment algorithm might have to
+install new bundles during an update to satisfy either new dependencies
+or updated dependencies that can no longer be satisfied by existing
+local bundles. In response to this type of scenario, the OBR deployment
+algorithm tries to favor updating existing bundles, if possible, as
+opposed to installing new bundles to satisfy dependencies.</p>
+
+<p>In the general case, OBR user's will not use the OBR API directly,
+but will use its functionality indirectly from another tool or user
+interface. For example, interactive access to OBR is available via a
+command for Felix' <a
href="http://cwiki.apache.org/FELIX/apache-felix-shell-service.html";
title="Apache Felix Shell Service">shell service</a>. The OBR shell command is
discussed in the next section.</p>
+
+<p><a name="ApacheFelixOSGiBundleRepository(OBR)-shellcommand"></a></p>
+
+<h2><a name="ApacheFelixOSGiBundleRepository(OBR)-OBRShellCommand"></a>OBR
Shell Command</h2>
+
+<p>Besides providing a service API, OBR implements a Felix shell
+command for accessing its functionality. For the end user, the OBR
+shell command is accessed using the text-based or GUI-based user
+interfaces for Felix' shell service. This section describes the syntax
+for the OBR shell command.</p>
+
+<p><a name="ApacheFelixOSGiBundleRepository(OBR)-obrhelp"></a></p>
+
+<h3><a name="ApacheFelixOSGiBundleRepository(OBR)-{{obrhelp}}"></a><tt>obr
help</tt></h3>
+
+<p>Syntax:</p>
+<div class="preformatted"><div class="preformattedContent">
+<pre>obr help [urls | list | info | install | deploy | start | update | source]
+</pre>
+</div></div>
+<p>This command is used to display additional information about the other OBR
commands.</p>
+
+<p><a name="ApacheFelixOSGiBundleRepository(OBR)-obrlisturl"></a></p>
+
+<h3><a name="ApacheFelixOSGiBundleRepository(OBR)-{{obrlisturl}}"></a><tt>obr
list-url</tt></h3>
+
+<p>Syntax:</p>
+<div class="preformatted"><div class="preformattedContent">
+<pre>obr list-url
+</pre>
+</div></div>
+<p>This command gets the URLs to the repository files used by the Repository
Admin.</p>
+
+<p><a name="ApacheFelixOSGiBundleRepository(OBR)-obraddurl"></a></p>
+
+<h3><a name="ApacheFelixOSGiBundleRepository(OBR)-{{obraddurl}}"></a><tt>obr
add-url</tt></h3>
+
+<p>Syntax:</p>
+<div class="preformatted"><div class="preformattedContent">
+<pre>obr add-url [<repository-file-url> ...]
+</pre>
+</div></div>
+<p>This command adds a repository file to the set of repository files
+for which the Repository Admin service provides access. The repository
+file is represented as a URL. If the repository file URL is already in
+the Repository Admin's set of repository files, the request is treated
+like a reload operation.</p>
+
+<p><a name="ApacheFelixOSGiBundleRepository(OBR)-obrremoveurl"></a></p>
+
+<h3><a
name="ApacheFelixOSGiBundleRepository(OBR)-{{obrremoveurl}}"></a><tt>obr
remove-url</tt></h3>
+
+<p>Syntax:</p>
+<div class="preformatted"><div class="preformattedContent">
+<pre>obr remove-url [<repository-file-url> ...]
+</pre>
+</div></div>
+<p>This command removes a repository file to the set of repository
+files for which the Repository Admin service provides access. The
+repository file is represented as a URL.</p>
+
+<p><a name="ApacheFelixOSGiBundleRepository(OBR)-obrlist"></a></p>
+
+<h3><a name="ApacheFelixOSGiBundleRepository(OBR)-{{obrlist}}"></a><tt>obr
list</tt></h3>
+
+<p>Syntax:</p>
+<div class="preformatted"><div class="preformattedContent">
+<pre>obr list [<string> ...]
+</pre>
+</div></div>
+<p>This command lists bundles available in the bundle repository. If no
+arguments are specified, then all available bundles are listed,
+otherwise any arguments are concatenated with spaces and used as a
+substring filter on the bundle names.</p>
+
+<p><a name="ApacheFelixOSGiBundleRepository(OBR)-obrinfo"></a></p>
+
+<h3><a name="ApacheFelixOSGiBundleRepository(OBR)-{{obrinfo}}"></a><tt>obr
info</tt></h3>
+
+<p>Syntax:</p>
+<div class="preformatted"><div class="preformattedContent">
+<pre>obr info <bundle-name>[;<version>] ...
+</pre>
+</div></div>
+<p>This command displays the meta-data for the specified bundles. If a
+bundle's name contains spaces, then it must be surrounded by quotes. It
+is also possible to specify a precise version if more than one version
+exists, such as:</p>
+<div class="preformatted"><div class="preformattedContent">
+<pre>obr info "Bundle Repository";1.0.0
+</pre>
+</div></div>
+<p>The above example retrieves the meta-data for version "1.0.0" of the bundle
named "Bundle Repository".</p>
+
+<p><a name="ApacheFelixOSGiBundleRepository(OBR)-obrdeploy"></a></p>
+
+<h3><a name="ApacheFelixOSGiBundleRepository(OBR)-{{obrdeploy}}"></a><tt>obr
deploy</tt></h3>
+
+<p>Syntax:</p>
+<div class="preformatted"><div class="preformattedContent">
+<pre>obr deploy [-nodeps] <bundle-name>[;<version>] ... |
<bundle-id> ...
+</pre>
+</div></div>
+<p>This command tries to install or update the specified bundles and
+all of their dependencies by default; use the "-nodeps" switch to
+ignore dependencies. You can specify either the bundle name or the
+bundle identifier. If a bundle's name contains spaces, then it must be
+surrounded by quotes. It is also possible to specify a precise version
+if more than one version exists, such as:</p>
+<div class="preformatted"><div class="preformattedContent">
+<pre>obr deploy "Bundle Repository";1.0.0
+</pre>
+</div></div>
+<p>For the above example, if version "1.0.0" of "Bundle Repository" is
+already installed locally, then the command will attempt to update it
+and all of its dependencies; otherwise, the command will install it and
+all of its dependencies.</p>
+
+<p><a name="ApacheFelixOSGiBundleRepository(OBR)-obrstart"></a></p>
+
+<h3><a name="ApacheFelixOSGiBundleRepository(OBR)-{{obrstart}}"></a><tt>obr
start</tt></h3>
+
+<p>Syntax:</p>
+<div class="preformatted"><div class="preformattedContent">
+<pre>obr start [-nodeps] <bundle-name>[;<version>] ...
+</pre>
+</div></div>
+<p>This command installs and starts the specified bundles and all of
+their dependencies by default; use the "-nodeps" switch to ignore
+dependencies. If a bundle's name contains spaces, then it must be
+surrounded by quotes. If a specified bundle is already installed, then
+this command has no effect. It is also possible to specify a precise
+version if more than one version exists, such as:</p>
+<div class="preformatted"><div class="preformattedContent">
+<pre>obr start "Bundle Repository";1.0.0
+</pre>
+</div></div>
+<p>The above example installs and starts the "1.0.0" version of the bundle
named "Bundle Repository" and its dependencies.</p>
+
+<p><a name="ApacheFelixOSGiBundleRepository(OBR)-obrsource"></a></p>
+
+<h3><a name="ApacheFelixOSGiBundleRepository(OBR)-{{obrsource}}"></a><tt>obr
source</tt></h3>
+
+<p>Syntax:</p>
+<div class="preformatted"><div class="preformattedContent">
+<pre>obr source [-x] <local-dir> <bundle-name>[;<version>]
...
+</pre>
+</div></div>
+<p>This command retrieves the source archives of the specified bundles
+and saves them to the specified local directory; use the "-x" switch to
+automatically extract the source archives. If a bundle name contains
+spaces, then it must be surrounded by quotes. It is also possible to
+specify a precise version if more than one version exists, such as:</p>
+<div class="preformatted"><div class="preformattedContent">
+<pre>obr source /home/rickhall/tmp "Bundle Repository";1.0.0
+</pre>
+</div></div>
+<p>The above example retrieves the source archive of version "1.0.0" of
+the bundle named "Bundle Repository" and saves it to the specified
+local directory.</p>
+
+<p><a name="ApacheFelixOSGiBundleRepository(OBR)-proxy"></a></p>
+
+<h2><a
name="ApacheFelixOSGiBundleRepository(OBR)-UsingOBRwithaProxy"></a>Using OBR
with a Proxy</h2>
+
+<p>If you use a proxy for Web access, then OBR will not work for you in
+its default configuration; certain system properties must be set to
+enable OBR to work with a proxy. These properties are:</p>
+
+<ul>
+ <li>http.proxyHost - the name of the proxy host.</li>
+ <li>http.proxyPort - the port of the proxy host.</li>
+ <li>http.proxyAuth
+- the user name and password to use when connecting to the proxy; this
+string should be the user name and password separated by a colon (e.g.,
+rickhall:mypassword).</li>
+</ul>
+
+
+<p>These system properties can be set directly on the command line when
+starting the JVM using the standard "-D<prop>=<value>"
+syntax or you can put them in the lib/system.properties file of your
+Felix installation; see documentation on configuring Felix for more
+information.</p>
+
+<p><a name="ApacheFelixOSGiBundleRepository(OBR)-sourcepackaging"></a></p>
+
+<h2><a
name="ApacheFelixOSGiBundleRepository(OBR)-BundleSourcePackaging"></a>Bundle
Source Packaging</h2>
+
+<p>Coming soon...</p>
+
+<p><a name="ApacheFelixOSGiBundleRepository(OBR)-feedback"></a></p>
+
+<h2><a name="ApacheFelixOSGiBundleRepository(OBR)-Feedback"></a>Feedback</h2>
+
+<p>Subscribe to the Felix users mailing list by sending a message to <span
class="nobr"><a href="mailto:[EMAIL PROTECTED]" title="Send mail to [EMAIL
PROTECTED]" rel="nofollow">[EMAIL PROTECTED]<sup><img class="rendericon"
src="apache-felix-osgi-bundle-repository-obr_files/mail_small.gif" alt=""
align="absmiddle" border="0" height="12" width="13"></sup></a></span>; after
subscribing, email questions or feedback to <span class="nobr"><a
href="mailto:[EMAIL PROTECTED]" title="Send mail to [EMAIL PROTECTED]"
rel="nofollow">[EMAIL PROTECTED]<sup><img class="rendericon"
src="apache-felix-osgi-bundle-repository-obr_files/mail_small.gif" alt=""
align="absmiddle" border="0" height="12" width="13"></sup></a></span>.</p>
+ </div>
+ </body></html>
\ No newline at end of file
Propchange:
felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr.html
------------------------------------------------------------------------------
svn:eol-style = native
Added:
felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/apache-felix-small.png
URL:
http://svn.apache.org/viewvc/felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/apache-felix-small.png?view=auto&rev=554975
==============================================================================
Binary file - no diff available.
Propchange:
felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/apache-felix-small.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added:
felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/linkext7.gif
URL:
http://svn.apache.org/viewvc/felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/linkext7.gif?view=auto&rev=554975
==============================================================================
Binary file - no diff available.
Propchange:
felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/linkext7.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added:
felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/mail_small.gif
URL:
http://svn.apache.org/viewvc/felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/mail_small.gif?view=auto&rev=554975
==============================================================================
Binary file - no diff available.
Propchange:
felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/mail_small.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added:
felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/obr-entities.png
URL:
http://svn.apache.org/viewvc/felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/obr-entities.png?view=auto&rev=554975
==============================================================================
Binary file - no diff available.
Propchange:
felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/obr-entities.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added:
felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/obr-high-level.png
URL:
http://svn.apache.org/viewvc/felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/obr-high-level.png?view=auto&rev=554975
==============================================================================
Binary file - no diff available.
Propchange:
felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/obr-high-level.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added:
felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/print.css
URL:
http://svn.apache.org/viewvc/felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/print.css?view=auto&rev=554975
==============================================================================
---
felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/print.css
(added)
+++
felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/print.css
Tue Jul 10 08:29:11 2007
@@ -0,0 +1,9 @@
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
+<html><head>
+<title>404 Not Found</title>
+</head><body>
+<h1>Not Found</h1>
+<p>The requested URL /FELIX/media.data/print.css was not found on this
server.</p>
+<hr>
+<address>Apache/2.2.3 (Unix) mod_ssl/2.2.3 OpenSSL/0.9.7g Server at
cwiki.apache.org Port 80</address>
+</body></html>
Propchange:
felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/print.css
------------------------------------------------------------------------------
svn:eol-style = native
Added:
felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/site.css
URL:
http://svn.apache.org/viewvc/felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/site.css?view=auto&rev=554975
==============================================================================
---
felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/site.css
(added)
+++
felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/site.css
Tue Jul 10 08:29:11 2007
@@ -0,0 +1,19 @@
+body { background-color: #ffffff; color: #000000; font-family: Arial,
sans-serif; }
+h1 { font-size: 130% }
+h2 { font-size: 125% }
+h3 { font-size: 120% }
+h4 { font-size: 115% }
+h5 { font-size: 110% }
+h6 { font-size: 105% }
+a { color: #880000 }
+a:visited { color: #880000 }
+a:hover { color: #cc4444 }
+.title { position: absolute; left: 1em; right: 1em; top: 10px; height: 52px; }
+.menu { position: absolute; top: 80px; left: 0.5em; width: 8em; border: solid
1px black; padding-left: 0.5em; padding-right: 0.5em }
+.menu ul { list-style: none; padding-left: 0pt}
+.main { position: absolute; top: 65px; left: 10.5em; right: 1em; }
+.code { background-color: #eeeeee; border: solid 1px black; padding: 0.5em; }
+.code-keyword { color: #880000; }
+.code-quote { color: #008800; }
+.code-object { color: #0000dd; }
+.code-java { margin: 0em; }
\ No newline at end of file
Propchange:
felix/trunk/bundlerepository/doc/apache-felix-osgi-bundle-repository-obr_files/site.css
------------------------------------------------------------------------------
svn:eol-style = native
Added: felix/trunk/shell/doc/apache-felix-shell-service.html
URL:
http://svn.apache.org/viewvc/felix/trunk/shell/doc/apache-felix-shell-service.html?view=auto&rev=554975
==============================================================================
--- felix/trunk/shell/doc/apache-felix-shell-service.html (added)
+++ felix/trunk/shell/doc/apache-felix-shell-service.html Tue Jul 10 08:29:11
2007
@@ -0,0 +1,345 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";>
+<html><head><title>Apache Felix</title>
+
+
+
+
+ <link rel="stylesheet" href="apache-felix-shell-service_files/site.css"
type="text/css" media="all">
+ <link rel="stylesheet" href="apache-felix-shell-service_files/print.css"
type="text/css" media="print">
+ <meta http-equiv="Content-Type"
content="text/html;charset=UTF-8"></head><body linkifytime="77" linkified="1"
linkifying="false">
+ <div class="title">
+ <img alt="Logo"
src="apache-felix-shell-service_files/apache-felix-small.png" align="right">
+ </div>
+ <div class="menu">
+ <ul>
+ <li><a href="http://cwiki.apache.org/FELIX/index.html";>home</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/news.html";>news</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/status.html";>status</a></li>
+ <li><a
href="http://cwiki.apache.org/FELIX/license.html";>license</a></li>
+ <li><a
href="http://cwiki.apache.org/FELIX/downloads.html";>downloads</a></li>
+ <li><a
href="http://cwiki.apache.org/FELIX/documentation.html";>documentation</a></li>
+ <li><a
href="http://cwiki.apache.org/FELIX/committers.html";>committers</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/mailinglists.html";>mailing
lists</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/faq.html";>faq</a></li>
+ <li><a
href="http://cwiki.apache.org/FELIX/roadmap.html";>roadmap</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/sourcecode.html";>source
code</a></li>
+ <li><a
href="http://cwiki.apache.org/FELIX/codingstandards.html";>coding
standards</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/issuetracking.html";>issue
tracking</a></li>
+ <li><a
href="http://cwiki.apache.org/FELIX/dependencies.html";>dependencies</a></li>
+ </ul>
+ </div>
+ <div class="main">
+<h1><a name="ApacheFelixShellService-ApacheFelixShellService"></a>Apache Felix
Shell Service</h1>
+
+<ul>
+ <li><a href="#ApacheFelixShellService-overview" title="overview on
Apache Felix Shell Service">Overview</a></li>
+ <li><a href="#ApacheFelixShellService-service" title="service on Apache
Felix Shell Service">How the Shell Service Works</a></li>
+ <li><a href="#ApacheFelixShellService-commands" title="commands on
Apache Felix Shell Service">How Commands Work</a></li>
+ <li><a href="#ApacheFelixShellService-creating" title="creating on
Apache Felix Shell Service">Creating a Command</a></li>
+ <li><a href="#ApacheFelixShellService-security" title="security on
Apache Felix Shell Service">Security and the Shell Service</a></li>
+ <li><a href="#ApacheFelixShellService-feedback" title="feedback on
Apache Felix Shell Service">Feedback</a></li>
+</ul>
+
+
+<p><a name="ApacheFelixShellService-overview"></a></p>
+
+<h2><a name="ApacheFelixShellService-Overview"></a>Overview</h2>
+
+<p>In order to interact with Felix it is necessary to have some sort of
+interactive shell that allows you to issue commands to the framework
+and to obtain information from it. The OSGi specification does not
+define how an OSGi framework should provide this interactivity. Felix
+defines a shell service for creating and executing arbitrary commands.
+The shell service does not define a user interface, only a service API.</p>
+
+<p>The benefit of the Felix shell service approach is that it is possible
to:</p>
+
+<ul>
+ <li>have multiple shell user interfaces (e.g., textual and
graphical),</li>
+ <li>add custom commands to the shell (i.e., bundles can make commands
available via the shell service), and</li>
+ <li>use the shell service from other bundles/services.</li>
+</ul>
+
+
+<p>The remainder of this document describes how the shell service works
+and how to create custom commands for it. This document does not
+describe how to use the command shell, nor does it describe the
+text-based or GUI-based user interfaces that are available for the
+shell.</p>
+
+<p><a name="ApacheFelixShellService-service"></a></p>
+
+<h2><a name="ApacheFelixShellService-HowtheShellServiceWorks"></a>How the
Shell Service Works</h2>
+
+<p>The Felix shell service is intended to be a simple, but extensible
+shell service that can have multiple user interface implementations,
+all of which are independent from the Felix framework. The shell
+service is currently not intended to be sophisticated, rather it is
+just a mechanism to execute commands. The shell service maintains a
+list of command services, each of which have a unique command name. The
+shell service is defined by the following service interface:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">package</span>
org.apache.felix.shell;
+
+<span class="code-keyword">public</span> <span
class="code-keyword">interface</span> ShellService
+{
+ <span class="code-keyword">public</span> <span
class="code-object">String</span>[] getCommands();
+ <span class="code-keyword">public</span> <span
class="code-object">String</span> getCommandUsage(<span
class="code-object">String</span> name);
+ <span class="code-keyword">public</span> <span
class="code-object">String</span> getCommandDescription(<span
class="code-object">String</span> name);
+ <span class="code-keyword">public</span> ServiceReference
getCommandReference(<span class="code-object">String</span> name);
+ <span class="code-keyword">public</span> void executeCommand(
+ <span class="code-object">String</span> commandLine, PrintStream out,
PrintStream err)
+ <span class="code-keyword">throws</span> Exception;
+}</pre>
+</div></div>
+
+<p>Using the shell service interface, it is possible to access and
+execute available commands. The shell service methods perform the
+following functions:</p>
+
+<ul>
+ <li><tt>getCommands()</tt> - returns an array of strings that
correspond to the names of the installed shell commands.</li>
+ <li><tt>getCommandUsage()</tt> - returns the command usage string for a
particular command name</li>
+ <li><tt>getCommandDescription()</tt> - returns a short description for
a particular command name.</li>
+ <li><tt>getCommandReference()</tt> - returns the service reference for
a particular command name.</li>
+ <li><tt>executeCommand()</tt> - executes a particular command using the
specified command line and print streams.</li>
+</ul>
+
+
+<p>Most of the shell service methods require no explanation except for
+the executeCommand() method. Even though this method is the most
+complex, it is still fairly simplistic. The assumption of the shell
+service is that a command line will be typed by the user (or perhaps
+constructed by a GUI) and passed into it for execution. The shell
+service interprets the command line in a very simplistic fashion; it
+takes the leading string of characters terminated by a space character
+(not including it) and assumes that this leading token is the command
+name. Consider the following command line:</p>
+
+<div class="preformatted"><div class="preformattedContent">
+<pre>update 3 <a style="color: rgb(0, 102, 32); background-color: rgb(255,
249, 171);" class="linkification-ext" href="http://www.foo.com/bar.jar";
title="Linkification: http://www.foo.com/bar.jar";>http://www.foo.com/bar.jar</a>
+</pre>
+</div></div>
+
+<p>The shell service interprets this as an <tt>update</tt> command and
+will search for a command service with the same name. If a
+corresponding command service is not found, then it will print an error
+message to the error print stream. If a corresponding command service
+is found, then it will pass the entire command line string and the
+print streams into the <tt>executeCommand()</tt> method of the command service
(for a more detailed description of command services, see the next section).</p>
+
+<p>Notice that there is no method to add commands to the shell service
+interface. This is because commands are implemented as OSGi services
+and the shell service listens for service events and when a command
+service registers/unregisters it automatically updates its list of
+commands accordingly.</p>
+
+<p><a name="ApacheFelixShellService-commands"></a></p>
+
+<h2><a name="ApacheFelixShellService-HowCommandsWork"></a>How Commands
Work</h2>
+
+<p>All commands available in the shell service are implemented as OSGi
+services. The advantage of this approach is two-fold: the shell service
+can leverage OSGi service events to maintain its list of available
+commands and the set available commands is dynamically extendable by
+installed bundles. The command service interface is defined as follows:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">package</span>
org.ungoverned.osgi.service.shell;
+
+<span class="code-keyword">public</span> <span
class="code-keyword">interface</span> Command
+{
+ <span class="code-keyword">public</span> <span
class="code-object">String</span> getName();
+ <span class="code-keyword">public</span> <span
class="code-object">String</span> getUsage();
+ <span class="code-keyword">public</span> <span
class="code-object">String</span> getShortDescription();
+ <span class="code-keyword">public</span> void execute(<span
class="code-object">String</span> line, PrintStream out, PrintStream err);
+}</pre>
+</div></div>
+
+<p>The semantics of the command service methods are:</p>
+
+<ul>
+ <li><tt>getName()</tt> - returns the name of the command; this must not
contain whitespace and must be unique.</li>
+ <li><tt>getUsage()</tt>
+- returns the usage string of the command; this should be one line and
+as short as possible (this is used for generating the help command
+output).</li>
+ <li><tt>getShortDescription()</tt> - returns a short
+description of the command; this should be one line and as short as
+possible (this is used for generating the help command output).</li>
+ <li><tt>execute()</tt> - executes the command's functionality using
supplied command line and print streams.</li>
+</ul>
+
+
+<p><a name="ApacheFelixShellService-creating"></a></p>
+
+<h2><a name="ApacheFelixShellService-CreatingaCommand"></a>Creating a
Command</h2>
+
+<p>The following example creates a simple version of the <tt>start</tt>
command.</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">package</span> test;
+
+<span class="code-keyword">import</span> java.io.PrintStream;
+<span class="code-keyword">import</span> java.net.URL;
+<span class="code-keyword">import</span> java.net.MalformedURLException;
+<span class="code-keyword">import</span> java.util.StringTokenizer;
+
+<span class="code-keyword">import</span> org.osgi.framework.*;
+<span class="code-keyword">import</span> org.apache.felix.shell.ShellService;
+<span class="code-keyword">import</span> org.apache.felix.shell.Command;
+
+<span class="code-keyword">public</span> class MyStartCommandImpl <span
class="code-keyword">implements</span> Command
+{
+ <span class="code-keyword">private</span> BundleContext m_context = <span
class="code-keyword">null</span>;
+
+ <span class="code-keyword">public</span> MyStartCommandImpl(BundleContext
context)
+ {
+ m_context = context;
+ }
+
+ <span class="code-keyword">public</span> <span
class="code-object">String</span> getName()
+ {
+ <span class="code-keyword">return</span> <span
class="code-quote">"mystart"</span>;
+ }
+
+ <span class="code-keyword">public</span> <span
class="code-object">String</span> getUsage()
+ {
+ <span class="code-keyword">return</span> <span
class="code-quote">"mystart <id> [<id> ...]"</span>;
+ }
+
+ <span class="code-keyword">public</span> <span
class="code-object">String</span> getShortDescription()
+ {
+ <span class="code-keyword">return</span> <span
class="code-quote">"start bundle(s)."</span>;
+ }
+
+ <span class="code-keyword">public</span> void execute(<span
class="code-object">String</span> s, PrintStream out, PrintStream err)
+ {
+ StringTokenizer st = <span class="code-keyword">new</span>
StringTokenizer(s, <span class="code-quote">" "</span>);
+
+ <span class="code-comment">// Ignore the command name.
+</span> st.nextToken();
+
+ <span class="code-comment">// There should be at least one bundle id.
+</span> <span class="code-keyword">if</span> (st.countTokens() >= 1)
+ {
+ <span class="code-keyword">while</span> (st.hasMoreTokens())
+ {
+ <span class="code-object">String</span> id =
st.nextToken().trim();
+
+ <span class="code-keyword">try</span> {
+ <span class="code-object">long</span> l = <span
class="code-object">Long</span>.valueOf(id).longValue();
+ Bundle bundle = m_context.getBundle(l);
+ <span class="code-keyword">if</span> (bundle != <span
class="code-keyword">null</span>)
+ {
+ bundle.start();
+ }
+ <span class="code-keyword">else</span>
+ {
+ err.println(<span class="code-quote">"Bundle ID
"</span> + id + <span class="code-quote">" is invalid."</span>);
+ }
+ } <span class="code-keyword">catch</span>
(NumberFormatException ex) {
+ err.println(<span class="code-quote">"Unable to parse id
'"</span> + id + <span class="code-quote">"'."</span>);
+ } <span class="code-keyword">catch</span> (BundleException ex)
{
+ <span class="code-keyword">if</span>
(ex.getNestedException() != <span class="code-keyword">null</span>)
+ err.println(ex.getNestedException().toString());
+ <span class="code-keyword">else</span>
+ err.println(ex.toString());
+ } <span class="code-keyword">catch</span> (Exception ex) {
+ err.println(ex.toString());
+ }
+ }
+ }
+ <span class="code-keyword">else</span>
+ {
+ err.println(<span class="code-quote">"Incorrect number of
arguments"</span>);
+ }
+ }
+}</pre>
+</div></div>
+
+<p>A bundle activator class is needed for packaging the command servce; the
bundle activator registers the command service in its <tt>start()</tt> method.
Note: You do not need one activator per command, a single activator can
register any number of commands.</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java"><span class="code-keyword">package</span> test;
+
+<span class="code-keyword">import</span> org.osgi.framework.BundleActivator;
+<span class="code-keyword">import</span> org.osgi.framework.BundleContext;
+
+<span class="code-keyword">public</span> class MyStartActivator <span
class="code-keyword">implements</span> BundleActivator
+{
+ <span class="code-keyword">private</span> <span
class="code-keyword">transient</span> BundleContext m_context = <span
class="code-keyword">null</span>;
+
+ <span class="code-keyword">public</span> void start(BundleContext context)
+ {
+ m_context = context;
+
+ <span class="code-comment">// Register the command service.
+</span> context.registerService(
+ org.apache.felix.shell.Command.class.getName(),
+ <span class="code-keyword">new</span>
MyStartCommandImpl(m_context), <span class="code-keyword">null</span>);
+ }
+
+ <span class="code-keyword">public</span> void stop(BundleContext context)
+ {
+ <span class="code-comment">// Services are automatically unregistered
so
+</span> <span class="code-comment">// we don't have to unregister the
factory here.
+</span> }
+}</pre>
+</div></div>
+
+<p>To compile these classes you will need to have the <tt>framework.jar</tt>
file on your class path. Compile all of the source files using a command
like:</p>
+
+<div class="preformatted"><div class="preformattedContent">
+<pre>java -d c:\classes *.java
+</pre>
+</div></div>
+
+<p>This command compiles all of the source files and outputs the generated
class files into a subdirectory of the <tt>c:\classes</tt> directory, called
test, named after the package of the source files; for the above command to
work, the <tt>c:\classes</tt>
+directory must exist. Once you have compiled all of the above classes,
+you need to create a bundle JAR file of the generated package
+directory. The bundle JAR file needs a manifest, so create a file
+called <tt>manifest.mf</tt> with the following contents:</p>
+
+<div class="code"><div class="codeContent">
+<pre class="code-java">Bundle-Name: My Start Command
+Bundle-Description: A 'start' command <span class="code-keyword">for</span>
the shell service.
+Bundle-Activator: test.MyStartActivator
+Bundle-ClassPath: .
+Import-Package: org.apache.felix.shell</pre>
+</div></div>
+
+<p>To create the bundle JAR file, issue the command:</p>
+
+<div class="preformatted"><div class="preformattedContent">
+<pre>jar cfm mystart.jar manifest.mf -C c:\classes test
+</pre>
+</div></div>
+
+<p>This command creates a JAR file using the manifest you created and
+includes all of the classes in the test directory inside of the
<tt>c:\classes</tt>
+directory. Once the bundle JAR file is created, you are ready to add
+the command service to the shell service; simply start Felix and
+install and start the bundle created by the above command. By doing so,
+the new <tt>mystart</tt> command is made available via the shell service.</p>
+
+<p><a name="ApacheFelixShellService-security"></a></p>
+
+<h2><a name="ApacheFelixShellService-SecurityandtheShellService"></a>Security
and the Shell Service</h2>
+
+<p>The shell service security handling is quite simple, all security is
+handled by the standard OSGi framework mechanisms. For example, if a
+bundle should not be able to register a shell service, then it should
+not be given the corresponding service permission. Security handling
+may change in future release after some experience is gained through
+usage.</p>
+
+<p><a name="ApacheFelixShellService-feedback"></a></p>
+
+<h2><a name="ApacheFelixShellService-Feedback"></a>Feedback</h2>
+
+<p>Subscribe to the Felix users mailing list by sending a message to <span
class="nobr"><a href="mailto:[EMAIL PROTECTED]" title="Send mail to [EMAIL
PROTECTED]" rel="nofollow">[EMAIL PROTECTED]<sup><img class="rendericon"
src="apache-felix-shell-service_files/mail_small.gif" alt="" align="absmiddle"
border="0" height="12" width="13"></sup></a></span>; after subscribing, email
questions or feedback to <span class="nobr"><a href="mailto:[EMAIL PROTECTED]"
title="Send mail to [EMAIL PROTECTED]" rel="nofollow">[EMAIL
PROTECTED]<sup><img class="rendericon"
src="apache-felix-shell-service_files/mail_small.gif" alt="" align="absmiddle"
border="0" height="12" width="13"></sup></a></span>.</p>
+ </div>
+
+</body></html>
\ No newline at end of file
Propchange: felix/trunk/shell/doc/apache-felix-shell-service.html
------------------------------------------------------------------------------
svn:eol-style = native
Added:
felix/trunk/shell/doc/apache-felix-shell-service_files/apache-felix-small.png
URL:
http://svn.apache.org/viewvc/felix/trunk/shell/doc/apache-felix-shell-service_files/apache-felix-small.png?view=auto&rev=554975
==============================================================================
Binary file - no diff available.
Propchange:
felix/trunk/shell/doc/apache-felix-shell-service_files/apache-felix-small.png
------------------------------------------------------------------------------
svn:mime-type = image/png
Added: felix/trunk/shell/doc/apache-felix-shell-service_files/mail_small.gif
URL:
http://svn.apache.org/viewvc/felix/trunk/shell/doc/apache-felix-shell-service_files/mail_small.gif?view=auto&rev=554975
==============================================================================
Binary file - no diff available.
Propchange:
felix/trunk/shell/doc/apache-felix-shell-service_files/mail_small.gif
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: felix/trunk/shell/doc/apache-felix-shell-service_files/print.css
URL:
http://svn.apache.org/viewvc/felix/trunk/shell/doc/apache-felix-shell-service_files/print.css?view=auto&rev=554975
==============================================================================
--- felix/trunk/shell/doc/apache-felix-shell-service_files/print.css (added)
+++ felix/trunk/shell/doc/apache-felix-shell-service_files/print.css Tue Jul 10
08:29:11 2007
@@ -0,0 +1,9 @@
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
+<html><head>
+<title>404 Not Found</title>
+</head><body>
+<h1>Not Found</h1>
+<p>The requested URL /FELIX/media.data/print.css was not found on this
server.</p>
+<hr>
+<address>Apache/2.2.3 (Unix) mod_ssl/2.2.3 OpenSSL/0.9.7g Server at
cwiki.apache.org Port 80</address>
+</body></html>
Propchange: felix/trunk/shell/doc/apache-felix-shell-service_files/print.css
------------------------------------------------------------------------------
svn:eol-style = native
Added: felix/trunk/shell/doc/apache-felix-shell-service_files/site.css
URL:
http://svn.apache.org/viewvc/felix/trunk/shell/doc/apache-felix-shell-service_files/site.css?view=auto&rev=554975
==============================================================================
--- felix/trunk/shell/doc/apache-felix-shell-service_files/site.css (added)
+++ felix/trunk/shell/doc/apache-felix-shell-service_files/site.css Tue Jul 10
08:29:11 2007
@@ -0,0 +1,19 @@
+body { background-color: #ffffff; color: #000000; font-family: Arial,
sans-serif; }
+h1 { font-size: 130% }
+h2 { font-size: 125% }
+h3 { font-size: 120% }
+h4 { font-size: 115% }
+h5 { font-size: 110% }
+h6 { font-size: 105% }
+a { color: #880000 }
+a:visited { color: #880000 }
+a:hover { color: #cc4444 }
+.title { position: absolute; left: 1em; right: 1em; top: 10px; height: 52px; }
+.menu { position: absolute; top: 80px; left: 0.5em; width: 8em; border: solid
1px black; padding-left: 0.5em; padding-right: 0.5em }
+.menu ul { list-style: none; padding-left: 0pt}
+.main { position: absolute; top: 65px; left: 10.5em; right: 1em; }
+.code { background-color: #eeeeee; border: solid 1px black; padding: 0.5em; }
+.code-keyword { color: #880000; }
+.code-quote { color: #008800; }
+.code-object { color: #0000dd; }
+.code-java { margin: 0em; }
\ No newline at end of file
Propchange: felix/trunk/shell/doc/apache-felix-shell-service_files/site.css
------------------------------------------------------------------------------
svn:eol-style = native
