Add framework distribution.
git-svn-id: https://svn.apache.org/repos/asf/felix/trunk@910114 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/main.distribution/LICENSE b/main.distribution/LICENSE
new file mode 100644
index 0000000..d645695
--- /dev/null
+++ b/main.distribution/LICENSE
@@ -0,0 +1,202 @@
+
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright [yyyy] [name of copyright owner]
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
diff --git a/main.distribution/LICENSE.kxml2 b/main.distribution/LICENSE.kxml2
new file mode 100644
index 0000000..1fe595b
--- /dev/null
+++ b/main.distribution/LICENSE.kxml2
@@ -0,0 +1,19 @@
+Copyright (c) 2002,2003, Stefan Haustein, Oberhausen, Rhld., Germany
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.
diff --git a/main.distribution/NOTICE b/main.distribution/NOTICE
new file mode 100644
index 0000000..b60c01b
--- /dev/null
+++ b/main.distribution/NOTICE
@@ -0,0 +1,33 @@
+Apache Felix Main
+Copyright 2010 The Apache Software Foundation
+
+
+I. Included Software
+
+This product includes software developed at
+The Apache Software Foundation (http://www.apache.org/).
+Licensed under the Apache License 2.0.
+
+This product includes software developed at
+The OSGi Alliance (http://www.osgi.org/).
+Copyright (c) OSGi Alliance (2000, 2009).
+Licensed under the Apache License 2.0.
+
+This product includes software from http://kxml.sourceforge.net.
+Copyright (c) 2002,2003, Stefan Haustein, Oberhausen, Rhld., Germany.
+Licensed under BSD License.
+
+II. Used Software
+
+This product uses software developed at
+The OSGi Alliance (http://www.osgi.org/).
+Copyright (c) OSGi Alliance (2000, 2009).
+Licensed under the Apache License 2.0.
+
+This product uses software developed at
+The Codehaus (http://www.codehaus.org)
+Licensed under the Apache License 2.0.
+
+III. License Summary
+- Apache License 2.0
+- BSD License
diff --git a/main.distribution/assembly.xml b/main.distribution/assembly.xml
new file mode 100644
index 0000000..73a261a
--- /dev/null
+++ b/main.distribution/assembly.xml
@@ -0,0 +1,69 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<assembly>
+ <id>distribution</id>
+ <formats>
+ <format>zip</format>
+ <format>tar.gz</format>
+ </formats>
+ <fileSets>
+ <fileSet>
+ <directory>${project.basedir}/bin</directory>
+ <outputDirectory>bin</outputDirectory>
+ <useDefaultExcludes>true</useDefaultExcludes>
+ <includes>
+ <include>*.jar</include>
+ </includes>
+ </fileSet>
+ <fileSet>
+ <directory>${project.basedir}/bundle</directory>
+ <outputDirectory>bundle</outputDirectory>
+ <useDefaultExcludes>true</useDefaultExcludes>
+ <includes>
+ <include>*.jar</include>
+ </includes>
+ </fileSet>
+ <fileSet>
+ <directory>${project.basedir}/conf</directory>
+ <outputDirectory>conf</outputDirectory>
+ <useDefaultExcludes>true</useDefaultExcludes>
+ <includes>
+ <include>*.properties</include>
+ </includes>
+ </fileSet>
+ <fileSet>
+ <directory>${project.basedir}/doc</directory>
+ <outputDirectory>doc</outputDirectory>
+ <useDefaultExcludes>true</useDefaultExcludes>
+ <includes>
+ <include>**</include>
+ </includes>
+ </fileSet>
+ <fileSet>
+ <directory>${project.basedir}</directory>
+ <includes>
+ <include>README*</include>
+ <include>LICENSE*</include>
+ <include>NOTICE*</include>
+ </includes>
+ <outputDirectory>.</outputDirectory>
+ <useDefaultExcludes>true</useDefaultExcludes>
+ </fileSet>
+ </fileSets>
+</assembly>
diff --git a/main.distribution/conf/config.properties b/main.distribution/conf/config.properties
new file mode 100644
index 0000000..a00d9f6
--- /dev/null
+++ b/main.distribution/conf/config.properties
@@ -0,0 +1,100 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+#
+# Framework config properties.
+#
+
+# To override the packages the framework exports by default from the
+# class path, set this variable.
+#org.osgi.framework.system.packages=
+
+# To append packages to the default set of exported system packages,
+# set this value.
+#org.osgi.framework.system.packages.extra=
+
+# The following property makes specified packages from the class path
+# available to all bundles. You should avoid using this property.
+#org.osgi.framework.bootdelegation=sun.*,com.sun.*
+
+# Felix tries to guess when to implicitly boot delegate in certain
+# situations to ease integration without outside code. This feature
+# is enabled by default, uncomment the following line to disable it.
+#felix.bootdelegation.implicit=false
+
+# The following property explicitly specifies the location of the bundle
+# cache, which defaults to "felix-cache" in the current working directory.
+# If this value is not absolute, then the felix.cache.rootdir controls
+# how the absolute location is calculated. (See next property)
+#org.osgi.framework.storage=${dollar}{felix.cache.rootdir}/felix-cache
+
+# The following property is used to convert a relative bundle cache
+# location into an absolute one by specifying the root to prepend to
+# the relative cache path. The default for this property is the
+# current working directory.
+#felix.cache.rootdir=${dollar}{user.dir}
+
+# The following property controls whether the bundle cache is flushed
+# the first time the framework is initialized. Possible values are
+# "none" and "onFirstInit"; the default is "none".
+#org.osgi.framework.storage.clean=onFirstInit
+
+# The following property determines which actions are performed when
+# processing the auto-deploy directory. It is a comma-delimited list of
+# the following values: 'install', 'start', 'update', and 'uninstall'.
+# An undefined or blank value is equivalent to disabling auto-deploy
+# processing.
+felix.auto.deploy.action=install,start
+
+# The following property specifies the directory to use as the bundle
+# auto-deploy directory; the default is 'bundle' in the working directory.
+#felix.auto.deploy.dir=bundle
+
+# The following property is a space-delimited list of bundle URLs
+# to install when the framework starts. The ending numerical component
+# is the target start level. Any number of these properties may be
+# specified for different start levels.
+#felix.auto.install.1=
+
+# The following property is a space-delimited list of bundle URLs
+# to install and start when the framework starts. The ending numerical
+# component is the target start level. Any number of these properties
+# may be specified for different start levels.
+#felix.auto.start.1=
+
+felix.log.level=1
+
+# Sets the initial start level of the framework upon startup.
+#org.osgi.framework.startlevel.beginning=1
+
+# Sets the start level of newly installed bundles.
+#felix.startlevel.bundle=1
+
+# Felix installs a stream and content handler factories by default,
+# uncomment the following line to not install them.
+#felix.service.urlhandlers=false
+
+# The launcher registers a shutdown hook to cleanly stop the framework
+# by default, uncomment the following line to disable it.
+#felix.shutdown.hook=false
+
+#
+# Bundle config properties.
+#
+
+org.osgi.service.http.port=8080
+obr.repository.url=http://felix.apache.org/obr/releases.xml
diff --git a/main.distribution/doc/apache-felix-framework-launching-and-embedding.html b/main.distribution/doc/apache-felix-framework-launching-and-embedding.html
new file mode 100644
index 0000000..fc4887d
--- /dev/null
+++ b/main.distribution/doc/apache-felix-framework-launching-and-embedding.html
@@ -0,0 +1,1067 @@
+<!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 - Apache Felix Framework Launching and Embedding</title>
+ <link rel="stylesheet" href="apache-felix-framework-launching-and-embedding_files/site.css" type="text/css" media="all">
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ </head><body>
+ <div class="title"><div class="logo"><a href="http://felix.apache.org/site/index.html"><img alt="Apache Felix" src="apache-felix-framework-launching-and-embedding_files/logo.png" border="0"></a></div><div class="header"><a href="http://www.apache.org/"><img alt="Apache" src="apache-felix-framework-launching-and-embedding_files/apache.png" border="0"></a></div></div>
+ <div class="menu">
+<ul>
+ <li><a href="http://felix.apache.org/site/news.html" title="news">news</a></li>
+ <li><a href="http://felix.apache.org/site/license.html" title="license">license</a></li>
+ <li><a href="http://felix.apache.org/site/downloads.cgi" rel="nofollow">downloads</a></li>
+ <li><a href="http://felix.apache.org/site/documentation.html" title="documentation">documentation</a></li>
+ <li><a href="http://felix.apache.org/site/mailinglists.html" title="mailinglists">mailing lists</a></li>
+ <li><a href="http://felix.apache.org/site/contributing.html" title="Contributing">contributing</a></li>
+ <li><a href="http://www.apache.org/" rel="nofollow">asf</a></li>
+ <li><a href="http://www.apache.org/foundation/sponsorship.html" rel="nofollow">sponsorship</a></li>
+ <li><a href="http://www.apache.org/foundation/thanks.html" rel="nofollow">sponsors</a>
+<!-- ApacheCon Ad -->
+<iframe src="apache-felix-framework-launching-and-embedding_files/button.html" style="border-width: 0pt; float: left;" frameborder="0" height="135" scrolling="no" width="135"></iframe>
+<p style="height: 100px;">
+<!-- ApacheCon Ad -->
+</p></li></ul> </div>
+ <div class="main">
+<h1><a name="ApacheFelixFrameworkLaunchingandEmbedding-ApacheFelixFrameworkLaunchingandEmbedding"></a>Apache Felix Framework Launching and Embedding</h1>
+
+<p><em>[This document describes framework launching introduced in Felix
+2.0.0 and is incompatible with older versions of the Felix framework.]</em></p>
+
+<ul>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-introduction">Introduction</a></li>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-overview">API Overview</a>
+ <ul>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-creatingandconfiguring">Creating and Configuring the Framework Instance</a></li>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-startinginstance">Starting the Framework Instance</a></li>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-stoppinginstance">Stopping the Framework Instance</a></li>
+ </ul>
+ </li>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-launching">Launching Felix</a>
+ <ul>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-standardlauncher">Standard Felix Launcher</a></li>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-customlauncher">Custom Felix Launcher</a></li>
+ </ul>
+ </li>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-embedding">Embedding Felix</a>
+ <ul>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-hostinteraction">Host/Felix Interaction</a></li>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-hostservices">Providing Host Application Services</a></li>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-hostserviceusage">Using Services Provided by Bundles</a>
+ <ul>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-servicereflection">Using Bundle Services via Reflection</a></li>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-serviceother">Other Approaches</a></li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-caveat">Caveat</a></li>
+ <li><a href="#ApacheFelixFrameworkLaunchingandEmbedding-feedback">Feedback</a></li>
+</ul>
+
+
+<p><a name="ApacheFelixFrameworkLaunchingandEmbedding-introduction"></a></p>
+
+<h1><a name="ApacheFelixFrameworkLaunchingandEmbedding-Introduction"></a>Introduction</h1>
+
+<p>The Apache Felix framework is intended to be easily launchable and
+embeddable. For example, Felix avoids the use of system properties for
+configuration, since these are globals and can cause interference if
+multiple framework instances are created in the same VM. Felix also
+tries to multiplex singleton facilities, like the URL stream handler
+factory. The goal is to make it possible to use Felix in as many
+scenarios as possible; however, this is still just a goal. In other
+words, this is a work in progress and if any issues arise, it would be
+greatly appreciated if they are brought to the attention of the Felix
+community. The next section provides a Felix API overview, while the
+remainder of the document is divided into two sections, one focusing on
+how to launch Felix and one focusing on how to embed Felix into a host
+application.</p>
+
+<p><a name="ApacheFelixFrameworkLaunchingandEmbedding-overview"></a></p>
+
+<h1><a name="ApacheFelixFrameworkLaunchingandEmbedding-APIOverview"></a>API Overview</h1>
+
+<p>The Felix framework is implemented by the <tt>org.apache.felix.framework.Felix</tt> class or just <tt>Felix</tt>
+for short. As part of the R4.2 OSGi specification, the launching and
+embedding API of the OSGi framework has been standardized. The approach
+is to have the framework implement the <tt>org.osgi.framework.launch.Framework</tt> interface, which extends the <tt>org.osgi.framework.Bundle</tt> interface. These interfaces provide the necessary means to launch and manage framework instances. The <tt>Bundle</tt> interface is defined as:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">public</span> <span class="code-keyword">interface</span> Bundle
+{
+ BundleContext getBundleContext();
+ <span class="code-object">long</span> getBundleId();
+ URL getEntry(<span class="code-object">String</span> name);
+ Enumeration getEntryPaths(<span class="code-object">String</span> path);
+ Enumeration findEntries(<span class="code-object">String</span> path, <span class="code-object">String</span> filePattern, <span class="code-object">boolean</span> recurse);
+ Dictionary getHeaders();
+ Dictionary getHeaders(<span class="code-object">String</span> locale);
+ <span class="code-object">long</span> getLastModified();
+ <span class="code-object">String</span> getLocation();
+ URL getResource(<span class="code-object">String</span> name);
+ Enumeration getResources(<span class="code-object">String</span> name) <span class="code-keyword">throws</span> IOException;
+ ServiceReference[] getRegisteredServices();
+ ServiceReference[] getServicesInUse();
+ <span class="code-object">int</span> getState();
+ <span class="code-object">String</span> getSymbolicName();
+ Version getVersion();
+ <span class="code-object">boolean</span> hasPermission(<span class="code-object">Object</span> obj);
+ <span class="code-object">Class</span> loadClass(<span class="code-object">String</span> name) <span class="code-keyword">throws</span> ClassNotFoundException;
+ void start() <span class="code-keyword">throws</span> BundleException;
+ void stop() <span class="code-keyword">throws</span> BundleException;
+ void uninstall() <span class="code-keyword">throws</span> BundleException;
+ void update() <span class="code-keyword">throws</span> BundleException;
+ void update(InputStream is) <span class="code-keyword">throws</span> BundleException;
+}
+</pre>
+</div></div>
+
+<p>The <tt>Framework</tt> interface is defined as:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">public</span> <span class="code-keyword">interface</span> Framework <span class="code-keyword">extends</span> Bundle
+{
+ void init();
+ FrameworkEvent waitForStop();
+}
+</pre>
+</div></div>
+
+<p>To actually construct a framework instance, the R4.2 specification defines the FrameworkFactory interface:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">public</span> <span class="code-keyword">interface</span> FrameworkFactory
+{
+ Framework newFramework(Map configMap);
+}
+</pre>
+</div></div>
+
+<p>The framework factory can be used to create configured framework instances. It is obtained following the standard <tt>META-INF/services</tt> approach.</p>
+
+<p><a name="ApacheFelixFrameworkLaunchingandEmbedding-creatingandconfiguring"></a></p>
+
+<h2><a name="ApacheFelixFrameworkLaunchingandEmbedding-CreatingandConfiguringtheFrameworkInstance"></a>Creating and Configuring the Framework Instance</h2>
+
+<p>You use the framework factory to construct and configure a framework
+instance (or by directly instantiating the Felix class). The
+configuration map may contain the following OSGi standard properties:</p>
+
+<ul>
+ <li><tt>org.osgi.framework.system.packages</tt> - specifies a
+list of packages the system bundle should export from the environment;
+if this is not set, then the framework uses a reasonable default fault.</li>
+ <li><tt>org.osgi.framework.system.packages.extra</tt>
+- specifies a list of additional packages the system bundle should
+export from the environment that are appended to the packages specified
+in <tt>org.osgi.framework.system.packages</tt>; there is no default value for this property.</li>
+ <li><tt>org.osgi.framework.bootdelegation</tt>
+- specifies a list of packages that should be made implicitly available
+to all bundles from the environment (i.e., no need to import them);
+there is no default value for this property and its use should be
+avoided.</li>
+ <li><tt>org.osgi.framework.storage</tt> - specifies the
+path to a directory, which will be created if it does not exist, to use
+for bundle cache storage; the default value for this property is "<tt>felix-cache</tt>" in the current working directory.</li>
+ <li><tt>org.osgi.framework.storage.clean</tt>
+- specifies whether the bundle cache should be flushed; the default
+value for this property is "none", but it can be changed to
+"onFirstInit" to flush the bundle cache when the framework is
+initialized.</li>
+ <li><tt>org.osgi.framework.startlevel.beginning</tt> - specifies the start level the framework enters upon startup; the default value for this property is 1.</li>
+</ul>
+
+
+<p>Felix also has the following, non-standard configuration properties:</p>
+
+<ul>
+ <li><tt>felix.cache.rootdir</tt> - specifies which directory should be used to calculate absolute paths when relative paths are used for the <tt>org.osgi.framework.storage</tt> property; the default value for this property is the current working directory.</li>
+ <li><tt>felix.systembundle.activators</tt> - specifies a <tt>List</tt> of <tt>BundleActivator</tt>
+instances that are started/stopped when the System Bundle is
+started/stopped; the specified instances will receive the System
+Bundle's <tt>BundleContext</tt> when invoked.</li>
+ <li><tt>felix.log.logger</tt> - specifies an instance of <tt>org.apache.felix.framework.util.Logger</tt> that the framework uses as its default logger.</li>
+ <li><tt>felix.log.level</tt> - specifies an integer <tt>String</tt>
+whose value indicates the degree of logging reported by the framework;
+the default value is "1" and "0" turns off logging completely,
+otherwise log levels match those specified in the OSGi Log Service
+(i.e., 1 = error, 2 = warning, 3 = information, and 4 = debug).</li>
+ <li><tt>felix.startlevel.bundle</tt> - specifies the start level for newly installed bundles; the default value is 1.</li>
+ <li><tt>felix.bootdelegation.implicit</tt>
+- specifies whether or not the framework should try to guess when to
+boot delegate when external code tries to load classes or resources;
+the default value is "<tt>true</tt>".</li>
+ <li><tt>framework.service.urlhandlers</tt> - specifies whether or not to activate the URL Handlers service for the framework instance; the default value is "<tt>true</tt>", which results in the <tt>URL.setURLStreamHandlerFactory()</tt> and <tt>URLConnection.setContentHandlerFactory()</tt> being called.</li>
+</ul>
+
+
+<p>The configuration map is copied and the keys are treated as case
+insensitive. You are not able to change the framework's configuration
+after construction. If you need a different configuration, you must
+create a new framework instance.</p>
+
+<div class="panelMacro"><table class="warningMacro"><colgroup><col width="24"><col></colgroup><tbody><tr><td valign="top"><img src="apache-felix-framework-launching-and-embedding_files/forbidden.gif" alt="" align="absmiddle" border="0" height="16" width="16"></td><td><b>WARNING</b><br><p>Felix configuration properties have change considerably starting from <tt>1.4.0</tt>; if you are upgrading from an earlier version, the <a href="http://felix.apache.org/site/apache-felix-framework-usage-documentation.html#ApacheFelixFrameworkUsageDocumentation-migrating">usage document</a> describes the configuration property changes.</p></td></tr></tbody></table></div>
+
+<p><a name="ApacheFelixFrameworkLaunchingandEmbedding-startinginstance"></a></p>
+
+<h2><a name="ApacheFelixFrameworkLaunchingandEmbedding-StartingtheFrameworkInstance"></a>Starting the Framework Instance</h2>
+
+<p>The <tt>start()</tt> method is used to start the framework instance. If the <tt>init()</tt> method was not invoked prior to calling <tt>start()</tt>, then it is invoked by <tt>start()</tt>. The two methods result in two different framework state transitions:</p>
+
+<ul>
+ <li><tt>init()</tt> results in the framework instance in the <tt>Bundle.STARTING</tt> state.</li>
+ <li><tt>start()</tt> results in the framework instance in the <tt>Bundle.ACTIVE</tt> state.</li>
+</ul>
+
+
+<p>The <tt>init()</tt> method is necessary since the framework does not have a <tt>BundleContext</tt> when it is first created, so a transition to the <tt>Bundle.STARTING</tt> state is required to acquire its context (via <tt>Bundle.getBundleContext()</tt>) for performing various tasks, such as installing bundles. Note that Felix also provides the <tt>felix.systembundle.activators</tt> property that serves a similar purpose, but is not standard. After the <tt>init()</tt> method completes, the follow actions have been performed:</p>
+
+<ul>
+ <li>Event handling is enabled.</li>
+ <li>The security manager is installed if it is enabled.</li>
+ <li>The framework is set to start level 0.</li>
+ <li>All bundles in the bundle caches are reified and their state is set to <tt>Bundle.INSTALLED</tt>.</li>
+ <li>The framework gets a valid <tt>BundleContext</tt>.</li>
+ <li>All framework-provided services are made available (e.g., PackageAdmin, StartLevel, etc.).</li>
+ <li>The framework enters the <tt>Bundle.STARTING</tt> state.</li>
+</ul>
+
+
+<p>A call to <tt>start()</tt> is necessary to start the framework instance, if the <tt>init()</tt> method is invoked manually. Invoking <tt>init()</tt> or <tt>start()</tt> on an already started framework as no effect.</p>
+
+<p><a name="ApacheFelixFrameworkLaunchingandEmbedding-stoppinginstance"></a></p>
+
+<h2><a name="ApacheFelixFrameworkLaunchingandEmbedding-StoppingtheFrameworkInstance"></a>Stopping the Framework Instance</h2>
+
+<p>To stop the framework instance, invoke the <tt>stop()</tt> method, which will asynchronously stop the framework. To know when the framework has finished its shutdown sequence, use the <tt>waitForStop()</tt> method to wait until it is complete. A stopped framework will be in the <tt>Bundle.RESOLVED</tt> state. It is possible to restart the framework, using the normal combination of <tt>init()</tt>/<tt>start()</tt> methods as previously described.</p>
+
+<p><a name="ApacheFelixFrameworkLaunchingandEmbedding-launching"></a></p>
+
+<h1><a name="ApacheFelixFrameworkLaunchingandEmbedding-LaunchingaFramework"></a>Launching a Framework</h1>
+
+<p>Launching a framework is fairly simple and involves only four steps:</p>
+
+<ol>
+ <li>Define some configuration properties.</li>
+ <li>Obtain framework factory.</li>
+ <li>Use factory to create framework with the configuration properties.</li>
+ <li>Invoke the <tt>Framework.start()</tt> method.</li>
+</ol>
+
+
+<p>In reality, the first step is optional, since all properties will
+have reasonable defaults, but if you are creating a launcher you will
+generally want to more than that, such as automatically installing and
+starting bundles when you start the framework instance. The default
+Felix launcher defines reusable functionality to automatically install
+and/or start bundles upon framework startup; see the <a href="http://felix.apache.org/site/apache-felix-framework-usage-documentation.html#ApacheFelixFrameworkUsageDocumentation-configuringfelix">usage document</a> for more information on configuring Felix and on the various configuration properties.</p>
+
+<p>The remainder of this section describes how the standard Felix
+launcher works as well as how to create a custom launcher for Felix.</p>
+
+<p><a name="ApacheFelixFrameworkLaunchingandEmbedding-standardlauncher"></a></p>
+
+<h2><a name="ApacheFelixFrameworkLaunchingandEmbedding-StandardFelixFrameworkLauncher"></a>Standard Felix Framework Launcher</h2>
+
+<p>The standard Felix launcher is very simple and is not intended to
+solve every possible requirement; it is intended to work for most
+standard situations. Most special launching requirements should be
+resolved by creating a custom launcher. This section describes how the
+standard launcher works. The following code represents the complete <tt>main()</tt> method of the standard launcher, each numbered comment will be described in more detail below:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">public</span> <span class="code-keyword">static</span> void main(<span class="code-object">String</span>[] args) <span class="code-keyword">throws</span> Exception
+{
+ <span class="code-comment">// (1) Check <span class="code-keyword">for</span> command line arguments and verify usage.
+</span> <span class="code-object">String</span> bundleDir = <span class="code-keyword">null</span>;
+ <span class="code-object">String</span> cacheDir = <span class="code-keyword">null</span>;
+ <span class="code-object">boolean</span> expectBundleDir = <span class="code-keyword">false</span>;
+ <span class="code-keyword">for</span> (<span class="code-object">int</span> i = 0; i < args.length; i++)
+ {
+ <span class="code-keyword">if</span> (args[i].equals(BUNDLE_DIR_SWITCH))
+ {
+ expectBundleDir = <span class="code-keyword">true</span>;
+ }
+ <span class="code-keyword">else</span> <span class="code-keyword">if</span> (expectBundleDir)
+ {
+ bundleDir = args[i];
+ expectBundleDir = <span class="code-keyword">false</span>;
+ }
+ <span class="code-keyword">else</span>
+ {
+ cacheDir = args[i];
+ }
+ }
+ <span class="code-keyword">if</span> ((args.length > 3) || (expectBundleDir && bundleDir == <span class="code-keyword">null</span>))
+ {
+ <span class="code-object">System</span>.out.println(<span class="code-quote">"Usage: [-b <bundle-deploy-dir>] [<bundle-cache-dir>]"</span>);
+ <span class="code-object">System</span>.exit(0);
+ }
+
+ <span class="code-comment">// (2) Load system properties.
+</span> Main.loadSystemProperties();
+
+ <span class="code-comment">// (3) Read configuration properties.
+</span> Properties configProps = Main.loadConfigProperties();
+ <span class="code-keyword">if</span> (configProps == <span class="code-keyword">null</span>)
+ {
+ <span class="code-object">System</span>.err.println(<span class="code-quote">"No "</span> + CONFIG_PROPERTIES_FILE_VALUE + <span class="code-quote">" found."</span>);
+ configProps = <span class="code-keyword">new</span> Properties();
+ }
+
+ <span class="code-comment">// (4) Copy framework properties from the system properties.
+</span> Main.copySystemProperties(configProps);
+
+ <span class="code-comment">// (5) Use the specified auto-deploy directory over <span class="code-keyword">default</span>.
+</span> <span class="code-keyword">if</span> (bundleDir != <span class="code-keyword">null</span>)
+ {
+ configProps.setProperty(AutoProcessor.AUTO_DEPLOY_DIR_PROPERY, bundleDir);
+ }
+
+ <span class="code-comment">// (6) Use the specified bundle cache directory over <span class="code-keyword">default</span>.
+</span> <span class="code-keyword">if</span> (cacheDir != <span class="code-keyword">null</span>)
+ {
+ configProps.setProperty(Constants.FRAMEWORK_STORAGE, cacheDir);
+ }
+
+ <span class="code-comment">// (7) Add a shutdown hook to clean stop the framework.
+</span> <span class="code-object">String</span> enableHook = configProps.getProperty(SHUTDOWN_HOOK_PROP);
+ <span class="code-keyword">if</span> ((enableHook == <span class="code-keyword">null</span>) || !enableHook.equalsIgnoreCase(<span class="code-quote">"<span class="code-keyword">false</span>"</span>))
+ {
+ <span class="code-object">Runtime</span>.getRuntime().addShutdownHook(<span class="code-keyword">new</span> <span class="code-object">Thread</span>() {
+ <span class="code-keyword">public</span> void run()
+ {
+ <span class="code-keyword">try</span>
+ {
+ <span class="code-keyword">if</span> (m_fwk != <span class="code-keyword">null</span>)
+ {
+ m_fwk.stop();
+ m_fwk.waitForStop(0);
+ }
+ }
+ <span class="code-keyword">catch</span> (Exception ex)
+ {
+ <span class="code-object">System</span>.err.println(<span class="code-quote">"Error stopping framework: "</span> + ex);
+ }
+ }
+ });
+ }
+
+ <span class="code-comment">// Print welcome banner.
+</span> <span class="code-object">System</span>.out.println(<span class="code-quote">"\nWelcome to Felix"</span>);
+ <span class="code-object">System</span>.out.println(<span class="code-quote">"================\n"</span>);
+
+ <span class="code-keyword">try</span>
+ {
+ <span class="code-comment">// (8) Create an instance and initialize the framework.
+</span> FrameworkFactory factory = getFrameworkFactory();
+ m_fwk = factory.newFramework(configProps);
+ m_fwk.init();
+ <span class="code-comment">// (9) Use the system bundle context to process the auto-deploy
+</span> <span class="code-comment">// and auto-install/auto-start properties.
+</span> AutoProcessor.process(configProps, m_fwk.getBundleContext());
+ <span class="code-comment">// (10) Start the framework.
+</span> m_fwk.start();
+ <span class="code-comment">// (11) Wait <span class="code-keyword">for</span> framework to stop to exit the VM.
+</span> m_fwk.waitForStop(0);
+ <span class="code-object">System</span>.exit(0);
+ }
+ <span class="code-keyword">catch</span> (Exception ex)
+ {
+ <span class="code-object">System</span>.err.println(<span class="code-quote">"Could not create framework: "</span> + ex);
+ ex.printStackTrace();
+ <span class="code-object">System</span>.exit(-1);
+ }
+}
+</pre>
+</div></div>
+
+<p>The general steps of the standard launcher are quite straightforward:</p>
+
+<ol>
+ <li>The launcher supports setting the auto-deploy directory (with the <tt>-b</tt>
+switch) and setting the bundle cache path with a single argument, so
+check for this and issue a usage message it there are more than one
+arguments.</li>
+ <li>Load any system properties specified in the <tt>system.properties</tt> file; this file is typically located in the <tt>conf/</tt> directory of the Felix installation directory, but it can be specified directly using the <tt>felix.system.properties</tt>
+system property. This file is not needed to launch Felix and is
+provided merely for convenience when system properties must be
+specified. The file is a standard Java properties file, but it also
+supports property substitution using <tt>${<property-name</tt>} syntax. Property substitution can be nested; only system properties will be used for substitution.</li>
+ <li>Load any configuration properties specified in the <tt>config.properties</tt> file; this file is typically located in the <tt>conf/</tt> directory of the Felix installation directory, but it can be specified directly using the <tt>felix.config.properties</tt>
+system property. This file is used to configure the Felix instance
+created by the launcher. The file is a standard Java properties file,
+but it also supports property substitution using "<tt>${<property-name></tt>}"
+syntax. Property substitution can be nested; configuration and system
+properties will be used for substitution with configuration properties
+having precedence.</li>
+ <li>For convenience, any configuration
+properties that are set as system properties are copied into the set of
+configuration properties. This provide an easy way to add to or
+override configuration properties specified in the <tt>config.properties</tt> file, since the Felix instance will never look at system properties for configuration.</li>
+ <li>If the <tt>-b</tt> switch was used to specify an auto-deploy directory, then use that to set the value of <tt>felix.auto.deploy.dir</tt>.</li>
+ <li>If a single command-line argument is specified, then use that to set the value of <tt>org.osgi.framework.storage</tt>; relative paths are relative to the current directory unless the <tt>felix.cache.rootdir</tt> property is set.</li>
+ <li>Add a shutdown hook to cleanly stop the framework, unless the hook is disabled.</li>
+ <li>Create a framework instance using the <tt>FrameworkFactory</tt> passing in the configuration properties, then initialize the factory instance; see the <a href="#ApacheFelixFrameworkLaunchingandEmbedding-customlauncher">custom launcher example</a> below to see how the META-INF/services <tt>FrameworkFactory</tt> is obtained.</li>
+ <li>Use <tt>org.apache.felix.main.AutoProcessor</tt>, which will automatically deploy any bundles in the auto-deploy directory as well as bundles specified in the <tt>felix.auto.install</tt> and <tt>felix.auto.start</tt>
+configuration properties during framework startup to automatically
+install and/or start bundles; see the usage document for more
+information <a href="http://felix.apache.org/site/apache-felix-framework-usage-documentation.html#ApacheFelixFrameworkUsageDocumentation-configuringframework">configuration properties</a> and <a href="http://felix.apache.org/site/apache-felix-framework-usage-documentation.html#ApacheFelixFrameworkUsageDocumentation-autodeploy">bundle auto-deploy</a>.</li>
+ <li>Invoke <tt>waitForStop()</tt> to wait for the framework to stop to force the VM to exit; this is necessary because the framework never calls <tt>System.exit()</tt> and some libraries (e.g., Swing) create threads that will not allow the VM to exit.</li>
+</ol>
+
+
+<p>The framework is not active until the <tt>start()</tt> method is
+called. If no shell bundles are installed and started or if there is
+difficulty locating the shell bundles specified in the auto-start
+property, then it will appear as if the framework is hung, but it is
+actually running without any way to interact with it since the shell
+bundles provide the only means of interaction.</p>
+
+<p><a name="ApacheFelixFrameworkLaunchingandEmbedding-customlauncher"></a></p>
+
+<h2><a name="ApacheFelixFrameworkLaunchingandEmbedding-CustomFrameworkLauncher"></a>Custom Framework Launcher</h2>
+
+<p>This section creates a bare-bones launcher to demonstrate the
+minimum requirements for creating an interactive launcher for the Felix
+framework. This example uses the standard Felix shell bundles for
+interactivity, but any other bundles could be used instead. For
+example, the shell service and telnet bundles could be used to launch
+Felix and make it remotely accessible.</p>
+
+<p>This example launcher project has the following directory structure:</p>
+
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>launcher/
+ lib/
+ org.apache.felix.main-2.0.0.jar
+ bundle/
+ org.apache.felix.shell-1.4.0.jar
+ org.apache.felix.shell.tui-1.4.0.jar
+ src/
+ example/
+ Main.java
+</pre>
+</div></div>
+
+<p>The <tt>lib/</tt> directory contains Felix' main JAR file, which
+also contains the OSGi core interfaces. The main JAR file is used so
+that we can reuse the default launcher's auto-install/auto-start
+configuration property handling; if these capabilities are not needed,
+then it would be possible to use the framework JAR file instead of the
+main JAR file. The <tt>bundle/</tt> directory contains the shell
+service and textual shell interface bundles that will be used for
+interacting with the framework instance. Note: If you do not launch
+Felix with interactive bundles, it will appear as if the framework
+instance is hung, but it is actually just sitting there waiting for
+someone to tell it to do something. The <tt>src/example/</tt> directory contains the following <tt>Main.java</tt> file, which is a very simplistic Felix launcher.</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">package</span> example;
+
+<span class="code-keyword">import</span> java.io.*;
+<span class="code-keyword">import</span> org.osgi.framework.launch.*;
+<span class="code-keyword">import</span> org.apache.felix.main.AutoProcessor;
+
+<span class="code-keyword">public</span> class Main
+{
+ <span class="code-keyword">private</span> <span class="code-keyword">static</span> Framework m_fwk = <span class="code-keyword">null</span>;
+
+ <span class="code-keyword">public</span> <span class="code-keyword">static</span> void main(<span class="code-object">String</span>[] argv) <span class="code-keyword">throws</span> Exception
+ {
+ <span class="code-comment">// Print welcome banner.
+</span> <span class="code-object">System</span>.out.println(<span class="code-quote">"\nWelcome to Felix."</span>);
+ <span class="code-object">System</span>.out.println(<span class="code-quote">"=================\n"</span>);
+
+ <span class="code-keyword">try</span>
+ {
+ m_fwk = getFrameworkFactory().newFramework(<span class="code-keyword">null</span>);
+ m_fwk.init()
+ AutoProcessor.process(<span class="code-keyword">null</span>, m_fwk.getBundleContext());
+ m_fwk.start();
+ m_fwk.waitForStop();
+ <span class="code-object">System</span>.exit(0);
+ }
+ <span class="code-keyword">catch</span> (Exception ex)
+ {
+ <span class="code-object">System</span>.err.println(<span class="code-quote">"Could not create framework: "</span> + ex);
+ ex.printStackTrace();
+ <span class="code-object">System</span>.exit(-1);
+ }
+ }
+
+ <span class="code-keyword">private</span> <span class="code-keyword">static</span> FrameworkFactory getFrameworkFactory() <span class="code-keyword">throws</span> Exception
+ {
+ URL url = Main.class.getClassLoader().getResource(
+ <span class="code-quote">"META-INF/services/org.osgi.framework.launch.FrameworkFactory"</span>);
+ <span class="code-keyword">if</span> (url != <span class="code-keyword">null</span>)
+ {
+ BufferedReader br = <span class="code-keyword">new</span> BufferedReader(<span class="code-keyword">new</span> InputStreamReader(url.openStream()));
+ <span class="code-keyword">try</span>
+ {
+ <span class="code-keyword">for</span> (<span class="code-object">String</span> s = br.readLine(); s != <span class="code-keyword">null</span>; s = br.readLine())
+ {
+ s = s.trim();
+ <span class="code-comment">// Try to load first non-empty, non-commented line.
+</span> <span class="code-keyword">if</span> ((s.length() > 0) && (s.charAt(0) != '#'))
+ {
+ <span class="code-keyword">return</span> (FrameworkFactory) <span class="code-object">Class</span>.forName(s).newInstance();
+ }
+ }
+ }
+ <span class="code-keyword">finally</span>
+ {
+ <span class="code-keyword">if</span> (br != <span class="code-keyword">null</span>) br.close();
+ }
+ }
+
+ <span class="code-keyword">throw</span> <span class="code-keyword">new</span> Exception(<span class="code-quote">"Could not find framework factory."</span>);
+ }
+}
+</pre>
+</div></div>
+
+<p>This launcher relies on the default behavior of <tt>AutoProcessor</tt>
+to automatically deploy the shell bundles. This simple, generic
+launcher provides a good starting point if the default Felix launcher
+is not sufficient. Since very few configuration properties are
+specified, the default values are used. For the bundle auto-deploy
+directory, "<tt>bundle</tt>" in the current directory is used, while for the framework bundle cache, "<tt>felix-cache</tt>" in the current directory is used.</p>
+
+<p>By breaking down the above source code into small chunks, it is quite easy to see what is going on.</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"> m_fwk = getFrameworkFactory().newFramework(<span class="code-keyword">null</span>);
+ m_fwk.init()
+</pre>
+</div></div>
+
+<p>These steps get a the framework factory service and use it to create
+a framework instance with a default configuration. Once the framework
+instance is created, it is initialized with <tt>init()</tt>.</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"> AutoProcessor.process(<span class="code-keyword">null</span>, m_fwk.getBundleContext());
+</pre>
+</div></div>
+
+<p>The <tt>AutorProcessor</tt> will automatically deploy bundles in the
+auto-deploy directory and any referenced from the auto-install/start
+properties. Since we are using an empty configuration, the auto-deploy
+directory is the <tt>bundle</tt> directory in the current directory
+and there are no auto properties. Therefore, in this case, the two
+shell bundles will be installed.</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"> m_fwk.start();
+ m_fwk.waitForStop();
+ <span class="code-object">System</span>.exit(0);
+</pre>
+</div></div>
+
+<p>These final steps start the framework and cause the launching
+application thread to wait for the framework to stop and when it does
+the launching thread calls <tt>System.exit()</tt> to make sure the VM actually exits.</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"> <span class="code-keyword">private</span> <span class="code-keyword">static</span> FrameworkFactory getFrameworkFactory() <span class="code-keyword">throws</span> Exception
+ {
+ ...
+ }
+</pre>
+</div></div>
+
+<p>This method retrieves the framework factory service by doing a
+META-INF/services resource lookup, which it can use to obtain the
+concrete class name for the factory. If you are using Java 6, then you
+can use the <tt>ServiceLoader</tt> API in the JRE to further simplify the factory service lookup.</p>
+
+<p>The following command compiles the launcher when run from the root directory of the launcher project:</p>
+
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>javac -d . -classpath lib/org.apache.felix.main-2.0.0.jar src/example/Main.java
+</pre>
+</div></div>
+
+<p>After executing this command, an <tt>example/</tt> directory is
+created in the current directory, which contains the generated class
+file. The following command executes the simple launcher when run from
+the root directory of the launcher project:</p>
+
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>java -cp .:lib/org.apache.felix.main-2.0.0.jar example.Main
+</pre>
+</div></div>
+
+<p>After executing this command, a "<tt>felix-cache/</tt>" directory is created that contains the cached bundles, which were installed from the <tt>bundle/</tt> directory.</p>
+
+<p><a name="ApacheFelixFrameworkLaunchingandEmbedding-embedding"></a></p>
+
+<h1><a name="ApacheFelixFrameworkLaunchingandEmbedding-EmbeddingFelix"></a>Embedding Felix</h1>
+
+<p>Embedding Felix into a host application is a simple way to provide a
+sophisticated extensibility mechanism (i.e., a plugin system) to the
+host application. Embedding Felix is very similar to launching Felix as
+described above, the main difference is that the host application
+typically wants to interact with the framework instance and/or
+installed bundles/services from the outside. This is fairly easy to
+achieve with Felix, but there are some subtle issues to understand.
+This section presents the mechanisms for embedding Felix into a host
+application and the issues in doing so.</p>
+
+<p><a name="ApacheFelixFrameworkLaunchingandEmbedding-hostinteraction"></a></p>
+
+<h2><a name="ApacheFelixFrameworkLaunchingandEmbedding-Host/FelixInteraction"></a>Host/Felix Interaction</h2>
+
+<p>In the section on <a href="#ApacheFelixFrameworkLaunchingandEmbedding-launching">launching</a> Felix above, the <tt>Felix</tt> accepts a configuration property called <tt>felix.systembundle.activators</tt>,
+which is a list of bundle activator instances. These bundle activator
+instances provide a convenient way for host applications to interact
+with the Felix framework. The ability offered by these activators can
+also be accomplished by invoking <tt>init()</tt> on the framework instance and the using <tt>getBundleContext()</tt> to get the System Bundle's context, but it can be more convenient to use an activator instance.</p>
+
+<p>Each activator instance passed into the constructor effectively becomes part of the System Bundle. This means that the <tt>start()</tt>/<tt>stop()</tt> methods of each activator instance in the list gets invoked when the System Bundle's activator <tt>start()</tt>/<tt>stop()</tt> methods gets invoked, respectively. Each activator instance will be given the System Bundle's <tt>BundleContext</tt> object so that they can interact with the framework. Consider following snippet of a bundle activator:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">public</span> class HostActivator <span class="code-keyword">implements</span> BundleActivator
+{
+ <span class="code-keyword">private</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-keyword">public</span> void stop(BundleContext context)
+ {
+ m_context = <span class="code-keyword">null</span>;
+ }
+
+ <span class="code-keyword">public</span> Bundle[] getBundles()
+ {
+ <span class="code-keyword">if</span> (m_context != <span class="code-keyword">null</span>)
+ {
+ <span class="code-keyword">return</span> m_context.getBundles();
+ }
+ <span class="code-keyword">return</span> <span class="code-keyword">null</span>;
+ }
+}
+</pre>
+</div></div>
+
+<p>Given the above bundle activator, it is now possible to embed Felix
+into a host application and interact with it as the following snippet
+illustrates:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">public</span> class HostApplication
+{
+ <span class="code-keyword">private</span> HostActivator m_activator = <span class="code-keyword">null</span>;
+ <span class="code-keyword">private</span> Felix m_felix = <span class="code-keyword">null</span>;
+
+ <span class="code-keyword">public</span> HostApplication()
+ {
+ <span class="code-comment">// Create a configuration property map.
+</span> Map configMap = <span class="code-keyword">new</span> HashMap();
+ <span class="code-comment">// Create host activator;
+</span> m_activator = <span class="code-keyword">new</span> HostActivator();
+ List list = <span class="code-keyword">new</span> ArrayList();
+ list.add(m_activator);
+ configMap.put(FelixConstants.SYSTEMBUNDLE_ACTIVATORS_PROP, list);
+
+ <span class="code-keyword">try</span>
+ {
+ <span class="code-comment">// Now create an instance of the framework with
+</span> <span class="code-comment">// our configuration properties.
+</span> m_felix = <span class="code-keyword">new</span> Felix(configMap);
+ <span class="code-comment">// Now start Felix instance.
+</span> m_felix.start();
+ }
+ <span class="code-keyword">catch</span> (Exception ex)
+ {
+ <span class="code-object">System</span>.err.println(<span class="code-quote">"Could not create framework: "</span> + ex);
+ ex.printStackTrace();
+ }
+ }
+
+ <span class="code-keyword">public</span> Bundle[] getInstalledBundles()
+ {
+ <span class="code-comment">// Use the system bundle activator to gain external
+</span> <span class="code-comment">// access to the set of installed bundles.
+</span> <span class="code-keyword">return</span> m_activator.getBundles();
+ }
+
+ <span class="code-keyword">public</span> void shutdownApplication()
+ {
+ <span class="code-comment">// Shut down the felix framework when stopping the
+</span> <span class="code-comment">// host application.
+</span> m_felix.stop();
+ m_felix.waitForStop();
+ }
+}
+</pre>
+</div></div>
+
+<p>Notice how the <tt>HostApplication.getInstalledBundles()</tt> method
+uses its activator instance to get access to the System Bundle's
+context in order to interact with the embedded Felix framework
+instance. This approach provides the foundation for all interaction
+between the host application and the embedded framework instance.</p>
+
+<p><a name="ApacheFelixFrameworkLaunchingandEmbedding-hostservices"></a></p>
+
+<h2><a name="ApacheFelixFrameworkLaunchingandEmbedding-ProvidingHostApplicationServices"></a>Providing Host Application Services</h2>
+
+<p>Providing services from the host application to bundles inside the
+embedded Felix framework instance follows the basic approach laid out
+in <a href="#ApacheFelixFrameworkLaunchingandEmbedding-hostinteraction">above</a>.
+The main complication for providing a host application service to
+bundles is the fact that both the host application and the bundles must
+be using the same class definitions for the service interface classes.
+Since the host application cannot import classes from a bundle, this
+means that the service interface classes <b>must</b> be accessible on
+the class path, typically as part of the host application itself. The
+host application then must export the service interface package via the
+system bundle so that bundles installed into the embedded framework
+instance can import it. This is achieved using the <tt>org.osgi.framework.system.packages.extra</tt> configuration property previously presented.</p>
+
+<p>Consider the follow simple property lookup service:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">package</span> host.service.lookup;
+
+<span class="code-keyword">public</span> class Lookup
+{
+ <span class="code-keyword">public</span> <span class="code-object">Object</span> lookup(<span class="code-object">String</span> name);
+}
+</pre>
+</div></div>
+
+<p>This package is simply part of the host application, which is potentially packaged into a JAR file and started with the "<tt>java -jar</tt>"
+command. Now consider the following host application bundle activator,
+which will be used to register/unregister the property lookup service
+when the embedded framework instance starts/stops:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">package</span> host.core;
+
+<span class="code-keyword">import</span> java.util.Map;
+<span class="code-keyword">import</span> org.osgi.framework.BundleActivator;
+<span class="code-keyword">import</span> org.osgi.framework.BundleContext;
+<span class="code-keyword">import</span> org.osgi.framework.ServiceRegistration;
+<span class="code-keyword">import</span> host.service.lookup;
+
+<span class="code-keyword">public</span> class HostActivator <span class="code-keyword">implements</span> BundleActivator
+{
+ <span class="code-keyword">private</span> Map m_lookupMap = <span class="code-keyword">null</span>;
+ <span class="code-keyword">private</span> BundleContext m_context = <span class="code-keyword">null</span>;
+ <span class="code-keyword">private</span> ServiceRegistration m_registration = <span class="code-keyword">null</span>;
+
+ <span class="code-keyword">public</span> HostActivator(Map lookupMap)
+ {
+ <span class="code-comment">// Save a reference to the service's backing store.
+</span> m_lookupMap = lookupMap;
+ }
+
+ <span class="code-keyword">public</span> void start(BundleContext context)
+ {
+ <span class="code-comment">// Save a reference to the bundle context.
+</span> m_context = context;
+ <span class="code-comment">// Create a property lookup service implementation.
+</span> Lookup lookup = <span class="code-keyword">new</span> Lookup() {
+ <span class="code-keyword">public</span> <span class="code-object">Object</span> lookup(<span class="code-object">String</span> name)
+ {
+ <span class="code-keyword">return</span> m_lookupMap.get(name);
+ }
+ };
+ <span class="code-comment">// Register the property lookup service and save
+</span> <span class="code-comment">// the service registration.
+</span> m_registration = m_context.registerService(
+ Lookup.class.getName(), lookup, <span class="code-keyword">null</span>);
+ }
+
+ <span class="code-keyword">public</span> void stop(BundleContext context)
+ {
+ <span class="code-comment">// Unregister the property lookup service.
+</span> m_registration.unregister();
+ m_context = <span class="code-keyword">null</span>;
+ }
+}
+</pre>
+</div></div>
+
+<p>Given the above host application bundle activator, the following
+code snippet shows how the host application could create an embedded
+version of the Felix framework and provide the property lookup service
+to installed bundles:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">package</span> host.core;
+
+<span class="code-keyword">import</span> java.util.List;
+<span class="code-keyword">import</span> java.util.ArrayList;
+<span class="code-keyword">import</span> java.util.Map;
+<span class="code-keyword">import</span> java.util.HashMap;
+<span class="code-keyword">import</span> host.service.lookup.Lookup;
+<span class="code-keyword">import</span> org.apache.felix.framework.Felix;
+<span class="code-keyword">import</span> org.apache.felix.framework.util.FelixConstants;
+<span class="code-keyword">import</span> org.osgi.framework.Constants;
+
+<span class="code-keyword">public</span> class HostApplication
+{
+ <span class="code-keyword">private</span> HostActivator m_activator = <span class="code-keyword">null</span>;
+ <span class="code-keyword">private</span> Felix m_felix = <span class="code-keyword">null</span>;
+ <span class="code-keyword">private</span> Map m_lookupMap = <span class="code-keyword">new</span> HashMap();
+
+ <span class="code-keyword">public</span> HostApplication()
+ {
+ <span class="code-comment">// Initialize the map <span class="code-keyword">for</span> the property lookup service.
+</span> m_lookupMap.put(<span class="code-quote">"name1"</span>, <span class="code-quote">"value1"</span>);
+
+ m_lookupMap.put(<span class="code-quote">"name2"</span>, <span class="code-quote">"value2"</span>);
+ m_lookupMap.put(<span class="code-quote">"name3"</span>, <span class="code-quote">"value3"</span>);
+ m_lookupMap.put(<span class="code-quote">"name4"</span>, <span class="code-quote">"value4"</span>);
+
+ <span class="code-comment">// Create a configuration property map.
+</span> Map configMap = <span class="code-keyword">new</span> HashMap();
+ <span class="code-comment">// Export the host provided service <span class="code-keyword">interface</span> <span class="code-keyword">package</span>.
+</span> configMap.put(Constants.FRAMEWORK_SYSTEMPACKAGES_EXTRA,
+ <span class="code-quote">"host.service.lookup; version=1.0.0"</span>);
+ <span class="code-comment">// Create host activator;
+</span> m_activator = <span class="code-keyword">new</span> HostActivator(m_lookupMap);
+ List list = <span class="code-keyword">new</span> ArrayList();
+ list.add(m_activator);
+ configMap.put(FelixConstants.SYSTEMBUNDLE_ACTIVATORS_PROP, list);
+
+ <span class="code-keyword">try</span>
+ {
+ <span class="code-comment">// Now create an instance of the framework with
+</span> <span class="code-comment">// our configuration properties.
+</span> m_felix = <span class="code-keyword">new</span> Felix(configMap);
+ <span class="code-comment">// Now start Felix instance.
+</span> m_felix.start();
+ }
+ <span class="code-keyword">catch</span> (Exception ex)
+ {
+ <span class="code-object">System</span>.err.println(<span class="code-quote">"Could not create framework: "</span> + ex);
+ ex.printStackTrace();
+ }
+ }
+
+ <span class="code-keyword">public</span> void shutdownApplication()
+ {
+ <span class="code-comment">// Shut down the felix framework when stopping the
+</span> <span class="code-comment">// host application.
+</span> m_felix.stop();
+ m_felix.waitForStop();
+ }
+}
+</pre>
+</div></div>
+
+<p>Rather than having the host application bundle activator register
+the service, it is also possible for the the host application to simply
+get the bundle context from the bundle activator and register the
+service directly, but the presented approach is perhaps a little
+cleaner since it allows the host application to register/unregister the
+service when the system bundle starts/stops.</p>
+
+<p><a name="ApacheFelixFrameworkLaunchingandEmbedding-hostserviceusage"></a></p>
+
+<h2><a name="ApacheFelixFrameworkLaunchingandEmbedding-UsingServicesProvidedbyBundles"></a>Using Services Provided by Bundles</h2>
+
+<p>Using services provided by bundles follows the same general approach
+of using a host application bundle activator. The main complication for
+the host application using a service from a bundle is the fact that
+both the host application and the bundle must be using the same class
+definitions for the service interface classes. Since the host
+application cannot import classes from a bundle, this means that the
+service interface classes <b>must</b> be accessible on the class path,
+typically as part of the host application itself. The host application
+then must export the service interface package via the system bundle so
+that bundles installed into the embedded framework instance can import
+it. This is achieved using the <tt>org.osgi.framework.system.packages.extra</tt> configuration property previously presented.</p>
+
+<p>Consider the following simple command service interface for which
+bundles provide implementations, such as might be used to create an
+extensible interactive shell:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">package</span> host.service.command;
+
+<span class="code-keyword">public</span> class 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> getDescription();
+ <span class="code-keyword">public</span> <span class="code-object">boolean</span> execute(<span class="code-object">String</span> commandline);
+}
+</pre>
+</div></div>
+
+<p>This package is simply part of the host application, which is potentially packaged into a JAR file and started with the "<tt>java -jar</tt>"
+command. Now consider the previously introduced host application bundle
+activator below, which simply provides access to the system bundle
+context:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">package</span> host.core;
+
+<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 HostActivator <span class="code-keyword">implements</span> BundleActivator
+{
+ <span class="code-keyword">private</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-keyword">public</span> void stop(BundleContext context)
+ {
+ m_context = <span class="code-keyword">null</span>;
+ }
+
+ <span class="code-keyword">public</span> BundleContext getContext()
+ {
+ <span class="code-keyword">return</span> m_context;
+ }
+}
+</pre>
+</div></div>
+
+<p>With this bundle activator, the host application can use command
+services provided by bundles installed inside its embedded Felix
+framework instance. The following code snippet illustrates one possible
+approach:</p>
+
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<pre class="code-java"><span class="code-keyword">package</span> host.core;
+
+<span class="code-keyword">import</span> java.util.List;
+<span class="code-keyword">import</span> java.util.ArrayList;
+<span class="code-keyword">import</span> java.util.Map;
+<span class="code-keyword">import</span> host.service.command.Command;
+<span class="code-keyword">import</span> org.apache.felix.framework.Felix;
+<span class="code-keyword">import</span> org.apache.felix.framework.util.FelixConstants;
+<span class="code-keyword">import</span> org.apache.felix.framework.cache.BundleCache;
+<span class="code-keyword">import</span> org.osgi.framework.Constants;
+<span class="code-keyword">import</span> org.osgi.util.tracker.ServiceTracker;
+
+<span class="code-keyword">public</span> class HostApplication
+{
+ <span class="code-keyword">private</span> HostActivator m_activator = <span class="code-keyword">null</span>;
+ <span class="code-keyword">private</span> Felix m_felix = <span class="code-keyword">null</span>;
+ <span class="code-keyword">private</span> ServiceTracker m_tracker = <span class="code-keyword">null</span>;
+
+ <span class="code-keyword">public</span> HostApplication()
+ {
+ <span class="code-comment">// Create a configuration property map.
+</span> Map configMap = <span class="code-keyword">new</span> HashMap();
+ <span class="code-comment">// Export the host provided service <span class="code-keyword">interface</span> <span class="code-keyword">package</span>.
+</span> configMap.put(Constants.FRAMEWORK_SYSTEMPACKAGES_EXTRA,
+ <span class="code-quote">"host.service.command; version=1.0.0"</span>);
+ <span class="code-comment">// Create host activator;
+</span> m_activator = <span class="code-keyword">new</span> HostActivator();
+ List list = <span class="code-keyword">new</span> ArrayList();
+ list.add(m_activator);
+ configMap.put(FelixConstants.SYSTEMBUNDLE_ACTIVATORS_PROP, list);
+
+ <span class="code-keyword">try</span>
+ {
+ <span class="code-comment">// Now create an instance of the framework with
+</span> <span class="code-comment">// our configuration properties.
+</span> m_felix = <span class="code-keyword">new</span> Felix(configMap);
+ <span class="code-comment">// Now start Felix instance.
+</span> m_felix.start();
+ }
+ <span class="code-keyword">catch</span> (Exception ex)
+ {
+ <span class="code-object">System</span>.err.println(<span class="code-quote">"Could not create framework: "</span> + ex);
+ ex.printStackTrace();
+ }
+
+ m_tracker = <span class="code-keyword">new</span> ServiceTracker(
+ m_activator.getContext(), Command.class.getName(), <span class="code-keyword">null</span>);
+ m_tracker.open();
+ }
+
+ <span class="code-keyword">public</span> <span class="code-object">boolean</span> execute(<span class="code-object">String</span> name, <span class="code-object">String</span> commandline)
+ {
+ <span class="code-comment">// See <span class="code-keyword">if</span> any of the currently tracked command services
+</span> <span class="code-comment">// match the specified command name, <span class="code-keyword">if</span> so then execute it.
+</span> <span class="code-object">Object</span>[] services = m_tracker.getServices();
+ <span class="code-keyword">for</span> (<span class="code-object">int</span> i = 0; (services != <span class="code-keyword">null</span>) && (i < services.length); i++)
+ {
+ <span class="code-keyword">try</span>
+ {
+ <span class="code-keyword">if</span> (((Command) services[i]).getName().equals(name))
+ {
+ <span class="code-keyword">return</span> ((Command) services[i]).execute(commandline);
+ }
+ }
+ <span class="code-keyword">catch</span> (Exception ex)
+ {
+ <span class="code-comment">// Since the services returned by the tracker could become
+</span> <span class="code-comment">// invalid at any moment, we will <span class="code-keyword">catch</span> all exceptions, log
+</span> <span class="code-comment">// a message, and then ignore faulty services.
+</span> <span class="code-object">System</span>.err.println(ex);
+ }
+ }
+ <span class="code-keyword">return</span> <span class="code-keyword">false</span>;
+ }
+
+ <span class="code-keyword">public</span> void shutdownApplication()
+ {
+ {
+ <span class="code-comment">// Shut down the felix framework when stopping the
+</span> <span class="code-comment">// host application.
+</span> m_felix.stop();
+ m_felix.waitForStop();
+ }
+}
+</pre>
+</div></div>
+
+<p>The above example is overly simplistic with respect to concurrency
+issues and error conditions, but it demonstrates the overall approach
+for using bundle-provided services from the host application.</p>
+
+<p><a name="ApacheFelixFrameworkLaunchingandEmbedding-servicereflection"></a></p>
+
+<h3><a name="ApacheFelixFrameworkLaunchingandEmbedding-UsingBundleServicesviaReflection"></a>Using Bundle Services via Reflection</h3>
+
+<p>It possible for the host application to use services provided by
+bundles without having access to the service interface classes and thus
+not needing to put the service interface classes on the class path. To
+do this, the host application uses the same general approach to acquire
+the system bundle context object, which it can use to look up service
+objects. Using either an LDAP filter or the service interface class
+name, the host application can retrieve the service object and then use
+standard Java reflection to invoke methods on the service object.</p>
+
+<p><a name="ApacheFelixFrameworkLaunchingandEmbedding-serviceother"></a></p>
+
+<h3><a name="ApacheFelixFrameworkLaunchingandEmbedding-OtherApproaches"></a>Other Approaches</h3>
+
+<p>The <a href="http://code.google.com/p/transloader/" rel="nofollow">Transloader</a> project is another attempt at dealing with issues of classes loaded from different class loaders and may be of interest.</p>
+
+<p><a name="ApacheFelixFrameworkLaunchingandEmbedding-caveat"></a></p>
+
+<h1><a name="ApacheFelixFrameworkLaunchingandEmbedding-Caveat"></a>Caveat</h1>
+
+<p>The code in this document has not been thoroughly tested nor even
+compiled and may be out of date with respect to the current Felix
+source code. If you find errors please report them so the that they can
+be corrected.</p>
+
+<p><a name="ApacheFelixFrameworkLaunchingandEmbedding-feedback"></a></p>
+
+<h2><a name="ApacheFelixFrameworkLaunchingandEmbedding-Feedback"></a>Feedback</h2>
+
+<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>
+ </div>
+ </body></html>
diff --git a/main.distribution/doc/apache-felix-framework-launching-and-embedding_files/apache.png b/main.distribution/doc/apache-felix-framework-launching-and-embedding_files/apache.png
new file mode 100644
index 0000000..5132f65
--- /dev/null
+++ b/main.distribution/doc/apache-felix-framework-launching-and-embedding_files/apache.png
Binary files differ
diff --git a/main.distribution/doc/apache-felix-framework-launching-and-embedding_files/button.html b/main.distribution/doc/apache-felix-framework-launching-and-embedding_files/button.html
new file mode 100644
index 0000000..1a464ef
--- /dev/null
+++ b/main.distribution/doc/apache-felix-framework-launching-and-embedding_files/button.html
@@ -0,0 +1,5 @@
+<html><head>
+<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1"><!-- ads start -->
+</head><body><a href="http://www.us.apachecon.com/c/acus2009/" target="_blank"><img src="button_data/2009-usa-125x125.png" title="ApacheCon US 2009" border="0" height="125" width="125"></a>
+<!-- ads end -->
+</body></html>
\ No newline at end of file
diff --git a/main.distribution/doc/apache-felix-framework-launching-and-embedding_files/button_data/2008-usa-125x125.png b/main.distribution/doc/apache-felix-framework-launching-and-embedding_files/button_data/2008-usa-125x125.png
new file mode 100644
index 0000000..37cca05
--- /dev/null
+++ b/main.distribution/doc/apache-felix-framework-launching-and-embedding_files/button_data/2008-usa-125x125.png
Binary files differ
diff --git a/main.distribution/doc/apache-felix-framework-launching-and-embedding_files/button_data/2009-europe-125x125.png b/main.distribution/doc/apache-felix-framework-launching-and-embedding_files/button_data/2009-europe-125x125.png
new file mode 100644
index 0000000..654a99c
--- /dev/null
+++ b/main.distribution/doc/apache-felix-framework-launching-and-embedding_files/button_data/2009-europe-125x125.png
Binary files differ
diff --git a/main.distribution/doc/apache-felix-framework-launching-and-embedding_files/button_data/2009-usa-125x125.png b/main.distribution/doc/apache-felix-framework-launching-and-embedding_files/button_data/2009-usa-125x125.png
new file mode 100644
index 0000000..117c695
--- /dev/null
+++ b/main.distribution/doc/apache-felix-framework-launching-and-embedding_files/button_data/2009-usa-125x125.png
Binary files differ
diff --git a/main.distribution/doc/apache-felix-framework-launching-and-embedding_files/forbidden.gif b/main.distribution/doc/apache-felix-framework-launching-and-embedding_files/forbidden.gif
new file mode 100644
index 0000000..c6acdec
--- /dev/null
+++ b/main.distribution/doc/apache-felix-framework-launching-and-embedding_files/forbidden.gif
Binary files differ
diff --git a/main.distribution/doc/apache-felix-framework-launching-and-embedding_files/linkext7.gif b/main.distribution/doc/apache-felix-framework-launching-and-embedding_files/linkext7.gif
new file mode 100644
index 0000000..f2dd2dc
--- /dev/null
+++ b/main.distribution/doc/apache-felix-framework-launching-and-embedding_files/linkext7.gif
Binary files differ
diff --git a/main.distribution/doc/apache-felix-framework-launching-and-embedding_files/logo.png b/main.distribution/doc/apache-felix-framework-launching-and-embedding_files/logo.png
new file mode 100644
index 0000000..dccbddc
--- /dev/null
+++ b/main.distribution/doc/apache-felix-framework-launching-and-embedding_files/logo.png
Binary files differ
diff --git a/main.distribution/doc/apache-felix-framework-launching-and-embedding_files/mail_small.gif b/main.distribution/doc/apache-felix-framework-launching-and-embedding_files/mail_small.gif
new file mode 100644
index 0000000..a3b7d9f
--- /dev/null
+++ b/main.distribution/doc/apache-felix-framework-launching-and-embedding_files/mail_small.gif
Binary files differ
diff --git a/main.distribution/doc/apache-felix-framework-launching-and-embedding_files/site.css b/main.distribution/doc/apache-felix-framework-launching-and-embedding_files/site.css
new file mode 100644
index 0000000..959ab0a
--- /dev/null
+++ b/main.distribution/doc/apache-felix-framework-launching-and-embedding_files/site.css
@@ -0,0 +1,25 @@
+/* @override http://felix.apache.org/site/media.data/site.css */
+
+body { background-color: #ffffff; color: #3b3b3b; font-family: Tahoma, Arial, sans-serif; font-size: 10pt; line-height: 140% }
+h1, h2, h3, h4, h5, h6 { font-weight: normal; color: #000000; line-height: 100%; margin-top: 0px}
+h1 { font-size: 200% }
+h2 { font-size: 175% }
+h3 { font-size: 150% }
+h4 { font-size: 140% }
+h5 { font-size: 130% }
+h6 { font-size: 120% }
+a { color: #1980af }
+a:visited { color: #1980af }
+a:hover { color: #1faae9 }
+.title { position: absolute; left: 1px; right: 1px; top:25px; height: 81px; background: url(http://felix.apache.org/site/media.data/gradient.png) repeat-x; background-position: bottom; }
+.logo { position: absolute; width: 15em; height: 81px; text-align: center; }
+.header { text-align: right; margin-right: 20pt; margin-top: 30pt;}
+.menu { border-top: 10px solid #f9bb00; position: absolute; top: 107px; left: 1px; width: 15em; bottom: 0px; padding: 0px; background-color: #fcfcfc }
+.menu ul { background-color: #fdf5d9; list-style: none; padding-left: 4em; margin-top: 0px; padding-top: 2em; padding-bottom: 2em; margin-left: 0px; color: #4a4a43}
+.menu a { text-decoration: none; color: #4a4a43 }
+.main { position: absolute; border-top: 10px solid #cde0ea; top: 107px; left: 15em; right: 1px; margin-left: 2px; padding-right: 4em; padding-left: 1em; padding-top: 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
diff --git a/main.distribution/doc/apache-felix-framework-usage-documentation.html b/main.distribution/doc/apache-felix-framework-usage-documentation.html
new file mode 100644
index 0000000..b3b725c
--- /dev/null
+++ b/main.distribution/doc/apache-felix-framework-usage-documentation.html
@@ -0,0 +1,399 @@
+<!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 - Apache Felix Framework Usage Documentation</title>
+ <link rel="stylesheet" href="apache-felix-framework-usage-documentation_files/site.css" type="text/css" media="all">
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ </head><body>
+ <div class="title"><div class="logo"><a href="http://felix.apache.org/site/index.html"><img alt="Apache Felix" src="apache-felix-framework-usage-documentation_files/logo.png" border="0"></a></div><div class="header"><a href="http://www.apache.org/"><img alt="Apache" src="apache-felix-framework-usage-documentation_files/apache.png" border="0"></a></div></div>
+ <div class="menu">
+<ul>
+ <li><a href="http://felix.apache.org/site/news.html" title="news">news</a></li>
+ <li><a href="http://felix.apache.org/site/license.html" title="license">license</a></li>
+ <li><a href="http://felix.apache.org/site/downloads.cgi" rel="nofollow">downloads</a></li>
+ <li><a href="http://felix.apache.org/site/documentation.html" title="documentation">documentation</a></li>
+ <li><a href="http://felix.apache.org/site/mailinglists.html" title="mailinglists">mailing lists</a></li>
+ <li><a href="http://felix.apache.org/site/contributing.html" title="Contributing">contributing</a></li>
+ <li><a href="http://www.apache.org/" rel="nofollow">asf</a></li>
+ <li><a href="http://www.apache.org/foundation/sponsorship.html" rel="nofollow">sponsorship</a></li>
+ <li><a href="http://www.apache.org/foundation/thanks.html" rel="nofollow">sponsors</a>
+<!-- ApacheCon Ad -->
+<iframe src="apache-felix-framework-usage-documentation_files/button.html" style="border-width: 0pt; float: left;" frameborder="0" height="135" scrolling="no" width="135"></iframe>
+<p style="height: 100px;">
+<!-- ApacheCon Ad -->
+</p></li></ul> </div>
+ <div class="main">
+<h1><a name="ApacheFelixFrameworkUsageDocumentation-ApacheFelixFrameworkUsageDocumentation"></a>Apache Felix Framework Usage Documentation</h1>
+
+<ul>
+ <li><a href="#ApacheFelixFrameworkUsageDocumentation-downloadingframework">Downloading the Framework</a></li>
+ <li><a href="#ApacheFelixFrameworkUsageDocumentation-startingframework">Starting the Framework</a></li>
+ <li><a href="#ApacheFelixFrameworkUsageDocumentation-frameworkshell">Framework Shell</a>
+ <ul>
+ <li><a href="#ApacheFelixFrameworkUsageDocumentation-installingbundles">Installing Bundles</a></li>
+ <li><a href="#ApacheFelixFrameworkUsageDocumentation-installingbundlesproxies">Web Proxy Issues when Installing Bundles</a></li>
+ </ul>
+ </li>
+ <li><a href="#ApacheFelixFrameworkUsageDocumentation-autodeploy">Bundle Auto-Deploy</a></li>
+ <li><a href="#ApacheFelixFrameworkUsageDocumentation-configuringframework">Configuring the Framework</a>
+ <ul>
+ <li><a href="#ApacheFelixFrameworkUsageDocumentation-migrating">Migrating from Earlier Versions</a></li>
+ <li><a href="#ApacheFelixFrameworkUsageDocumentation-propertysubstitution">System Property Substitution</a></li>
+ </ul>
+ </li>
+ <li><a href="#ApacheFelixFrameworkUsageDocumentation-configuringbundles">Configuring Bundles</a></li>
+ <li><a href="#ApacheFelixFrameworkUsageDocumentation-feedback">Feedback</a></li>
+</ul>
+
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-downloadingframework"></a></p>
+
+<h2><a name="ApacheFelixFrameworkUsageDocumentation-DownloadingtheFramework"></a>Downloading the Framework</h2>
+
+<p>Go to the <a href="http://felix.apache.org/site/downloads.html" title="downloads">downloads</a> page and download the latest Felix framework distribution.</p>
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-startingframework"></a></p>
+
+<h2><a name="ApacheFelixFrameworkUsageDocumentation-StartingtheFramework"></a>Starting the Framework</h2>
+
+<p>Start the framework from the installation directory by typing:</p>
+
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>java -jar bin/felix.jar
+</pre>
+</div></div>
+
+<p>The framework launcher starts the framework and installs a bundles contained in the <tt>bundle</tt>
+directory of the current directory. By default, the bundle directory
+contains a simple text-based shell to interact with the framework.
+Bundles installed into the framework are copied into a bundle cache
+directory for subsequent executions. By default, the framework creates
+a cache directory, called <tt>felix-cache</tt>, in your current working directory; this behavior is configurable, see the <a href="http://felix.apache.org/site/apache-felix-framework-bundle-cache.html" title="Apache Felix Framework Bundle Cache">Apache Felix Framework Bundle Cache</a> document for more details.</p>
+
+<p>If you want to start the framework using a different bundle cache directory, you can do so like this:</p>
+
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>java -jar bin/felix.jar <cache-path>
+</pre>
+</div></div>
+
+<p>Where <tt><cache-path></tt> is the path you want to use as the
+bundle cache. If you specify a relative cache path, then it will be
+treated as relative to the current working directory.</p>
+
+<div class="panelMacro"><table class="infoMacro"><colgroup><col width="24"><col></colgroup><tbody><tr><td valign="top"><img src="apache-felix-framework-usage-documentation_files/information.gif" alt="" align="absmiddle" border="0" height="16" width="16"></td><td><b>Useful Information</b><br><p>Previous
+versions of the framework prompted for a profile name when executed.
+The profile name was used to create a directory inside <tt>.felix/</tt>
+in the user home directory. This approach allowed users to have
+different sets of bundles for different purposes, e.g., testing,
+production, etc. If this behavior is still desired, it is very easy to
+mimic. Modify <tt>conf/config.properties</tt> to include "<tt>felix.cache.rootdir=${user.home}/.felix</tt>". Now, if you start Felix with something like "<tt>java -jar bin/felix.jar foo</tt>", it will use "<tt>${user.home}/.felix/foo/</tt>" as the bundle cache directory, where "<tt>${user.home</tt>}" is automatically substituted with the appropriate system property by the launcher.</p></td></tr></tbody></table></div>
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-frameworkshell"></a></p>
+
+<h2><a name="ApacheFelixFrameworkUsageDocumentation-FrameworkShell"></a>Framework Shell</h2>
+
+<p>The main way to interact with the framework is via its shell. Felix'
+shell is implemented as an OSGi service that, be default, uses a simple
+text-based user interface. After starting the framework, type <tt>help</tt> into the shell to see the list of the available commands and <tt>help <command-name></tt> to get help for a specific command.</p>
+
+<p>To install bundles, use the <tt>install</tt> command, which is described in more detail in the next <a href="#ApacheFelixFrameworkUsageDocumentation-installingbundles">sub-section</a>. To view all currently installed bundles, use the <tt>ps</tt> command. To stop the framework type <tt>stop 0</tt>
+to stop the System Bundle; any installed bundles will automatically be
+reloaded (and potentially restarted) the next time you launch with the
+associated cache.</p>
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-installingbundles"></a></p>
+
+<h3><a name="ApacheFelixFrameworkUsageDocumentation-InstallingBundles"></a>Installing Bundles</h3>
+
+<p>A bundle is the OSGi term for a component for the OSGi framework. A
+bundle is simply a JAR file containing a manifest and some combination
+of Java classes, embedded JAR files, native code, and resources. A
+bundle may provide some specific functionality for the user or it may
+implement a service that other bundles can use; bundles can only use
+functionality from other bundles through shared services and packages.</p>
+
+<p>The Felix framework is packaged with three bundles, which are located in the <tt>bundle/</tt>
+directory of the framework installation directory. There are bundles
+for the Felix shell service, a text-based shell service user interface,
+and a bundle repository service. In addition to these bundles, the
+bundle repository services provides access to other bundles for easy
+installation. The bundle repository service provides a shell command,
+named <tt>obr</tt>, to access available bundles; refer to the <a href="http://felix.apache.org/site/apache-felix-osgi-bundle-repository.html" title="Apache Felix OSGi Bundle Repository">Apache Felix OSGi Bundle Repository</a> for more information.</p>
+
+<p>Before installing any bundles, it is important to understand how
+bundles are manually deployed into the framework. Bundles are deployed
+in two stages; first they are installed, then they are started. To
+install a bundle use the <tt>install</tt> shell command followed by a bundle URL. For example, to install a <tt>bundle.jar</tt> bundle you type (assuming you have started Felix from its installation directory):</p>
+
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>install file:/path/to/bundle/bundle.jar
+</pre>
+</div></div>
+
+<p>Once a bundle is installed, it can then be started by using the <tt>start</tt> command and the bundle identifier of the desired bundle. The <tt>ps</tt>
+shell command is used to list all installed bundles and to obtain the
+bundle's identifier. The following Felix shell session capture
+illustrates how to start the <tt>bundle.jar</tt> bundle:</p>
+
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>-> install [file:bundle/simple]
+-> ps
+START LEVEL 1
+ ID State Level Name
+[ 0] [Active ] [ 0] System Bundle (2.0.0)
+[ 1] [Active ] [ 1] Shell Service (1.4.0)
+[ 2] [Active ] [ 1] Shell TUI (1.4.0)
+[ 3] [Active ] [ 1] Bundle Repository (1.4.0)
+[ 4] [Installed ] [ 1] Bundle Example (1.0.0)
+-> start 4
+Hello from Bundle 4.
+->
+</pre>
+</div></div>
+
+<p>The <tt>stop</tt> command is used to stop a bundle and the <tt>uninstall</tt> command is used to remove a bundle from the bundle cache. As an alternative to using the <tt>install</tt> and <tt>start</tt> commands explicitly, it is also possible to install and start a bundle in one step by using the <tt>start</tt> command with a bundle URL.</p>
+
+<p>Bundles can be updated using the <tt>update</tt> command. The update
+command allows you to specify an URL from which to retrieve the updated
+bundle, but if one is not specified it will try to update the bundle
+from the bundle's <tt>Bundle-UpdateLocation</tt> manifest attribute, if present, or the bundle's original location URL.</p>
+
+<p><b>Important:</b> When you <tt>update</tt> or <tt>uninstall</tt> a
+bundle, the changes appear to take effect immediately, but in reality
+the changes are only partially enacted. If a bundle is updated or
+uninstalled and it was exporting packages, these packages are not
+removed until the framework is refreshed using the <tt>PackageAdmin</tt> service. The Felix shell offers a convenient <tt>refresh</tt> command for this purpose.</p>
+
+<p>For an introduction to writing bundles and services, refer to the Felix bundle tutorial.</p>
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-installingbundlesproxies"></a></p>
+
+<h3><a name="ApacheFelixFrameworkUsageDocumentation-WebProxyIssueswhenInstallingBundles"></a>Web Proxy Issues when Installing Bundles</h3>
+
+<p>If you use a proxy for Web access, then you may run into difficulty
+using the Felix shell to install bundles from a remote URL. To remedy
+this situation, certain system properties must be set to make Felix
+work with your proxy. These properties are:</p>
+
+<ul>
+ <li><tt>http.proxyHost</tt> - the name of the proxy host.</li>
+ <li><tt>http.proxyPort</tt> - the port of the proxy host.</li>
+ <li><tt>http.proxyAuth</tt>
+- 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.,
+<tt>rickhall:mypassword</tt>).</li>
+</ul>
+
+
+<p>These system properties can be set directly on the command line when starting the JVM using the standard "<tt>-D<prop>=<value></tt>" syntax or you can put them in the <tt>lib/system.properties</tt> file of your Felix installation; see the next section on <a href="#ApacheFelixFrameworkUsageDocumentation-configuringframework">configuring Felix</a> for more information.</p>
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-autodeploy"></a></p>
+
+<h2><a name="ApacheFelixFrameworkUsageDocumentation-BundleAutoDeploy"></a>Bundle Auto-Deploy</h2>
+
+<p>To minimize the amount of configuration necessary to install bundles
+when you launch the framework, the Felix launcher uses the concept of
+an "auto-deploy" directory. The Felix launcher deploys all bundles in
+the auto-deploy directory into the framework instance during startup.
+By default, the auto-deploy directory is "<tt>bundle</tt>" in the current directory, but it can be specified on the command line like this:</p>
+
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>java -jar bin/felix.jar -b /path/to/dir
+</pre>
+</div></div>
+
+<p>Specifying an auto-deploy directory replaces the default directory,
+it does not augment it. The default deployment actions performed on the
+bundles in the auto-deploy directory are: install, update, and start.
+Both the location of the auto-deploy directory and the deployment
+actions performed can be controlled by the following configuration
+properties, respectively:</p>
+
+<ul>
+ <li><tt>felix.auto.deploy.dir</tt> - Specifies the auto-deploy directory from which bundles are automatically deploy at framework startup. The default is the <tt>bundle/</tt> directory of the current directory.</li>
+ <li><tt>felix.auto.deploy.action</tt>
+- Specifies the auto-deploy actions to be found on bundle JAR files
+found in the auto-deploy directory. The possible actions are <tt>install</tt>, <tt>update</tt>, <tt>start</tt>, and <tt>uninstall</tt>.
+If no actions are specified, then the auto-deploy directory is not
+processed. There is no default value for this property, but the default
+<tt>config.properties</tt> file installed with the Felix framework sets the value to <tt>install</tt>, <tt>update</tt>, and <tt>start</tt>.</li>
+</ul>
+
+
+<p>The next section describes how to set and use configuration properties.</p>
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-configuringframework"></a></p>
+
+<h2><a name="ApacheFelixFrameworkUsageDocumentation-ConfiguringtheFramework"></a>Configuring the Framework</h2>
+
+<p>Both the Felix framework and the launcher use configuration
+properties to alter their default behavior. The framework can only be
+configured by passing properties into its constructor, but the launcher
+provides a mechanism to configure the framework via a property file.
+The launcher The Felix framework uses properties to configure certain
+aspects of its behavior. The framework launcher reads configuration
+properties from <tt>conf/config.properties</tt>. This file uses standard Java property file syntax.</p>
+
+<p>The launcher also supports setting system properties via the <tt>conf/system.properties</tt>
+file. This file is purely for convenience when you need to repeatedly
+set system properties when running the framework. While the framework
+itself does not look at system properties, the launcher does copy any
+framework configuration properties found in the system properties into
+the framework configuration map, also for your convenience.</p>
+
+<p>It is possible to specify a different locations for these property files for the system properties file by using the <tt>felix.config.properties</tt> and <tt>felix.system.properties</tt> system properties when executing the framework. For example:</p>
+
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>java -Dfelix.config.properties=file:/home/rickhall/config.properties -jar bin/felix.jar
+</pre>
+</div></div>
+
+<p>Configuration and system properties are accessible at run time via <tt>BundleContext.getProperty()</tt>, but configuration properties override system properties.</p>
+
+<p>The following configuration properties are specifically for the launcher:</p>
+
+<ul>
+ <li><tt>felix.auto.deploy.dir</tt> - Specifies the auto-deploy directory from which bundles are automatically deploy at framework startup. The default is the <tt>bundle/</tt> directory of the current directory.</li>
+ <li><tt>felix.auto.deploy.action</tt>
+- Specifies the auto-deploy actions to be found on bundle JAR files
+found in the auto-deploy directory. The possible actions are <tt>install</tt>, <tt>update</tt>, <tt>start</tt>, and <tt>uninstall</tt>. An undefined or blank value is equivalent to disabling auto-deploy processing.</li>
+ <li><tt>felix.auto.install.<n></tt> - Space-delimited list of bundle URLs to automatically install when Felix is started, where <tt><n></tt> is the start level into which the bundle will be installed (e.g., <tt>felix.auto.install.2</tt>).</li>
+ <li><tt>felix.auto.start.<n></tt> - Space-delimited list of bundle URLs to automatically install and start when Felix is started, where <tt><n></tt> is the start level into which the bundle will be installed (e.g., <tt>felix.auto.start.2</tt>).</li>
+ <li><tt>felix.shutdown.hook</tt>
+- Specifies whether the launcher should install a shutdown hook to
+cleanly shutdown the framework on process exit. The default value is <tt>true</tt>.</li>
+</ul>
+
+
+<p>The following configuration properties are specifically for the framework (properties starting with "<tt>felix</tt>" are specific to Felix, while those starting with "<tt>org.osgi</tt>" are standard OSGi properties):</p>
+
+<ul>
+ <li><tt>org.osgi.framework.storage</tt> - Sets the directory to use as the bundle cache; by default bundle cache directory is <tt>felix-cache</tt>
+in the current working directory. The value should be a valid directory
+name. The directory name can be either absolute or relative. Relative
+directory names are relative to the current working directory. The
+specified directory will be created if it does not exist.</li>
+ <li><tt>felix.cache.rootdir</tt> - Sets the root directory to use to calculate the bundle cache directory for relative directory names. If <tt>org.osgi.framework.storage</tt>
+is set to a relative name, by default it is relative to the current
+working directory. If this property is set, then it will be calculated
+as being relative to the specified root directory.</li>
+ <li><tt>org.osgi.framework.storage.clean</tt> - Determines whether the bundle cache is flushed. The value can either be "<tt>none</tt>" or "<tt>onFirstInit</tt>", where "<tt>none</tt>" does not flush the bundle cache and "<tt>onFirstInit</tt>" flushes the bundle cache when the framework instance is first initialized. The default value is "<tt>none</tt>".</li>
+ <li><tt>felix.cache.bufsize</tt>
+- Sets the buffer size to be used by the cache; the default value is
+4096. The integer value of this string provides control over the size
+of the internal buffer of the disk cache for performance reasons.</li>
+ <li><tt>org.osgi.framework.system.packages</tt>
+- Specifies a comma-delimited list of packages that should be exported
+via the System Bundle from the parent class loader. The framework will
+set this to a reasonable default. If the value is specified, it
+replaces any default value.</li>
+ <li><tt>org.osgi.framework.system.packages.extra</tt>
+- Specifies a comma-delimited list of packages that should be exported
+via the System Bundle from the parent class loader in addition to the
+packages in <tt>org.osgi.framework.system.packages</tt>. The default value is empty. If a value is specified, it is appended to the list of default or specified packages in <tt>org.osgi.framework.system.packages</tt>.</li>
+ <li><tt>org.osgi.framework.bootdelegation</tt>
+- Specifies a comma-delimited list of packages that should be made
+implicitly available to all bundles from the parent class loader. It is
+recommended not to use this property since it breaks modularity. The
+default value is empty.</li>
+ <li><tt>felix.bootdelegation.implicit</tt>
+- Specifies whether the framework should try to guess when to
+implicitly boot delegate to ease integration with external code. The
+default value is <tt>true</tt>.</li>
+ <li><tt>felix.systembundle.activators</tt> - A <tt>List</tt> of <tt>BundleActivator</tt>
+instances that are started/stopped when the System Bundle is
+started/stopped. The specified instances will receive the System
+Bundle's <tt>BundleContext</tt> when invoked. (This property cannot be
+set in the configuration file since it requires instances; it can only
+be passed into Felix' constructor directly.)</li>
+ <li><tt>felix.log.logger</tt> - An instance of <tt>Logger</tt>
+that the framework uses as its default logger. (This property cannot be
+set in the configuration file since it requires an instance; it can
+only be passed into Felix' constructor directly.)</li>
+ <li><tt>felix.log.level</tt>
+- An integer value indicating the degree of logging reported by the
+framework; the higher the value the more logging is reported. If zero
+('0') is specified, then logging is turned off completely. The log
+levels match those specified in the OSGi Log Service (i.e., 1 = error,
+2 = warning, 3 = information, and 4 = debug). The default value is 1.</li>
+ <li><tt>org.osgi.framework.startlevel.beginning</tt> - The initial start level of the framework once it starts execution; the default value is 1.</li>
+ <li><tt>felix.startlevel.bundle</tt> - The default start level for newly installed bundles; the default value is 1.</li>
+ <li><tt>felix.service.urlhandlers</tt> - Flag to indicate whether to activate the URL Handlers service for the framework instance; the default value is "<tt>true</tt>". Activating the URL Handlers service will result in the <tt>URL.setURLStreamHandlerFactory()</tt> and <tt>URLConnection.setContentHandlerFactory()</tt> being called.</li>
+ <li><tt>felix.fragment.validation</tt> - Determines if installing unsupported fragment bundles throws an exception or logs a warning. Possible values are "<tt>exception</tt>" or "<tt>warning</tt>". The default value is "<tt>exception</tt>".</li>
+</ul>
+
+
+<p>The Felix framework installation contains a default <tt>conf/config.properties</tt> file for automatically starting the shell-related bundles.</p>
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-migrating"></a></p>
+
+<h3><a name="ApacheFelixFrameworkUsageDocumentation-MigratingfromEarlierVersions"></a>Migrating from Earlier Versions</h3>
+
+<p>Apache Felix Framework <tt>1.4.0</tt> introduced some configuration property changes. This section describes the differences from older versions of the framework.</p>
+
+<ul>
+ <li><b>Removed</b>
+ <ul>
+ <li><tt>felix.embedded.execution</tt> - No longer needed, since the framework now never calls <tt>System.exit()</tt>; the creator of the framework is now always responsible for exiting the VM.</li>
+ <li><tt>felix.strict.osgi</tt> - No longer needed, since all non-specification features have been removed.</li>
+ <li><tt>felix.cache.dir</tt> - No longer needed, since Felix no longer uses bundle cache profiles for saving sets of bundles.</li>
+ <li><tt>felix.cache.profile</tt> - No longer needed, since Felix no longer uses bundle cache profiles for saving sets of bundles.</li>
+ </ul>
+ </li>
+ <li><b>Renamed</b>
+ <ul>
+ <li><tt>felix.cache.profiledir</tt> - The equivalent of this property is now named <tt>org.osgi.framework.storage</tt>.</li>
+ <li><tt>felix.startlevel.framework</tt> - The equivalent of this property is now named <tt>org.osgi.framework.startlevel.beginning</tt>.</li>
+ </ul>
+ </li>
+ <li><b>Introduced</b>
+ <ul>
+ <li><tt>org.osgi.framework.system.packages.extra</tt> - New property, as described above, added to align with standard framework API.</li>
+ <li><tt>org.osgi.framework.storage.clean</tt> - New property, as described above, added to align with standard framework API.</li>
+ <li><tt>felix.cache.rootdir</tt> - Introduced as a result of removing bundle profiles to help resolve relative bundle cache directories.</li>
+ <li><tt>felix.fragment.validation</tt> - Introduced to control fragment validation, since the default behavior introduced in <tt>1.2.0</tt> of throwing an exception for fragments using unsupported features was causing issues for some users.</li>
+ </ul>
+ </li>
+</ul>
+
+
+<p>For the most part, these changes are minor and previous behavior
+achieved from older configuration properties is either easily attained
+with the new properties or no longer necessary.</p>
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-propertysubstitution"></a></p>
+
+<h3><a name="ApacheFelixFrameworkUsageDocumentation-SystemPropertySubstituion"></a>System Property Substituion</h3>
+
+<p>It is possible to use system properties to specify the values of properties in the <tt>conf/config.properties</tt> file. This is achieved through system property substitution, which is instigated by using <tt>${<property></tt>} syntax, where <tt><property></tt>
+is the name of a system property to substitute. When such a property
+value is retrieved by a bundle, the system property value will be
+substituted into the bundle property value as appropriate. It is
+possible to have nested system property substitution, in which case the
+inner-most property is substituted first, then the next inner most,
+until reaching the outer most.</p>
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-configuringbundles"></a></p>
+
+<h2><a name="ApacheFelixFrameworkUsageDocumentation-ConfiguringBundles"></a>Configuring Bundles</h2>
+
+<p>Some bundles use properties to configure certain aspects of their behavior. As an example, the default URL for the <tt>cd</tt> command of the shell service can be specified using the property <tt>felix.shell.baseurl</tt>.
+It is a good idea, when implementing bundles, to parameterize them with
+properties where appropriate. To learn about the configuration options
+for specific bundles, refer to the documentation that accompanies them.</p>
+
+<p>Bundle properties are also defined in the <tt>conf/config.properties</tt> property file. Any property placed in this file will be accessible via <tt>BundleContext.getProperty()</tt>
+at run time. The property file uses the standard Java property file
+syntax (i.e., attribute-value pairs). For information on changing the
+default location of this file, refer to the section on <a href="#ApacheFelixFrameworkUsageDocumentation-configuringframework">configuring Felix</a>.</p>
+
+<p><a name="ApacheFelixFrameworkUsageDocumentation-feedback"></a></p>
+
+<h2><a name="ApacheFelixFrameworkUsageDocumentation-Feedback"></a>Feedback</h2>
+
+<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>
+ </div>
+ </body></html>
diff --git a/main.distribution/doc/apache-felix-framework-usage-documentation_files/apache.png b/main.distribution/doc/apache-felix-framework-usage-documentation_files/apache.png
new file mode 100644
index 0000000..5132f65
--- /dev/null
+++ b/main.distribution/doc/apache-felix-framework-usage-documentation_files/apache.png
Binary files differ
diff --git a/main.distribution/doc/apache-felix-framework-usage-documentation_files/button.html b/main.distribution/doc/apache-felix-framework-usage-documentation_files/button.html
new file mode 100644
index 0000000..1a464ef
--- /dev/null
+++ b/main.distribution/doc/apache-felix-framework-usage-documentation_files/button.html
@@ -0,0 +1,5 @@
+<html><head>
+<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1"><!-- ads start -->
+</head><body><a href="http://www.us.apachecon.com/c/acus2009/" target="_blank"><img src="button_data/2009-usa-125x125.png" title="ApacheCon US 2009" border="0" height="125" width="125"></a>
+<!-- ads end -->
+</body></html>
\ No newline at end of file
diff --git a/main.distribution/doc/apache-felix-framework-usage-documentation_files/button_data/2008-usa-125x125.png b/main.distribution/doc/apache-felix-framework-usage-documentation_files/button_data/2008-usa-125x125.png
new file mode 100644
index 0000000..37cca05
--- /dev/null
+++ b/main.distribution/doc/apache-felix-framework-usage-documentation_files/button_data/2008-usa-125x125.png
Binary files differ
diff --git a/main.distribution/doc/apache-felix-framework-usage-documentation_files/button_data/2009-europe-125x125.png b/main.distribution/doc/apache-felix-framework-usage-documentation_files/button_data/2009-europe-125x125.png
new file mode 100644
index 0000000..654a99c
--- /dev/null
+++ b/main.distribution/doc/apache-felix-framework-usage-documentation_files/button_data/2009-europe-125x125.png
Binary files differ
diff --git a/main.distribution/doc/apache-felix-framework-usage-documentation_files/button_data/2009-usa-125x125.png b/main.distribution/doc/apache-felix-framework-usage-documentation_files/button_data/2009-usa-125x125.png
new file mode 100644
index 0000000..117c695
--- /dev/null
+++ b/main.distribution/doc/apache-felix-framework-usage-documentation_files/button_data/2009-usa-125x125.png
Binary files differ
diff --git a/main.distribution/doc/apache-felix-framework-usage-documentation_files/information.gif b/main.distribution/doc/apache-felix-framework-usage-documentation_files/information.gif
new file mode 100644
index 0000000..072ab66
--- /dev/null
+++ b/main.distribution/doc/apache-felix-framework-usage-documentation_files/information.gif
Binary files differ
diff --git a/main.distribution/doc/apache-felix-framework-usage-documentation_files/linkext7.gif b/main.distribution/doc/apache-felix-framework-usage-documentation_files/linkext7.gif
new file mode 100644
index 0000000..f2dd2dc
--- /dev/null
+++ b/main.distribution/doc/apache-felix-framework-usage-documentation_files/linkext7.gif
Binary files differ
diff --git a/main.distribution/doc/apache-felix-framework-usage-documentation_files/logo.png b/main.distribution/doc/apache-felix-framework-usage-documentation_files/logo.png
new file mode 100644
index 0000000..dccbddc
--- /dev/null
+++ b/main.distribution/doc/apache-felix-framework-usage-documentation_files/logo.png
Binary files differ
diff --git a/main.distribution/doc/apache-felix-framework-usage-documentation_files/mail_small.gif b/main.distribution/doc/apache-felix-framework-usage-documentation_files/mail_small.gif
new file mode 100644
index 0000000..a3b7d9f
--- /dev/null
+++ b/main.distribution/doc/apache-felix-framework-usage-documentation_files/mail_small.gif
Binary files differ
diff --git a/main.distribution/doc/apache-felix-framework-usage-documentation_files/site.css b/main.distribution/doc/apache-felix-framework-usage-documentation_files/site.css
new file mode 100644
index 0000000..959ab0a
--- /dev/null
+++ b/main.distribution/doc/apache-felix-framework-usage-documentation_files/site.css
@@ -0,0 +1,25 @@
+/* @override http://felix.apache.org/site/media.data/site.css */
+
+body { background-color: #ffffff; color: #3b3b3b; font-family: Tahoma, Arial, sans-serif; font-size: 10pt; line-height: 140% }
+h1, h2, h3, h4, h5, h6 { font-weight: normal; color: #000000; line-height: 100%; margin-top: 0px}
+h1 { font-size: 200% }
+h2 { font-size: 175% }
+h3 { font-size: 150% }
+h4 { font-size: 140% }
+h5 { font-size: 130% }
+h6 { font-size: 120% }
+a { color: #1980af }
+a:visited { color: #1980af }
+a:hover { color: #1faae9 }
+.title { position: absolute; left: 1px; right: 1px; top:25px; height: 81px; background: url(http://felix.apache.org/site/media.data/gradient.png) repeat-x; background-position: bottom; }
+.logo { position: absolute; width: 15em; height: 81px; text-align: center; }
+.header { text-align: right; margin-right: 20pt; margin-top: 30pt;}
+.menu { border-top: 10px solid #f9bb00; position: absolute; top: 107px; left: 1px; width: 15em; bottom: 0px; padding: 0px; background-color: #fcfcfc }
+.menu ul { background-color: #fdf5d9; list-style: none; padding-left: 4em; margin-top: 0px; padding-top: 2em; padding-bottom: 2em; margin-left: 0px; color: #4a4a43}
+.menu a { text-decoration: none; color: #4a4a43 }
+.main { position: absolute; border-top: 10px solid #cde0ea; top: 107px; left: 15em; right: 1px; margin-left: 2px; padding-right: 4em; padding-left: 1em; padding-top: 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
diff --git a/main.distribution/doc/apache-felix-osgi-bundle-repository.html b/main.distribution/doc/apache-felix-osgi-bundle-repository.html
new file mode 100644
index 0000000..825a9ff
--- /dev/null
+++ b/main.distribution/doc/apache-felix-osgi-bundle-repository.html
@@ -0,0 +1,524 @@
+<!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 - Apache Felix OSGi Bundle Repository</title>
+ <link rel="stylesheet" href="apache-felix-osgi-bundle-repository_files/site.css" type="text/css" media="all">
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ </head><body>
+ <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>
+ <div class="menu">
+<ul>
+ <li><a href="http://cwiki.apache.org/FELIX/news.html" title="news">news</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/license.html" title="license">license</a></li>
+ <li><a href="http://felix.apache.org/site/downloads.cgi" rel="nofollow">downloads</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/documentation.html" title="documentation">documentation</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/mailinglists.html" title="mailinglists">mailing lists</a></li>
+ <li><a href="http://cwiki.apache.org/FELIX/contributing.html" title="Contributing">contributing</a></li>
+ <li><a href="http://www.apache.org/" rel="nofollow">asf</a></li>
+ <li><a href="http://www.apache.org/foundation/sponsorship.html" rel="nofollow">sponsorship</a></li>
+ <li><a href="http://www.apache.org/foundation/thanks.html" rel="nofollow">sponsors</a>
+<!-- ApacheCon Ad -->
+<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>
+<p style="height: 100px;">
+<!-- ApacheCon Ad -->
+</p></li></ul> </div>
+ <div class="main">
+<h1><a name="ApacheFelixOSGiBundleRepository-ApacheFelixOSGiBundleRepository(OBR)"></a>Apache Felix OSGi Bundle Repository (OBR)</h1>
+
+<div>
+<ul>
+ <li><a href="#ApacheFelixOSGiBundleRepository-Motivation">Motivation</a></li>
+ <li><a href="#ApacheFelixOSGiBundleRepository-Overview">Overview</a></li>
+ <li><a href="#ApacheFelixOSGiBundleRepository-OBRRepositoryFile">OBR Repository File</a></li>
+ <li><a href="#ApacheFelixOSGiBundleRepository-OBRServiceAPI">OBR Service API</a></li>
+ <li><a href="#ApacheFelixOSGiBundleRepository-OBRShellCommand">OBR Shell Command</a></li>
+<ul>
+ <li><a href="#ApacheFelixOSGiBundleRepository-obrhelp">obr help</a></li>
+ <li><a href="#ApacheFelixOSGiBundleRepository-obrlisturl">obr list-url</a></li>
+ <li><a href="#ApacheFelixOSGiBundleRepository-obraddurl">obr add-url</a></li>
+ <li><a href="#ApacheFelixOSGiBundleRepository-obrremoveurl">obr remove-url</a></li>
+ <li><a href="#ApacheFelixOSGiBundleRepository-obrlist">obr list</a></li>
+ <li><a href="#ApacheFelixOSGiBundleRepository-obrinfo">obr info</a></li>
+ <li><a href="#ApacheFelixOSGiBundleRepository-obrdeploy">obr deploy</a></li>
+ <li><a href="#ApacheFelixOSGiBundleRepository-obrstart">obr start</a></li>
+ <li><a href="#ApacheFelixOSGiBundleRepository-obrsource">obr source</a></li>
+ <li><a href="#ApacheFelixOSGiBundleRepository-obrjavadoc">obr javadoc</a></li>
+</ul>
+ <li><a href="#ApacheFelixOSGiBundleRepository-UsingOBRwithaProxy">Using OBR with a Proxy</a></li>
+ <li><a href="#ApacheFelixOSGiBundleRepository-BundleSourcePackaging">Bundle Source Packaging</a></li>
+ <li><a href="#ApacheFelixOSGiBundleRepository-NoteonOSGiR3Bundles">Note on OSGi R3 Bundles</a></li>
+ <li><a href="#ApacheFelixOSGiBundleRepository-Feedback">Feedback</a></li>
+</ul></div>
+
+<p><a name="ApacheFelixOSGiBundleRepository-motivation"></a></p>
+
+<h2><a name="ApacheFelixOSGiBundleRepository-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-overview"></a></p>
+
+<h2><a name="ApacheFelixOSGiBundleRepository-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_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_files/obr-high-level.png" align="absmiddle" border="0"></p>
+
+<p><a name="ApacheFelixOSGiBundleRepository-repositoryfile"></a></p>
+
+<h2><a name="ApacheFelixOSGiBundleRepository-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 <a href="http://www2.osgi.org/download/rfc-0112_BundleRepository.pdf" rel="nofollow">OSGi RFC 112</a>
+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 panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<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 panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<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 panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<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-serviceapi"></a></p>
+
+<h2><a name="ApacheFelixOSGiBundleRepository-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 panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<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 panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<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 panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<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">true</span>);
+}
+<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/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>
+
+<p><a name="ApacheFelixOSGiBundleRepository-shellcommand"></a></p>
+
+<h2><a name="ApacheFelixOSGiBundleRepository-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-obrhelp"></a></p>
+
+<h3><a name="ApacheFelixOSGiBundleRepository-obrhelp"></a>obr help</h3>
+
+<p>Syntax:</p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>obr help [add-url | remove-url | list-url | list | info | deploy | start | source | javadoc]
+</pre>
+</div></div>
+<p>This command is used to display additional information about the other OBR commands.</p>
+
+<p><a name="ApacheFelixOSGiBundleRepository-obrlisturl"></a></p>
+
+<h3><a name="ApacheFelixOSGiBundleRepository-obrlisturl"></a>obr list-url</h3>
+
+<p>Syntax:</p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<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-obraddurl"></a></p>
+
+<h3><a name="ApacheFelixOSGiBundleRepository-obraddurl"></a>obr add-url</h3>
+
+<p>Syntax:</p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<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-obrremoveurl"></a></p>
+
+<h3><a name="ApacheFelixOSGiBundleRepository-obrremoveurl"></a>obr remove-url</h3>
+
+<p>Syntax:</p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<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-obrlist"></a></p>
+
+<h3><a name="ApacheFelixOSGiBundleRepository-obrlist"></a>obr list</h3>
+
+<p>Syntax:</p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<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-obrinfo"></a></p>
+
+<h3><a name="ApacheFelixOSGiBundleRepository-obrinfo"></a>obr info</h3>
+
+<p>Syntax:</p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<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 panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<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-obrdeploy"></a></p>
+
+<h3><a name="ApacheFelixOSGiBundleRepository-obrdeploy"></a>obr deploy</h3>
+
+<p>Syntax:</p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>obr deploy <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. 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 panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<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-obrstart"></a></p>
+
+<h3><a name="ApacheFelixOSGiBundleRepository-obrstart"></a>obr start</h3>
+
+<p>Syntax:</p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<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 panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<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-obrsource"></a></p>
+
+<h3><a name="ApacheFelixOSGiBundleRepository-obrsource"></a>obr source</h3>
+
+<p>Syntax:</p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<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 panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<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>
+
+<h3><a name="ApacheFelixOSGiBundleRepository-obrjavadoc"></a>obr javadoc</h3>
+
+<p>Syntax:</p>
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>obr javadoc [-x] <local-dir> <bundle-name>[;<version>] ...
+</pre>
+</div></div>
+<p>This command retrieves the javadoc archives of the specified bundles
+and saves them to the specified local directory; use the "-x" switch to
+automatically extract the javadoc 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 panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>obr javadoc /home/rickhall/tmp "Bundle Repository";1.0.0
+</pre>
+</div></div>
+<p>The above example retrieves the javadoc 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-proxy"></a></p>
+
+<h2><a name="ApacheFelixOSGiBundleRepository-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-sourcepackaging"></a></p>
+
+<h2><a name="ApacheFelixOSGiBundleRepository-BundleSourcePackaging"></a>Bundle Source Packaging</h2>
+
+<p>Coming soon...</p>
+
+<p><a name="ApacheFelixOSGiBundleRepository-r3note"></a></p>
+
+<h2><a name="ApacheFelixOSGiBundleRepository-NoteonOSGiR3Bundles"></a>Note on OSGi R3 Bundles</h2>
+
+<p>In contrast to OSGi R4 the previous specifications, most notably R3, allowed bundles without the <tt>Bundle-SymbolicName</tt>
+header. The Felix OSGi Bundle Repository implementation heavily relies
+on the symbolic name being defined in bundles. As a consequence bundles
+without a symbolic name are not fully supported by the Bundle
+Repository:</p>
+
+<ul>
+ <li>Bundles installed in the framework are used by the Bundle
+Repository implementation to resolve dependencies regardless of whether
+they 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>
+ <li>Bundles installed in the framework without a <tt>Bundle-SymbolicName</tt>
+header cannot be updated by the Bundle Repository implementation
+because updates from the bundle repository cannot be correlated to such
+"anonymous" bundles.</li>
+</ul>
+
+
+
+<p><a name="ApacheFelixOSGiBundleRepository-feedback"></a></p>
+
+<h2><a name="ApacheFelixOSGiBundleRepository-Feedback"></a>Feedback</h2>
+
+<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>
+ </div>
+ </body></html>
diff --git a/main.distribution/doc/apache-felix-osgi-bundle-repository_files/apache-felix-small.png b/main.distribution/doc/apache-felix-osgi-bundle-repository_files/apache-felix-small.png
new file mode 100644
index 0000000..95bfa5e
--- /dev/null
+++ b/main.distribution/doc/apache-felix-osgi-bundle-repository_files/apache-felix-small.png
Binary files differ
diff --git a/main.distribution/doc/apache-felix-osgi-bundle-repository_files/apache.png b/main.distribution/doc/apache-felix-osgi-bundle-repository_files/apache.png
new file mode 100644
index 0000000..5132f65
--- /dev/null
+++ b/main.distribution/doc/apache-felix-osgi-bundle-repository_files/apache.png
Binary files differ
diff --git a/main.distribution/doc/apache-felix-osgi-bundle-repository_files/button.html b/main.distribution/doc/apache-felix-osgi-bundle-repository_files/button.html
new file mode 100644
index 0000000..dc64b6c
--- /dev/null
+++ b/main.distribution/doc/apache-felix-osgi-bundle-repository_files/button.html
@@ -0,0 +1,5 @@
+<html><head>
+<meta http-equiv="content-type" content="text/html; charset=UTF-8"><!-- ads start -->
+</head><body><a href="http://www.us.apachecon.com/c/acus2009/" target="_blank"><img src="button_data/2009-usa-125x125.png" title="ApacheCon US 2009" border="0" height="125" width="125"></a>
+<!-- ads end -->
+</body></html>
\ No newline at end of file
diff --git a/main.distribution/doc/apache-felix-osgi-bundle-repository_files/button_data/2009-usa-125x125.png b/main.distribution/doc/apache-felix-osgi-bundle-repository_files/button_data/2009-usa-125x125.png
new file mode 100644
index 0000000..117c695
--- /dev/null
+++ b/main.distribution/doc/apache-felix-osgi-bundle-repository_files/button_data/2009-usa-125x125.png
Binary files differ
diff --git a/main.distribution/doc/apache-felix-osgi-bundle-repository_files/linkext7.gif b/main.distribution/doc/apache-felix-osgi-bundle-repository_files/linkext7.gif
new file mode 100644
index 0000000..f2dd2dc
--- /dev/null
+++ b/main.distribution/doc/apache-felix-osgi-bundle-repository_files/linkext7.gif
Binary files differ
diff --git a/main.distribution/doc/apache-felix-osgi-bundle-repository_files/logo.png b/main.distribution/doc/apache-felix-osgi-bundle-repository_files/logo.png
new file mode 100644
index 0000000..dccbddc
--- /dev/null
+++ b/main.distribution/doc/apache-felix-osgi-bundle-repository_files/logo.png
Binary files differ
diff --git a/main.distribution/doc/apache-felix-osgi-bundle-repository_files/mail_small.gif b/main.distribution/doc/apache-felix-osgi-bundle-repository_files/mail_small.gif
new file mode 100644
index 0000000..a3b7d9f
--- /dev/null
+++ b/main.distribution/doc/apache-felix-osgi-bundle-repository_files/mail_small.gif
Binary files differ
diff --git a/main.distribution/doc/apache-felix-osgi-bundle-repository_files/obr-entities.png b/main.distribution/doc/apache-felix-osgi-bundle-repository_files/obr-entities.png
new file mode 100644
index 0000000..81d3760
--- /dev/null
+++ b/main.distribution/doc/apache-felix-osgi-bundle-repository_files/obr-entities.png
Binary files differ
diff --git a/main.distribution/doc/apache-felix-osgi-bundle-repository_files/obr-high-level.png b/main.distribution/doc/apache-felix-osgi-bundle-repository_files/obr-high-level.png
new file mode 100644
index 0000000..566f171
--- /dev/null
+++ b/main.distribution/doc/apache-felix-osgi-bundle-repository_files/obr-high-level.png
Binary files differ
diff --git a/main.distribution/doc/apache-felix-osgi-bundle-repository_files/site.css b/main.distribution/doc/apache-felix-osgi-bundle-repository_files/site.css
new file mode 100644
index 0000000..959ab0a
--- /dev/null
+++ b/main.distribution/doc/apache-felix-osgi-bundle-repository_files/site.css
@@ -0,0 +1,25 @@
+/* @override http://felix.apache.org/site/media.data/site.css */
+
+body { background-color: #ffffff; color: #3b3b3b; font-family: Tahoma, Arial, sans-serif; font-size: 10pt; line-height: 140% }
+h1, h2, h3, h4, h5, h6 { font-weight: normal; color: #000000; line-height: 100%; margin-top: 0px}
+h1 { font-size: 200% }
+h2 { font-size: 175% }
+h3 { font-size: 150% }
+h4 { font-size: 140% }
+h5 { font-size: 130% }
+h6 { font-size: 120% }
+a { color: #1980af }
+a:visited { color: #1980af }
+a:hover { color: #1faae9 }
+.title { position: absolute; left: 1px; right: 1px; top:25px; height: 81px; background: url(http://felix.apache.org/site/media.data/gradient.png) repeat-x; background-position: bottom; }
+.logo { position: absolute; width: 15em; height: 81px; text-align: center; }
+.header { text-align: right; margin-right: 20pt; margin-top: 30pt;}
+.menu { border-top: 10px solid #f9bb00; position: absolute; top: 107px; left: 1px; width: 15em; bottom: 0px; padding: 0px; background-color: #fcfcfc }
+.menu ul { background-color: #fdf5d9; list-style: none; padding-left: 4em; margin-top: 0px; padding-top: 2em; padding-bottom: 2em; margin-left: 0px; color: #4a4a43}
+.menu a { text-decoration: none; color: #4a4a43 }
+.main { position: absolute; border-top: 10px solid #cde0ea; top: 107px; left: 15em; right: 1px; margin-left: 2px; padding-right: 4em; padding-left: 1em; padding-top: 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
diff --git a/main.distribution/doc/apache-felix-shell-service.html b/main.distribution/doc/apache-felix-shell-service.html
new file mode 100644
index 0000000..f2198d8
--- /dev/null
+++ b/main.distribution/doc/apache-felix-shell-service.html
@@ -0,0 +1,439 @@
+<!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 - Apache Felix Shell Service</title>
+ <link rel="stylesheet" href="apache-felix-shell-service_files/site.css" type="text/css" media="all">
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ </head><body>
+ <div class="title"><div class="logo"><a href="http://felix.apache.org/site/index.html"><img alt="Apache Felix" src="apache-felix-shell-service_files/logo.png" border="0"></a></div><div class="header"><a href="http://www.apache.org/"><img alt="Apache" src="apache-felix-shell-service-Dateien/apache.png" border="0"></a></div></div>
+ <div class="menu">
+<ul>
+ <li><a href="http://felix.apache.org/site/news.html" title="news">news</a></li>
+ <li><a href="http://felix.apache.org/site/license.html" title="license">license</a></li>
+ <li><a href="http://felix.apache.org/site/downloads.cgi" rel="nofollow">downloads</a></li>
+ <li><a href="http://felix.apache.org/site/documentation.html" title="documentation">documentation</a></li>
+ <li><a href="http://felix.apache.org/site/mailinglists.html" title="mailinglists">mailing lists</a></li>
+ <li><a href="http://felix.apache.org/site/contributing.html" title="Contributing">contributing</a></li>
+ <li><a href="http://www.apache.org/" rel="nofollow">asf</a></li>
+ <li><a href="http://www.apache.org/foundation/sponsorship.html" rel="nofollow">sponsorship</a></li>
+ <li><a href="http://www.apache.org/foundation/thanks.html" rel="nofollow">sponsors</a>
+<!-- ApacheCon Ad -->
+<iframe src="apache-felix-shell-service_files/button.html" style="border-width: 0pt; float: left;" frameborder="0" height="135" scrolling="no" width="135"></iframe>
+<p style="height: 100px;">
+<!-- ApacheCon Ad -->
+</p></li></ul> </div>
+ <div class="main">
+<h1><a name="ApacheFelixShellService-ApacheFelixShellService"></a>Apache Felix Shell Service</h1>
+
+<ul>
+ <li><a href="#ApacheFelixShellService-overview">Overview</a></li>
+ <li><a href="#ApacheFelixShellService-service">How the Shell Service Works</a></li>
+ <li><a href="#ApacheFelixShellService-commands">How Commands Work</a></li>
+ <li><a href="#ApacheFelixShellService-creating">Creating a Command</a></li>
+ <li><a href="#ApacheFelixShellService-security">Security and the Shell Service</a></li>
+ <li><a href="#ApacheFelixShellService-feedback">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>
+
+<style type="text/css">
+@import url(/confluence/download/resources/confluence.ext.code:code/shStyles.css);
+</style>
+<!--[if IE]>
+<style type="text/css">
+ .code textarea, .code input { padding: 0 !important; }
+</style>
+<![endif]-->
+<script class="javascript" src="apache-felix-shell-service_files/shCore.js"></script>
+<script class="javascript" src="apache-felix-shell-service_files/shBrushCSharp.js"></script>
+<script class="javascript" src="apache-felix-shell-service_files/shBrushPhp.js"></script>
+<script class="javascript" src="apache-felix-shell-service_files/shBrushJScript.js"></script>
+<script class="javascript" src="apache-felix-shell-service_files/shBrushVb.js"></script>
+<script class="javascript" src="apache-felix-shell-service_files/shBrushSql.js"></script>
+<script class="javascript" src="apache-felix-shell-service_files/shBrushXml.js"></script>
+<script class="javascript" src="apache-felix-shell-service_files/shBrushShell.html"></script>
+<script class="javascript" src="apache-felix-shell-service_files/shBrushDelphi.js"></script>
+<script class="javascript" src="apache-felix-shell-service_files/shBrushPython.js"></script>
+<script class="javascript" src="apache-felix-shell-service_files/shBrushJava.js"></script>
+<div class="code">
+<textarea name="newcodemacro" class="java:nocontrols:nogutter" rows="10" readonly="readonly">package org.apache.felix.shell;
+
+public interface ShellService
+{
+ public String[] getCommands();
+ public String getCommandUsage(String name);
+ public String getCommandDescription(String name);
+ public ServiceReference getCommandReference(String name);
+ public void executeCommand(
+ String commandLine, PrintStream out, PrintStream err)
+ throws Exception;
+}</textarea>
+<script class="javascript">
+ if(!window.newcodemacro_initialised)
+ {
+ window.newcodemacro_initialised = true;
+ window.oldonloadmethod = window.onload;
+ window.onload = function(){
+ dp.SyntaxHighlighter.HighlightAll('newcodemacro');
+ if(window.oldonloadmethod)
+ {
+ window.oldonloadmethod();
+ }
+ }
+ }
+
+</script>
+</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 panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>update 3 http://www.foo.com/bar.jar
+</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">
+<textarea name="newcodemacro" class="java:nocontrols:nogutter" rows="10" readonly="readonly">package org.apache.felix.shell;
+
+public interface Command
+{
+ public String getName();
+ public String getUsage();
+ public String getShortDescription();
+ public void execute(String line, PrintStream out, PrintStream err);
+}</textarea>
+<script class="javascript">
+ if(!window.newcodemacro_initialised)
+ {
+ window.newcodemacro_initialised = true;
+ window.oldonloadmethod = window.onload;
+ window.onload = function(){
+ dp.SyntaxHighlighter.HighlightAll('newcodemacro');
+ if(window.oldonloadmethod)
+ {
+ window.oldonloadmethod();
+ }
+ }
+ }
+
+</script>
+</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">
+<textarea name="newcodemacro" class="java:nocontrols:nogutter" rows="10" readonly="readonly">package test;
+
+import java.io.PrintStream;
+import java.net.URL;
+import java.net.MalformedURLException;
+import java.util.StringTokenizer;
+
+import org.osgi.framework.*;
+import org.apache.felix.shell.ShellService;
+import org.apache.felix.shell.Command;
+
+public class MyStartCommandImpl implements Command
+{
+ private BundleContext m_context = null;
+
+ public MyStartCommandImpl(BundleContext context)
+ {
+ m_context = context;
+ }
+
+ public String getName()
+ {
+ return "mystart";
+ }
+
+ public String getUsage()
+ {
+ return "mystart <id> [<id> ...]";
+ }
+
+ public String getShortDescription()
+ {
+ return "start bundle(s).";
+ }
+
+ public void execute(String s, PrintStream out, PrintStream err)
+ {
+ StringTokenizer st = new StringTokenizer(s, " ");
+
+ // Ignore the command name.
+ st.nextToken();
+
+ // There should be at least one bundle id.
+ if (st.countTokens() >= 1)
+ {
+ while (st.hasMoreTokens())
+ {
+ String id = st.nextToken().trim();
+
+ try {
+ long l = Long.valueOf(id).longValue();
+ Bundle bundle = m_context.getBundle(l);
+ if (bundle != null)
+ {
+ bundle.start();
+ }
+ else
+ {
+ err.println("Bundle ID " + id + " is invalid.");
+ }
+ } catch (NumberFormatException ex) {
+ err.println("Unable to parse id '" + id + "'.");
+ } catch (BundleException ex) {
+ if (ex.getNestedException() != null)
+ err.println(ex.getNestedException().toString());
+ else
+ err.println(ex.toString());
+ } catch (Exception ex) {
+ err.println(ex.toString());
+ }
+ }
+ }
+ else
+ {
+ err.println("Incorrect number of arguments");
+ }
+ }
+}</textarea>
+<script class="javascript">
+ if(!window.newcodemacro_initialised)
+ {
+ window.newcodemacro_initialised = true;
+ window.oldonloadmethod = window.onload;
+ window.onload = function(){
+ dp.SyntaxHighlighter.HighlightAll('newcodemacro');
+ if(window.oldonloadmethod)
+ {
+ window.oldonloadmethod();
+ }
+ }
+ }
+
+</script>
+</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">
+<textarea name="newcodemacro" class="java:nocontrols:nogutter" rows="10" readonly="readonly">package test;
+
+import org.osgi.framework.BundleActivator;
+import org.osgi.framework.BundleContext;
+
+public class MyStartActivator implements BundleActivator
+{
+ private transient BundleContext m_context = null;
+
+ public void start(BundleContext context)
+ {
+ m_context = context;
+
+ // Register the command service.
+ context.registerService(
+ org.apache.felix.shell.Command.class.getName(),
+ new MyStartCommandImpl(m_context), null);
+ }
+
+ public void stop(BundleContext context)
+ {
+ // Services are automatically unregistered so
+ // we don't have to unregister the factory here.
+ }
+}</textarea>
+<script class="javascript">
+ if(!window.newcodemacro_initialised)
+ {
+ window.newcodemacro_initialised = true;
+ window.oldonloadmethod = window.onload;
+ window.onload = function(){
+ dp.SyntaxHighlighter.HighlightAll('newcodemacro');
+ if(window.oldonloadmethod)
+ {
+ window.oldonloadmethod();
+ }
+ }
+ }
+
+</script>
+</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 panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<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">
+<textarea name="newcodemacro" class="java:nocontrols:nogutter" rows="10" readonly="readonly">Bundle-Name: My Start Command
+Bundle-Description: A 'start' command for the shell service.
+Bundle-Activator: test.MyStartActivator
+Bundle-ClassPath: .
+Import-Package: org.apache.felix.shell</textarea>
+<script class="javascript">
+ if(!window.newcodemacro_initialised)
+ {
+ window.newcodemacro_initialised = true;
+ window.oldonloadmethod = window.onload;
+ window.onload = function(){
+ dp.SyntaxHighlighter.HighlightAll('newcodemacro');
+ if(window.oldonloadmethod)
+ {
+ window.oldonloadmethod();
+ }
+ }
+ }
+
+</script>
+</div>
+
+
+<p>To create the bundle JAR file, issue the command:</p>
+
+<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+<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 <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>
+ </div>
+ </body></html>
diff --git a/main.distribution/doc/apache-felix-shell-service_files/apache-felix-small.png b/main.distribution/doc/apache-felix-shell-service_files/apache-felix-small.png
new file mode 100644
index 0000000..95bfa5e
--- /dev/null
+++ b/main.distribution/doc/apache-felix-shell-service_files/apache-felix-small.png
Binary files differ
diff --git a/main.distribution/doc/apache-felix-shell-service_files/apache.png b/main.distribution/doc/apache-felix-shell-service_files/apache.png
new file mode 100644
index 0000000..5132f65
--- /dev/null
+++ b/main.distribution/doc/apache-felix-shell-service_files/apache.png
Binary files differ
diff --git a/main.distribution/doc/apache-felix-shell-service_files/button.html b/main.distribution/doc/apache-felix-shell-service_files/button.html
new file mode 100644
index 0000000..d6a5da8
--- /dev/null
+++ b/main.distribution/doc/apache-felix-shell-service_files/button.html
@@ -0,0 +1,3 @@
+<html><head><!-- ads start --></head><body><a href="http://www.us.apachecon.com/us2008/" target="_blank"><img src="button_data/2008-usa-125x125.png" title="ApacheCon US 2008" border="0" height="125" width="125"></a>
+<!-- ads end -->
+</body></html>
\ No newline at end of file
diff --git a/main.distribution/doc/apache-felix-shell-service_files/button_data/2008-usa-125x125.png b/main.distribution/doc/apache-felix-shell-service_files/button_data/2008-usa-125x125.png
new file mode 100644
index 0000000..3d6008b
--- /dev/null
+++ b/main.distribution/doc/apache-felix-shell-service_files/button_data/2008-usa-125x125.png
Binary files differ
diff --git a/main.distribution/doc/apache-felix-shell-service_files/linkext7.gif b/main.distribution/doc/apache-felix-shell-service_files/linkext7.gif
new file mode 100644
index 0000000..f2dd2dc
--- /dev/null
+++ b/main.distribution/doc/apache-felix-shell-service_files/linkext7.gif
Binary files differ
diff --git a/main.distribution/doc/apache-felix-shell-service_files/logo.png b/main.distribution/doc/apache-felix-shell-service_files/logo.png
new file mode 100644
index 0000000..dccbddc
--- /dev/null
+++ b/main.distribution/doc/apache-felix-shell-service_files/logo.png
Binary files differ
diff --git a/main.distribution/doc/apache-felix-shell-service_files/mail_small.gif b/main.distribution/doc/apache-felix-shell-service_files/mail_small.gif
new file mode 100644
index 0000000..a3b7d9f
--- /dev/null
+++ b/main.distribution/doc/apache-felix-shell-service_files/mail_small.gif
Binary files differ
diff --git a/main.distribution/doc/apache-felix-shell-service_files/site.css b/main.distribution/doc/apache-felix-shell-service_files/site.css
new file mode 100644
index 0000000..959ab0a
--- /dev/null
+++ b/main.distribution/doc/apache-felix-shell-service_files/site.css
@@ -0,0 +1,25 @@
+/* @override http://felix.apache.org/site/media.data/site.css */
+
+body { background-color: #ffffff; color: #3b3b3b; font-family: Tahoma, Arial, sans-serif; font-size: 10pt; line-height: 140% }
+h1, h2, h3, h4, h5, h6 { font-weight: normal; color: #000000; line-height: 100%; margin-top: 0px}
+h1 { font-size: 200% }
+h2 { font-size: 175% }
+h3 { font-size: 150% }
+h4 { font-size: 140% }
+h5 { font-size: 130% }
+h6 { font-size: 120% }
+a { color: #1980af }
+a:visited { color: #1980af }
+a:hover { color: #1faae9 }
+.title { position: absolute; left: 1px; right: 1px; top:25px; height: 81px; background: url(http://felix.apache.org/site/media.data/gradient.png) repeat-x; background-position: bottom; }
+.logo { position: absolute; width: 15em; height: 81px; text-align: center; }
+.header { text-align: right; margin-right: 20pt; margin-top: 30pt;}
+.menu { border-top: 10px solid #f9bb00; position: absolute; top: 107px; left: 1px; width: 15em; bottom: 0px; padding: 0px; background-color: #fcfcfc }
+.menu ul { background-color: #fdf5d9; list-style: none; padding-left: 4em; margin-top: 0px; padding-top: 2em; padding-bottom: 2em; margin-left: 0px; color: #4a4a43}
+.menu a { text-decoration: none; color: #4a4a43 }
+.main { position: absolute; border-top: 10px solid #cde0ea; top: 107px; left: 15em; right: 1px; margin-left: 2px; padding-right: 4em; padding-left: 1em; padding-top: 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
diff --git a/main.distribution/doc/apache-felix-shell-tui.html b/main.distribution/doc/apache-felix-shell-tui.html
new file mode 100644
index 0000000..5f393db
--- /dev/null
+++ b/main.distribution/doc/apache-felix-shell-tui.html
@@ -0,0 +1,40 @@
+<!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 - Apache Felix Shell TUI</title>
+
+
+
+
+ <link rel="stylesheet" href="apache-felix-shell-tui_files/site.css" type="text/css" media="all">
+ <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"></head><body>
+ <div class="title"><div class="logo"><a href="http://felix.apache.org/site/index.html"><img alt="Apache Felix" src="apache-felix-shell-tui_files/logo.png" border="0"></a></div><div class="header"><a href="http://www.apache.org/"><img alt="Apache" src="apache-felix-shell-tui_files/apache.png" border="0"></a></div></div>
+ <div class="menu">
+<ul>
+ <li><a href="http://felix.apache.org/site/news.html" title="news">news</a></li>
+ <li><a href="http://felix.apache.org/site/license.html" title="license">license</a></li>
+ <li><span class="nobr"><a href="http://felix.apache.org/site/downloads.cgi" title="Visit page outside Confluence" rel="nofollow">downloads<sup><img class="rendericon" src="apache-felix-shell-tui_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span></li>
+ <li><a href="http://felix.apache.org/site/documentation.html" title="documentation">documentation</a></li>
+ <li><a href="http://felix.apache.org/site/mailinglists.html" title="mailinglists">mailing lists</a></li>
+ <li><a href="http://felix.apache.org/site/contributing.html" title="Contributing">contributing</a></li>
+ <li><span class="nobr"><a href="http://www.apache.org/" title="Visit page outside Confluence" rel="nofollow">asf<sup><img class="rendericon" src="apache-felix-shell-tui_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span></li>
+ <li><span class="nobr"><a href="http://www.apache.org/foundation/sponsorship.html" title="Visit page outside Confluence" rel="nofollow">sponsorship<sup><img class="rendericon" src="apache-felix-shell-tui_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span></li>
+ <li><span class="nobr"><a href="http://www.apache.org/foundation/thanks.html" title="Visit page outside Confluence" rel="nofollow">sponsors<sup><img class="rendericon" src="apache-felix-shell-tui_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span>
+<!-- ApacheCon Ad -->
+<iframe src="apache-felix-shell-tui_files/button.html" style="border-width: 0pt; float: left;" frameborder="0" height="135" scrolling="no" width="135"></iframe>
+<p style="height: 100px;">
+<!-- ApacheCon Ad -->
+</p></li></ul> </div>
+ <div class="main">
+<h1><a name="ApacheFelixShellTUI-ApacheFelixShellTUI"></a>Apache Felix Shell TUI</h1>
+<p>The Apache Felix Shell TUI (Textual User Interface) sub-project provides a simple, text-based user interface for the <a href="/confluence/display/FELIX/Apache+Felix+Shell+Service" title="Apache Felix Shell Service">Apache Felix Shell Service</a>. This bundle is not of much use by itself and should always be used in conjunction with the shell service bundle. The shell service and shell TUI bundles are used by the standard Felix launcher to provide a means for interacting with the launched Felix framework instance. The shell TUI bundle is not required to use the shell service; it is possible to use it programmatically, via a GUI interface, or a remote access interface.</p>
+
+<p>Shell TUI supports one configuration property:</p>
+
+<ul>
+ <li><tt>shell.tui.checkinput</tt> - This is a simple workaround for a JRE bug which can appear when running Shell TUI inside Eclipse; the default value is <tt>false</tt>. Note that if this workaround is enabled, when running from the command line under Windows, character input is not echoed back to the screen.</li>
+</ul>
+
+
+<p>To set this property, add it to the <tt>conf/config.properties</tt> file of your Felix installation.</p>
+
+ </div>
+ </body></html>
diff --git a/main.distribution/doc/apache-felix-shell-tui_files/apache-felix-small.png b/main.distribution/doc/apache-felix-shell-tui_files/apache-felix-small.png
new file mode 100644
index 0000000..95bfa5e
--- /dev/null
+++ b/main.distribution/doc/apache-felix-shell-tui_files/apache-felix-small.png
Binary files differ
diff --git a/main.distribution/doc/apache-felix-shell-tui_files/apache.png b/main.distribution/doc/apache-felix-shell-tui_files/apache.png
new file mode 100644
index 0000000..5132f65
--- /dev/null
+++ b/main.distribution/doc/apache-felix-shell-tui_files/apache.png
Binary files differ
diff --git a/main.distribution/doc/apache-felix-shell-tui_files/button.html b/main.distribution/doc/apache-felix-shell-tui_files/button.html
new file mode 100644
index 0000000..d6a5da8
--- /dev/null
+++ b/main.distribution/doc/apache-felix-shell-tui_files/button.html
@@ -0,0 +1,3 @@
+<html><head><!-- ads start --></head><body><a href="http://www.us.apachecon.com/us2008/" target="_blank"><img src="button_data/2008-usa-125x125.png" title="ApacheCon US 2008" border="0" height="125" width="125"></a>
+<!-- ads end -->
+</body></html>
\ No newline at end of file
diff --git a/main.distribution/doc/apache-felix-shell-tui_files/button_data/2008-usa-125x125.png b/main.distribution/doc/apache-felix-shell-tui_files/button_data/2008-usa-125x125.png
new file mode 100644
index 0000000..3d6008b
--- /dev/null
+++ b/main.distribution/doc/apache-felix-shell-tui_files/button_data/2008-usa-125x125.png
Binary files differ
diff --git a/main.distribution/doc/apache-felix-shell-tui_files/linkext7.gif b/main.distribution/doc/apache-felix-shell-tui_files/linkext7.gif
new file mode 100644
index 0000000..f2dd2dc
--- /dev/null
+++ b/main.distribution/doc/apache-felix-shell-tui_files/linkext7.gif
Binary files differ
diff --git a/main.distribution/doc/apache-felix-shell-tui_files/logo.png b/main.distribution/doc/apache-felix-shell-tui_files/logo.png
new file mode 100644
index 0000000..dccbddc
--- /dev/null
+++ b/main.distribution/doc/apache-felix-shell-tui_files/logo.png
Binary files differ
diff --git a/main.distribution/doc/apache-felix-shell-tui_files/site.css b/main.distribution/doc/apache-felix-shell-tui_files/site.css
new file mode 100644
index 0000000..959ab0a
--- /dev/null
+++ b/main.distribution/doc/apache-felix-shell-tui_files/site.css
@@ -0,0 +1,25 @@
+/* @override http://felix.apache.org/site/media.data/site.css */
+
+body { background-color: #ffffff; color: #3b3b3b; font-family: Tahoma, Arial, sans-serif; font-size: 10pt; line-height: 140% }
+h1, h2, h3, h4, h5, h6 { font-weight: normal; color: #000000; line-height: 100%; margin-top: 0px}
+h1 { font-size: 200% }
+h2 { font-size: 175% }
+h3 { font-size: 150% }
+h4 { font-size: 140% }
+h5 { font-size: 130% }
+h6 { font-size: 120% }
+a { color: #1980af }
+a:visited { color: #1980af }
+a:hover { color: #1faae9 }
+.title { position: absolute; left: 1px; right: 1px; top:25px; height: 81px; background: url(http://felix.apache.org/site/media.data/gradient.png) repeat-x; background-position: bottom; }
+.logo { position: absolute; width: 15em; height: 81px; text-align: center; }
+.header { text-align: right; margin-right: 20pt; margin-top: 30pt;}
+.menu { border-top: 10px solid #f9bb00; position: absolute; top: 107px; left: 1px; width: 15em; bottom: 0px; padding: 0px; background-color: #fcfcfc }
+.menu ul { background-color: #fdf5d9; list-style: none; padding-left: 4em; margin-top: 0px; padding-top: 2em; padding-bottom: 2em; margin-left: 0px; color: #4a4a43}
+.menu a { text-decoration: none; color: #4a4a43 }
+.main { position: absolute; border-top: 10px solid #cde0ea; top: 107px; left: 15em; right: 1px; margin-left: 2px; padding-right: 4em; padding-left: 1em; padding-top: 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
diff --git a/main.distribution/doc/changelog.txt b/main.distribution/doc/changelog.txt
new file mode 100644
index 0000000..60439ed
--- /dev/null
+++ b/main.distribution/doc/changelog.txt
@@ -0,0 +1,4 @@
+2.0.4
+-----
+
+** Initial release
diff --git a/main.distribution/doc/changelog_bundlerepository.txt b/main.distribution/doc/changelog_bundlerepository.txt
new file mode 100644
index 0000000..e5dade4
--- /dev/null
+++ b/main.distribution/doc/changelog_bundlerepository.txt
@@ -0,0 +1,95 @@
+Changes from 1.4.2 to 1.4.3
+---------------------------
+
+** Bug
+ * [FELIX-1792] - Felix OBR seems to just randomly choose one of the satisifed bundles if more than one bundle meets the requirement
+
+
+Changes from 1.4.1 to 1.4.2
+---------------------------
+
+** Task
+ * [FELIX-1617] - Modify framework, main, shell, shell.tui, and obr to depend on official OSGi JAR files
+
+Changes from 1.4.0 to 1.4.1
+---------------------------
+
+** Bug
+ * [FELIX-1000] - Updating an bundle which was installed via OBR fails
+ * [FELIX-1157] - NPE results in OBR if a resource does not have a presentation name
+ * [FELIX-1433] - java.lang.NumberFormatException in Bundle-Version (org.osgi.framework.Version) due to trailing whitespace
+
+Changes from 1.2.1 to 1.4.0
+---------------------------
+** Bug
+ * [FELIX-973] - FilterImpl from Felix Framework does not support none LDAP operators
+ * [FELIX-977] - Bundle resolving runs extreme long
+ * [FELIX-999] - The OBR ResolverImpl shouldn't try to start fragment bundles
+
+** Improvement
+ * [FELIX-884] - OBR should expose registered services as capabilities of local repository
+ * [FELIX-887] - Ensure BundleListeners are not forgotten about
+ * [FELIX-940] - Add support for execution environment
+ * [FELIX-986] - Include the symbolicname in the output of obr list -v
+
+** New Feature
+ * [FELIX-976] - OBR update-url shell command
+
+Changes from 1.2.0 to 1.2.1
+---------------------------
+* [2008-10-24] Fixed potential NPE when comparing resources. (FELIX-789)
+* [2008-10-24] Removed the default repository URL from OBR, so now it must
+ be configured to have a repository. (FELIX-481)
+* [2008-10-24] Print message if there are no matching bundles. (FELIX-785)
+* [2008-10-23] Modified the OBR shell command to hide multiple versions of
+ available artifacts to cut down on noise. It is still possible to list
+ all versions by using a new "-v" switch.
+* [2008-09-29] Adapt Bundle-DocURL header to modified URL
+
+
+Changes from 1.0.3 to 1.2.0
+---------------------------
+
+* [2008-08-30] Prevent issues when updating running bundles. (FELIX-701)
+* [2008-08-28] Prevent NullPointerException if a locally installed bundle
+ does not have a Bundle-SymbolicName or version. (FELIX-108)
+* [2008-08-12] Added OBR descriptor and updated to the newest bundle plugin. (FELIX-672)
+* [2008-07-31] Use LogService instead of System.err. (FELIX-482)
+* [2008-07-21] Modified OBR to correctly consider the namespace attribute
+ when matching capabilities to requirements. (FELIX-638)
+* [2008-06-26] Implement referral with hop count support. (FELIX-399)
+* [2008-05-09] Return an empty resource array when querying with a filter
+ with invalid syntax. (FELIX-480)
+* [2008-05-09] Fixed improper synchronization with respect to visibility rules.
+* [2008-05-09] Ignore resources with invalid filters. (FELIX-484)
+* [2008-05-09] Move repository URL list initialization to a later time to
+ avoid the default repository URL if it is not desired. (FELIX-485)
+
+Changes from 1.0.2 to 1.0.3
+---------------------------
+
+* [2008-04-21] Re-release to make bytecode executable on jre 1.3.
+
+Changes from 1.0.0 to 1.0.2
+---------------------------
+
+* [2008-01-27] Change the default url from sf.net to sourceforge.net.
+* [2007-10-25] Add support for zipped repository files. (FELIX-410)
+* [2007-10-03] Updated OBR's VersionRange to match the Framework's VersionRange
+ and now accept whitespace in its version range. (FELIX-389)
+* [2007-09-24] Extract OSGi OBR service API to a non-bundle jar to avoid
+ circular build problems.
+
+Changes from 0.8.0-incubator to 1.0.0
+-------------------------------------
+
+* [2007-03-16] Correctly initialized member fields to avoid incorrectly
+ assigning the source and license URLs. (FELIX-242)
+* [2007-03-19] Parent POM extends Apache POM for Apache-wide policies.
+ (FELIX-260)
+* [2007-05-18] Improved OBR dependency resolution by searching resolving
+ bundles before local bundles and to search through all available
+ candidates to find one that can resolve instead of picking one and failing
+ if it cannot be resolved. (FELIX-285)
+* [2007-07-13] Fixed LDAP filter syntax bug when using inclusive version
+ ranges. (FELIX-327)
diff --git a/main.distribution/doc/changelog_framework.txt b/main.distribution/doc/changelog_framework.txt
new file mode 100644
index 0000000..47c699a
--- /dev/null
+++ b/main.distribution/doc/changelog_framework.txt
@@ -0,0 +1,535 @@
+Changes from 2.0.3 to 2.0.4
+---------------------------
+
+** Bug
+ * [FELIX-2056] - URLHandlersStreamHandler not getting handlers from frameworks that are inside a different classloader
+ * [FELIX-2067] - Fragment bundle ignored silently when the host Bundle-SymbolicName equals import package name
+ * [FELIX-2073] - The System Bundle is not providing WS Addressing
+
+** Improvement
+ * [FELIX-2071] - Missing checks inside ModuleImpl (in Framework) which causes exceptions
+
+Changes from 2.0.2 to 2.0.3
+---------------------------
+
+** Bug
+ * [FELIX-1838] - PackageAdmin.getExportedPackages() duplicates output for packages with different version
+ * [FELIX-1867] - ModuleImpl diagnoseClassLoadError throw NullPointerException for empty package name in debug mode
+ * [FELIX-1917] - A few minor bugs in the framework found while embedding Felix
+ * [FELIX-1919] - Fragment bundle cannot be linked to its host
+ * [FELIX-1920] - RequiredBundle.getRequiringBundles() incorrectly calculates result
+ * [FELIX-1929] - getStartLevel() always reports requested start level, not active start level
+ * [FELIX-1982] - Documented but uninterpreted felix.cache.* properties
+ * [FELIX-1998] - Use UTF-8 when decoding reference location URLs
+ * [FELIX-2002] - Uninstalled fragments are not properly detached
+
+** Improvement
+ * [FELIX-37] - Implement security for bundle resource URLs
+ * [FELIX-325] - Factor out security checks from the framework/system bundle code
+ * [FELIX-1973] - Implement all required security checks
+
+** New Feature
+ * [FELIX-30] - Implement extension bundles
+ * [FELIX-1991] - Allow boot delegation class loader to be configurable per bundle
+
+
+Changes from 2.0.1 to 2.0.2
+---------------------------
+
+** Bug
+ * [FELIX-1754] - Usage of BundleContext.getServiceReferences results in failure to activate components
+ * [FELIX-1782] - Errors during start-up on gnu/classpath based VMs (jamvm, kaffe, cacao) and mika
+ * [FELIX-1795] - Bundle version ignored in Fragment-Host header
+ * [FELIX-1834] - java.io.IOException: No framework context found when embedding felix frameworks as bundles
+
+** Improvement
+ * [FELIX-1534] - Improve fragment merging
+ * [FELIX-1781] - Try to reduce object allocations/usage in resolver algorithm
+ * [FELIX-1783] - Eliminate contention on ServiceRegistry.getServiceReferences(String, Filter)
+
+Changes from 2.0.0 to 2.0.1
+---------------------------
+
+** Bug
+ * [FELIX-1565] - Deadlock UrlHandlers
+ * [FELIX-1573] - Occasional NPE in URLHandlersBundleStreamHandler
+ * [FELIX-1580] - Regression with native library handling
+ * [FELIX-1586] - Framework reports org.osgi.framework.version as 1.3
+ * [FELIX-1600] - ServiceReference.isAssignableTo() always returns true if requesting bundle has no wire
+ * [FELIX-1631] - Implicit bootdelegation causes hang on android
+ * [FELIX-1710] - Resolver still does not discard all partial results when a cyclical dependency fails
+ * [FELIX-1721] - Framework boot delegation has a bug due to extraneous code
+ * [FELIX-1731] - Native library extraction could be improved to help cases where there are dependencies among libraries
+
+** Improvement
+ * [FELIX-1619] - Change the default auto-deploy actions to be install and start only
+ * [FELIX-1625] - Refactor bundle cache to simplify management
+ * [FELIX-1679] - VersionRange class should use finals to be thread safe.
+ * [FELIX-1724] - Various module metadata should be cached
+
+** Task
+ * [FELIX-1617] - Modify framework, main, shell, shell.tui, and obr to depend on official OSGi JAR files
+
+Changes from 1.8.1 to 2.0.0
+---------------------------
+
+** Bug
+ * [FELIX-893] - Felix fails to start using J9 JVM
+ * [FELIX-905] - Felix needs an RFC 126 FindHook
+ * [FELIX-906] - Felix needs an RFC 126 EventHook
+ * [FELIX-1122] - Extension bundles are not being removed from the bundle list when uninstalled
+ * [FELIX-1123] - System bundle does still not correctly handle (export) package attributes
+ * [FELIX-1124] - ResourceNotFoundException too verbose
+ * [FELIX-1130] - Bundle.getHeaders() returns a Dictionary<java.util.jar.Attribute.Name,String>
+ * [FELIX-1138] - URL Handlers performance regression due to service lookups
+ * [FELIX-1170] - MemoryLeak when stopping and restarting Felix
+ * [FELIX-1187] - BundleContext.ungetService() should return false only if the usage count is zero when the method is invoked
+ * [FELIX-1197] - Bundle Fragments not resolved correctly
+ * [FELIX-1198] - config.properties still refers to old org.osgi.framework.startlevel property
+ * [FELIX-1247] - BundleEvent.UNRESOLVED should be fired during update/uninstall not refresh
+ * [FELIX-1249] - Bundle.findEntries() should search fragments as well as the bundle itself
+ * [FELIX-1254] - Bundle#findEntries does not return resources from fragments
+ * [FELIX-1271] - Improve manifest localization to handle special cases
+ * [FELIX-1272] - Need to special case getResource()/getResources()/loadClass() for fragment bundles
+ * [FELIX-1273] - Bundle.getResources() should return null for a non-existent resource
+ * [FELIX-1277] - Fix Service Hooks Tests failures in RFC 126 TCK
+ * [FELIX-1279] - Framework.waitForStop() does not obey timeout
+ * [FELIX-1280] - Package Admin - getExportedPackages must return null instead of an empty array
+ * [FELIX-1285] - SecureAction captures the calling context incorrectly
+ * [FELIX-1286] - Module class loader should use secure action instead of a privileged block
+ * [FELIX-1287] - System bundle operations from RFC-132 (e.g., init(), start(), stop(), waitForStop()) are using wrong lock object
+ * [FELIX-1288] - System bundle context should be null after stopping the framework
+ * [FELIX-1292] - PackageAdmin.getBundle(Class) should return null if the bundle associated with the passed in class is from another framework
+ * [FELIX-1293] - StringMap used for case insensitive properties does not respect ordering if case sensitivity is changed
+ * [FELIX-1295] - ServiceRegistry increments/decrements service use count after/before getService/ungetService() is called on ServiceFactory
+ * [FELIX-1371] - Automatic parent class loader delegation does not correctly filter calls to Bundle.loadClass()
+ * [FELIX-1397] - Required execution environment verification should happen at resolve time, not install time
+ * [FELIX-1400] - bootdelegation and dynamic-import-packages are accepting invalid patterns
+ * [FELIX-1401] - Manifest localization with fragments not handled correctly
+ * [FELIX-1422] - Resolver does not always discard partial results when a cyclically dependency fails
+ * [FELIX-1435] - Resolver does not always resolve a dynamic import to a fragment export
+ * [FELIX-1527] - R4.2 spec errata now specifies uninstalling a bundle must transition through INSTALLED on its way to UNINSTALLED
+ * [FELIX-1551] - Start level service must synchronously persist bundle start level changes
+ * [FELIX-1556] - Bundle.getResource/s is not able to find resources if the package is not alraedy wired when I use DynamicImport-Package: *
+
+** Improvement
+ * [FELIX-712] - Ability to disable automatic parent classloader delegation
+ * [FELIX-883] - JarContent logs and then swallows exceptions when reading from JAR file, should probably throw an exception
+ * [FELIX-1120] - Enable BundleCache customization
+ * [FELIX-1134] - Add support for native libraries in fragments
+ * [FELIX-1189] - Improve error message in main when there is an error processing auto-install/start bundles
+ * [FELIX-1246] - PackageAdmin.getBundle() is not implemented efficiently
+ * [FELIX-1260] - Make Bundle.findEntries() and Bundle.getEntryPaths() more thread safe
+ * [FELIX-1291] - Implement support for proper return type from Framework.waitForStop()
+ * [FELIX-1300] - Remove legacy bundle cache support when extracting embedded JAR files
+ * [FELIX-1360] - Improve native library matching algorithm (part 2)
+ * [FELIX-1404] - Use provided classes from OSGi R4.2 companion code
+ * [FELIX-1432] - Manifest parser doesn't return import package declarations in order of manifest
+ * [FELIX-1462] - Felix framework launcher should only use standard launching API
+
+** New Feature
+ * [FELIX-33] - Implement system bundle update
+ * [FELIX-749] - Add support for lazy activation of bundles
+ * [FELIX-1193] - Implement org.osgi.framework.bundle.parent from RFC 132
+ * [FELIX-1205] - Update to the latest OSGi R4.2 API
+ * [FELIX-1244] - Add support for ServiceEvent.MODIFIED_ENDMATCH
+ * [FELIX-1250] - Support service exceptions for service factories
+ * [FELIX-1289] - Support for FrameworkUtil.getBundle()
+ * [FELIX-1297] - Implement support for new org.osgi.framework.command.execpermission configuration property
+ * [FELIX-1298] - Implement support for new org.osgi.framework.library.extensions configuration property
+ * [FELIX-1446] - Framework launcher should automatically deploy bundles in bundle directory
+ * [FELIX-1478] - Add shutdown hook to launcher to cleanly shutdown the framework if the process is killed
+
+
+
+
+** Task
+ * [FELIX-1144] - The NOTICE file for Main subproject is not correctly copied into the source JAR
+
+
+** Test
+ * [FELIX-1208] - Need migrate the EventDispatcherTest to newer version of EasyMock
+
+Changes form 1.6.1 to 1.8.0
+---------------------------
+** Bug
+ * [FELIX-1034] - bootdelegation property seems to be matching more packages than desired
+ * [FELIX-1059] - DynamicImport-Package matches more packages than desired
+
+** Improvement
+ * [FELIX-1060] - URLHandlers doesn't support URLStreamHandler.openConnection(proxy,url) method
+
+** New Feature
+ * [FELIX-29] - Implement bundle fragments
+
+Changes from 1.6.0 to 1.6.1
+---------------------------
+** Bug
+ * [FELIX-1027] - deadlock with felix 1.6.0 ?
+ * [FELIX-1028] - NPE in configuration view when running webconsole with Equinox
+ * [FELIX-1033] - Exceptions when Felix is started with security manager
+ * [FELIX-1035] - deadlock observed while using fileinstall to monitor multiple directories
+ * [FELIX-1045] - Felix 1.6.0 fails with ClassCircularityError
+
+Changes from 1.4.1 to 1.6.0
+---------------------------
+
+** Bug
+ * [FELIX-737] - Resolver does not correctly discard export when module imports the same package (part 2)
+ * [FELIX-852] - Fragment support is currently limited to directly resolved hosts
+ * [FELIX-869] - SCR throws exception on invalidating a component with a reference to a service that was already unregistered
+ * [FELIX-891] - Bundle lock acquisition should not record lock until it verifies the bundle is lockable
+ * [FELIX-892] - ServiceReferenceImpl improper implementation of equals and hashcode
+ * [FELIX-893] - Felix fails to start using J9 JVM
+ * [FELIX-897] - Empty system package is exported when a semicolon is present in "extra" configuration
+ * [FELIX-902] - Empty bundle.state file produces NPE
+ * [FELIX-910] - Framework may ignore framework startlevel on startup
+ * [FELIX-911] - Potential deadlock between Bundle.stop() and BundleContext.registerService()
+ * [FELIX-915] - PackageAdmin returns null on getBundle(...) with system classes
+ * [FELIX-934] - Bootdelegation bug
+ * [FELIX-947] - Behaviour of startlevel comman doesn't adhere to spec
+ * [FELIX-948] - ServiceReferenceImpl.compareTo should handle other types than integer for service ranking
+ * [FELIX-951] - Deadlock in iPojo when stopping Felix
+ * [FELIX-952] - Exception thrown when unregistering services because the bundle is stopped
+ * [FELIX-953] - Bundle#loadClass sometimes return null instead of throwing a CNFE
+ * [FELIX-961] - 100% CPU looping inside uses calculation
+ * [FELIX-962] - Erroneous class loading delegation to the application launcher classloader in some cases
+ * [FELIX-969] - system bundle does not correctly handle (export) package attributes
+ * [FELIX-971] - Exception thrown in ServiceTracker at shutdown
+ * [FELIX-978] - Resolver does not clean up properly on a failed recursive attempt to resolve
+ * [FELIX-1004] - Extensionmanager openConnection(URL) method should be public
+ * [FELIX-1005] - Strange list of imported packages returned by the package admin
+
+** Improvement
+ * [FELIX-681] - Modify daemon threads to catch all exceptions and log them to avoid premature thread death
+ * [FELIX-851] - Refactor the module abstraction layer to align more closely to OSGi concepts
+ * [FELIX-872] - JarContent swallows exception when opening manifest, it should log it
+ * [FELIX-883] - JarContent logs and then swallows exceptions when reading from JAR file, should probably throw an exception
+ * [FELIX-894] - Loosen locking when starting/stopping/uninstalling a bundle by firing event without holding a lock
+ * [FELIX-908] - Unsynchronize access to bundle state inside BundleInfo by making the variable volatile
+
+Changes from 1.4.0 to 1.4.1
+---------------------------
+
+* [2008-12-19] Refactor the URLHandlers implementation to fix a possible
+ Linkage-Error when running embedded inside tomcat. Furthermore, make it possible
+ to dynamically set a SecurityManager, change the url we add to the framework
+ classloader to fix issues with rmi and make sure we restore the previous URLStreamHandlerFactory
+ after stopping. (FELIX-842, FELIX-837, FELIX-844, FELIX-827)
+* [2008-12-19] Add missing javax.security.cert in JRE 1.4 and 1.5. (FELIX-854)
+* [2008-12-19] Improve framework internal locking protocol.
+* [2008-12-18] Fixed an issue where bundles with a non-existing native library
+ would not be removed correctly. (FELIX-835)
+* [2008-11-21] Throw an exception when there is an attempt to start or stop a
+ fragment, as per the spec. (FELIX-820)
+* [2008-11-20] Fixed a bug during shutdown where uninstalled fragments are not
+ properly closed. (FELIX-819)
+* [2008-11-14] Added partial support for new service registry hooks as proposed
+ for OSGi R4.2; currently, only listener hooks are supported. (FELIX-804)
+* [2008-11-08] Fixed Felix' delegation hack so that it correctly delegates to
+ the parent class loader for resources as appropriate; previously it was always
+ delegating for class loading, which was incorrect. (FELIX-808)
+
+Changes from 1.2.2 to 1.4.0
+---------------------------
+
+* [2008-11-05] URLStreamHandlerService and ContentHandlerService override
+ built-in handlers and make it possible to use URLHandlers when extending the
+ Felix class. (FELIX-756, FELIX-800)
+* [2008-11-04] Implement ServiceReference.compareTo() method. (FELIX-799)
+* [2008-10-31] Fix some visibility issues in the LDAP operators which could
+ result in incorrect toString values. (FELIX-765)
+* [2008-10-31] Fixed spec compliance issues around getting a service reference
+ from an invalid registration and throwing an exception when there are
+ duplicate property keys. (FELIX-798)
+* [2008-10-21] Fixed an issue with extension bundles which would be installed
+ as fragments and fail to install extension bundles if they have incomplete
+ metadata. (FELIX-770)
+* [2008-10-21] Fix a possible deadlock in URLHandlers. (FELIX-748)
+* [2008-10-16] Modified framework to have default values for the system
+ packages property, which also required modifying main to no longer expect to
+ set it. Now it is possible to start Felix with no configuration properties.
+ (FELIX-753)
+* [2008-10-16] Update felix to work with the 1.0.0-rc1 version of the android
+ sdk.
+* [2008-10-15] Implemented remaining PackageAdmin methods from R4. (FELIX-35)
+* [2008-10-15] Modified resolver to correctly mark fragment modules as resolved.
+ (FELIX-777)
+* [2008-10-15] Modified the resolver to longer consider uninstalled fragments
+ and hosts when resolving dependencies; this required a new "stale" flag on
+ modules that gets set when their associated bundle is uninstalled. (FELIX-776)
+* [2008-10-15] Modified the resolver to sort candidates when resolving
+ Require-Bundle dependencies. (FELIX-775)
+* [2008-10-14] Modified ExportedPackage.getImportingBundles() to include
+ bundles requiring the exporting bundle, in addition to those bundles
+ importing the package. Also tried to simplify dependency management code
+ by separating it out. (FELIX-764)
+* [2008-10-14] Fix a NullPointerException in SecureAction when a
+ SecurityManager is used by keeping pointers on the local stack. (FELIX-766)
+* [2008-10-13] Use System.gc to allow to update and uninstall bundles with
+ native libs on Windows. (FELIX-733)
+* [2008-10-10] Set the activator to null on Bundle.stop() to allow for earlier
+ garbage collection. (FELIX-762)
+* [2008-10-10] Implements support for flushing the cache on framework
+ initialization. (FELIX-755)
+* [2008-10-10] Improve exception messages. (FELIX-750)
+* [2008-10-09] Modified the bundle cache to no longer have profiles. (FELIX-754)
+* [2008-10-08] Modified the Felix API to aligned with the proposed standard
+ OSGi framework API. The framework instance can now be stopped and restarted.
+ (FELIX-753)
+* [2008-09-29] Support transiently starting/stopping bundles. (FELIX-713)
+* [2008-09-25] Correctly discard exported packages when a bundle is chosen to
+ import a package it exports. (FELIX-736)
+* [2008-09-24] Clearly distinguish between "resolved" and "unresolved"
+ capabilities, which is necessary since "resolved" capabilities have higher
+ priority than "unresolved" ones. (FELIX-730)
+* [2008-09-24] Do not bootdelegate in the case where Bundle.loadClass() has
+ been used. (FELIX-712)
+* [2008-09-23] Improve decoding of reference URLs. (FELIX-731)
+* [2008-09-23] For completeness, added symbolic names to framework and main.
+* [2008-09-17] Improve gc by fixing an issue with StartLevel and PackageAdmin.
+ (FELIX-728)
+* [2008-09-15] Fix an issue with Require-Bundle not aggregating packages
+ correctly. (FELIX-722)
+* [2008-09-15] Fixed a bug where class loader delegation for dynamic imports
+ was happening when it shouldn't. (FELIX-724)
+* [2008-09-12] Added a configuration property to determine whether installing a
+ fragment that uses unimplemented features throws an exception or logs a
+ warning. (FELIX-725)
+* [2008-09-12] Removed some experimental code for "implicit requirements",
+ since it was no longer needed.
+* [2008-09-12] Fix some visibility issues within the LDAP filter. (FELIX-721)
+
+Changes from 1.2.1 to 1.2.2
+---------------------------
+
+* [2008-10-14] Fixed a NullPointer exception that could happen when
+ running with a SecurityManager as a backport of FELIX-766.
+
+Changes from 1.2.0 to 1.2.1
+---------------------------
+
+* [2008-09-05] Fixed a performance regression that was caused by uncached
+ access to the bundle manifest headers. (FELIX-711)
+* [2008-09-03] Fixed a bug in calculating the system bundle's exported
+ packages which added a null export package.
+
+Changes from 1.0.4 to 1.2.0
+---------------------------
+
+* [2008-08-29] Support JAR-wide manifest package metadata. (FELIX-682)
+* [2008-08-29] Throw an exception when installing a fragment that uses
+ features that we do not support.
+* [2008-08-20] Improve error reporting when loading bundle classes using
+ Bundle.loadClass.
+* [2008-08-16] Fix attribute checking when resolving dynamic imports.
+ (FELIX-676)
+* [2008-08-08] Implement singleton bundle support. (FELIX-102)
+* [2008-08-06] Default to current security policy if no security extension is
+ installed in order to make Subject.doAs work. (FELIX-654)
+* [2008-08-04] Return Bundle.getLastModified() for bundle URLs
+ lastModified(). (FELIX-582)
+* [2008-08-04] Improve handling of improper resource URLs. (FELIX-577)
+* [2008-08-01] Add necessary stub methods to implement new R4.1 methods.
+ (FELIX-595)
+* [2008-08-01] Applied patch to properly return symbolic name when it has
+ parameters. (FELIX-650)
+* [2008-07-25] Fix some rollback issues after a bundle update throws an
+ exception. (FELIX-647)
+* [2008-07-23] Modified manifest parser to be more lenient. (FELIX-641)
+* [2008-07-07] Add support for the standard symbolic name for the system
+ bundle. (FELIX-602)
+* [2008-06-01] Add initial fragment support for extending the host bundle
+ class path. (FELIX-29, FELIX-656)
+
+Changes from 1.0.3 to 1.0.4
+___________________________
+
+* [2008-04-18] Check that the returned object from a service factory is an
+ instance of all classes named when the service was registered. (FELIX-540)
+* [2008-04-13] Fix an issue when logging messages while holding framework
+ internal locks that could lead to a deadlock. For now we just disable
+ logging to log services inside the framework. (FELIX-536)
+* [2008-04-13] Implemented various small performance improvments e.g.,
+ we now cache filters and create an index for objectclass to improve
+ service lookup performance and don't use the BundleInfo to get the
+ bundle id but the BundleImpl directly. Furthermore, we added an index to
+ get bundles by id.
+* [2008-04-04] Fix an NoClassDefFoundError when trying to query the
+ framework classloader for whether a class is available or not.
+* [2008-03-19] Don't try to resolve extension bundles and fix a
+ classcastexception that could happen if more then one framework is around
+ and both have extensions installed. Furthermore, make extension bundles
+ use the system bundle context.
+* [2008-03-07] Bundle.getResource does now check for AdminPermission.
+ (FELIX-150)
+* [2008-03-06] Make urlhandlers work when a handler factory is already set.
+ Furthermore, it is now possible to have more then one framework running
+ in more then one classloader. (FELIX-38).
+* [2008-03-05] Make LDAP filter reentrant.
+* [2008-02-29] Refactored the IContent abstraction from the module loader
+ layer to provide more generic access to the content of the module. This
+ makes it possible that a bundle's class path could span multiple module's,
+ which will be necessary for fragments. (FELIX-29)
+* [2008-02-27] Applied a patch to disable the class loading diagnostic message
+ when the logger is not at the DEBUG level. (FELIX-500)
+* [2008-02-15] Modified the service registry to use more fine-grained locking
+ to avoid callbacks to service factories while holding locks. (FELIX-489)
+
+Changes from 1.0.1 to 1.0.3
+---------------------------
+
+* [2008-01-27] Moved framework docs to main, since the launcher examples now
+ depend on main for the auto-property handling.
+* [2008-01-25] Applied patches to improve how Felix finds resources when
+ getResources() is called. (FELIX-466, FELIX-467)
+* [2008-01-25] Make FilterImpl.toString() add escape characters where needed.
+ (FELIX-471)
+* [2008-01-16] Fix a NPE on framework restart when extension bundles are
+ installed.
+* [2008-01-15] Try to fix a potential visibility issue on loading a class
+ form a bundle where it seems to be possible that we create two classloaders
+ instead of one.
+* [2008-01-15] Modified boot delegation to not terminate when delegating to
+ parent class loader for non-java.* packages. (FELIX-463)
+* [2008-01-04] Fix some issues related to directories on the bundle class
+ path. Specifically, leading slashes created an issue and are now stripped
+ and entries were not being properly filtered when enumerating the contents
+ of a class path directory. (FELIX-426)
+* [2007-12-20] Modified logger to have all of its public methods be final to
+ avoid it from being extended in undesired ways via the constructor supplied
+ logger. (FELIX-428)
+* [2007-12-20] The TCK has changed to verify that bundles do not depend on
+ themselves, so we filter that case now.
+* [2007-12-20] Applied patch from Guillaume Nodet to properly fire a framework
+ error event only when a bundle cannot be resolved. (FELIX-441)
+* [2007-12-19] Modified framework to accept a Logger instance so that host
+ applications can do custom logging until the log service arrives. (FELIX-428)
+* [2007-12-19] Add support for loading bundles on Google Android (FELIX-440).
+* [2007-12-18] Improve native code loading - bundle installation will now
+ fail in case a native library is not in the jar and we only use the first
+ library of a given name. Furthermore, we now support .dylib extensions on
+ the mac as well as others; should make it possible to use .netmodules as
+ well. (FELIX-439)
+* [2007-12-17] Make the win32 alias match any version of windows for native
+ clauses. (FELIX-438)
+* [2007-12-14] Removed auto-property processing out of the framework and
+ into the default launcher, i.e, main. (FELIX-393)
+* [2007-12-13] Fix a StackOverflowError in URLHandlers.createStreamHandler()
+ when creating URL on jamvm and Mika. This patch resolves an unfortunate
+ interaction between our ExtensionManager and the URLHandlers by making the
+ URLHandlers aware of the extension protocol. Pretty much like we do already
+ for the bundle protocol. (FELIX-435)
+* [2007-11-26] Fix a small oversight in the extension manager that could lead
+ to a null pointer exception and save some memory by creating less objects.
+* [2007-11-26] Degrate to version 0.0.0 if we can not find the Felix.properties
+ for some reason and avoid a null pointer in this case.
+* [2007-11-08] Reorganized usage count methods to better handle null
+ reference checking in response to Karl Pauls seeing an NPE when trying to
+ get a service that was already unregistered while shutting down the
+ framework.
+* [2007-11-06] Added a simple check to detect and work around a bug in J9.
+ (FELIX-416)
+* [2007-10-30] Change how the extension manager url stream handler handles
+ request to the root path in order to make some tomcat issue go away.
+ (FELIX-414)
+* [2007-10-26] Added support for "/" bundle resources as requested. (FELIX-383)
+* [2007-10-24] Use system bundle when firing a framework error event when an
+ install error occurs.
+* [2007-10-22] Fix a NPE when getEntryPaths is called on the system bundle.
+ (FELIX-394)
+* [2007-10-16] Modifies bundle resource URL handling such that if a resource
+ URL points to a resource that does not exist, a bundle class path search
+ for the resource will be instigated and if any matching resource is found,
+ that one will be used instead. (FELIX-383)
+* [2007-10-10] Auto-property handling now installs bundles into the default
+ bundle start level if a start level is not specified. (FELIX-359)
+* [2007-10-08] Overwrite the URLStreamHandler.getHostAddress(URL) in the
+ ExtensionManager to immediately return null to prevent DNS lookup.
+ (FELIX-388)
+* [2007-09-30] Resolved a concurrency issue that could result in the same
+ bundle being resolved more than once; also tried to simplify locking in
+ the core search policy implementation. (FELIX-381)
+
+Changes from 1.0.0 to 1.0.1
+---------------------------
+
+* [2007-07-23] Fixed a bug in the framework shutdown process which was
+ causing threads calling Felix.stopAndWait() to not get notified that
+ the framework had shutdown. (FELIX-329)
+* [2007-08-15] Fixed a bug in the LDAP filter which was not thread safe
+ on execution. (FELIX-338)
+* [2007-08-17] Added support for persistent last used bundle ID to avoid
+ re-use of bundle identifiers. (FELIX-339)
+* [2007-08-23] Modified BundleImpl.getHeaders(Locale) to accept a null
+ locale. (FELIX-346)
+* [2007-09-11] Added support to handle external termination of Felix
+ which was not handled or detected and prevented a restart of future
+ Felix instances in the same VM. (FELIX-363)
+* [2007-09-12] Add support for Collection values in the LDAP filter to
+ match the 4.1 spec.
+* [2007-09-12] Fixed a bug in the LDAP filter where attributes where
+ limited to [a-zA-Z ] so didn't allow for e.g., numbers. (FELIX-361)
+* [2007-09-13] Enable support for exporting the same package more than
+ once (FELIX-101).
+* [2007-09-13] Returns the system bundle from a call to
+ PackageAdmin.getBundle(Class) in case the class comes from the
+ classloader (or one of its parents) that loaded Felix and the system
+ bundle exports the package.
+* [2007-09-16] Fixed a bug in class space filtering in the service registry
+ that could result in class cast exceptions for service clients.
+* [2007-09-16] Fixed a bug that prevented extension bundle exports to be
+ usable.
+
+Changes from 0.8.0-incubator to 1.0.0
+-------------------------------------
+
+* [2007-01-18] Added support for bundle header localization. (FELIX-27)
+* [2007-01-22] Modified framework resolver to support a generic
+ capability/requirement model.
+* [2007-01-22] Reorganized and centralized manifest parsing code and added
+ support for resolver's generic capability/requirement model. (FELIX-98)
+* [2007-01-22] Improved native library naming normalization. (FELIX-26)
+* [2007-01-23] No longer eagerly resolving classes loaded from modules
+ since this was causing verification errors with IBM J9.
+* [2007-01-25] Added some support for execution environment checking.
+ (FELIX-23)
+* [2007-01-29] Added support for getAllServiceReferences(). (FELIX-32)
+* [2007-01-31] Added Require-Bundle support to resolve using the generic
+ capability/requirement model of the resolver. (FELIX-28)
+* [2007-02-05] Fixed a bug in processor type normalization for x86-64
+ processors.
+* [2007-02-09] The resolver previously ignored packages that were pending
+ removal when resolving new bundles, now it does not.
+* [2007-02-09] Bundles are automatically refreshed when updated/uninstalled
+ if none of their exported packages are in use.
+* [2007-02-13] Added support for extension bundles. (FELIX-30)
+* [2007-03-02] Added a Bundle.getBundleContext() method until actual
+ support for OSGi R4.1.
+* [2007-04-26] Modified Bundle.findEntries() to return URLs to directory
+ entries as well as file entries.
+* [2007-05-06] Modified LDAP evaluator to special case the fact that
+ BigDecimal is not available in Foundation profile.
+* [2007-05-21] Made some performance improvements in LDAP evaluation.
+* [2007-05-22] Modified JAR file to include Service Tracker package.
+* [2007-05-22] Improved concurrency handling around checking for already
+ loaded classes and defining classes.
+* [2007-06-05] Modified resource URLs to use port number rather than
+ prepend information to the resource path.
+* [2007-06-13] Improved dynamic imports to cycle through all available
+ candidates when checking for class space consistency.
+* [2007-06-18] Improved service registry filtering based on class versions
+ to allow a bundle to register a service for a different version of class
+ that it can access.
+* [2007-06-21] Modified our "last ditch effort" to guess when to delegate
+ to the system bundle to make it a little more robust.
+* [2007-06-29] Fixed a bug in EventDispatcher that was causing asynchronous
+ events to not be fired after stopping the framework instance and creating
+ a new instance. (FELIX-314)
+* [2007-07-03] Fixed a bug in EventDispatcher that would not correctly
+ update a listener when it implemented multiple listener interfaces.
+* [2007-07-04] Modified Felix framework class to implement the Bundle
+ interface to improve the startup/shutdown sequence and to provide a
+ simplified API for creating framework instances.
+* [2007-07-11] Removed the PropertyResolver-related classes and now only
+ use Maps for configuration properties. (FELIX-324)
diff --git a/main.distribution/doc/changelog_main.txt b/main.distribution/doc/changelog_main.txt
new file mode 100644
index 0000000..e2b00e6
--- /dev/null
+++ b/main.distribution/doc/changelog_main.txt
@@ -0,0 +1,139 @@
+Changes from 2.0.2 to 2.0.3
+---------------------------
+
+** Improvement
+ * Update to latest framework version 2.0.3
+
+Changes from 2.0.1 to 2.0.2
+---------------------------
+
+** Improvement
+ * Update to latest framework version 2.0.2
+
+Changes from 2.0.0 to 2.0.1
+---------------------------
+
+** Improvement
+ * Update to latest framework version 2.0.1
+
+Changes from 1.8.1 to 2.0.0
+---------------------------
+
+** Improvement
+ * Update to latest framework version 2.0.0
+
+Changes form 1.6.1 to 1.8.0
+---------------------------
+
+** Improvement
+ * Update to latest framework version 1.8.0
+
+Changes from 1.6.0 to 1.6.1
+---------------------------
+
+** Improvement
+ * Update to latest framework version 1.6.1
+
+Changes from 1.4.1 to 1.6.0
+---------------------------
+
+** Improvement
+ * Update to latest framework version 1.6.0
+
+Changes from 1.4.0 to 1.4.1
+---------------------------
+
+* [2008-12-20] Update to latest framework version 1.4.0
+* [2008-11-18] Modified the pom file to export the OSGi packages; this can be
+ helpful for tools trying to determine what the JAR file provides.
+* [2008-11-07] Align log level property name in pom.xml and config.properties
+
+Changes from 1.2.2 to 1.4.0
+---------------------------
+
+* [2008-10-31] Fixed a possible NPE when no configuration file is found.
+* [2008-10-23] Change the name of the SystemBundle interface to be Framework.
+ (FELIX-753)
+* [2008-10-22] Hide wire messages in felix releases. (FELIX-707)
+* [2008-10-16] Modified framework to have default values for the system packages
+ property. Now it is really possible to start Felix with no configuration
+ properties. (FELIX-753)
+* [2008-10-10] Implements support for flushing the cache on framework
+ initialization. (FELIX-755)
+* [2008-10-09] Modified the bundle cache to no longer have profiles. (FELIX-754)
+* [2008-10-08] Modified the Felix API to aligned with the proposed standard OSGi
+ framework API. (FELIX-753)
+* [2008-09-23] Added symbolic names to framework and main.
+* [2008-09-12] Added a configuration property to determine whether installing a
+ fragment that uses unimplemented features throws an exception or logs a
+ warning. (FELIX-725)
+
+Changes form 1.2.1 to 1.2.2
+---------------------------
+
+* [2008-10-14] Update to latest framework version 1.2.2.
+
+Changes from 1.2.0 to 1.2.1
+---------------------------
+
+* [2008-09-07] Hide WIRE log messages. (FELIX-707)
+* [2008-09-07] Use the new Felix releases obr repository URL.
+ (FELIX-708)
+
+Changes from 1.0.3 to 1.2.0
+---------------------------
+
+* [2008-08-03] Change to the R4.1 version of the spec. (FELIX-514)
+* [2008-05-08] Fixed a NPE. (FELIX-525)
+
+Changes from 1.0.3 to 1.0.4
+---------------------------
+
+* [2008-04-22] Update to framework version 1.0.4.
+
+Changes from 1.0.1 to 1.0.3
+---------------------------
+
+* [2008-01-27] Added launching and embedding docs to main project.
+* [2008-01-22] Update to maven-bundle-plugin version 1.2.0.
+* [2008-01-07] Modifed default launcher in Main to separate out
+ auto-property processing so that it is easier to reuse the code in
+ custom launchers. (FELIX-448)
+* [2007-12-14] Removed auto-property processing out of the framework and
+ into the default launcher. (FELIX-393)
+* [2007-10-16] Use variable substitution via BND to define the properties
+ in default.properties from the properties in config.properties.
+ (FELIX-380)
+* [2007-10-03] Added support to the Main launcher to use a default
+ embedded resource for setting the framework configuration properties
+ if the actual config.properties file cannot be loaded. (FELIX-380)
+* [2007-09-20] Remove some packages for jre1.3 profile and add/remove a
+ few for 1.4, 1.5, and 1.6 (javax.crypto.*). (FELIX-371)
+
+
+Changes from 1.0.0 to 1.0.1
+---------------------------
+
+* [2007-09-16] Update to framework version 1.0.1.
+
+
+Changes from 0.8.0-incubator to 1.0.0
+-------------------------------------
+
+* [2007-01-31] Changed how the system packages property is calculated to
+ make it more robust; previously it was leaving a dangling comma if the
+ execution platform was not known.
+* [2007-02-05] Added system package support for Java 6. (FELIX-201)
+* [2007-02-13] Removed support for trusted certificate authorities; this
+ will be added later as an extension.
+* [2007-03-16] Felix configuration properties can now be set as system
+ properties when using the standard launcher. (FELIX-250)
+* [2007-03-28] No longer including config.properties in the JAR file.
+* [2007-04-13] The javax.net and javax.net.ssl packages were missing
+ from the system packages properties.
+* [2007-04-13] Fixed a bug where the launcher was not correctly calculating
+ the installation directory correctly.
+* [2007-05-07] Was accidentally including OBR service interface package
+ in main JAR.
+* [2007-05-22] Now includes the Service Tracker package in main JAR.
+* [2007-07-04] Modified to use the new Felix embedding API.
diff --git a/main.distribution/doc/changelog_shell.tui.txt b/main.distribution/doc/changelog_shell.tui.txt
new file mode 100644
index 0000000..dc1a7ee
--- /dev/null
+++ b/main.distribution/doc/changelog_shell.tui.txt
@@ -0,0 +1,31 @@
+Changes from 1.2.0 to 1.4.0
+---------------------------
+
+** Bug
+ * [FELIX-619] - Shell.TUI causes "new java.io.ServerSocket()" to hang
+ * [FELIX-1137] - [PATCH] Shell TUI pom has incorrect Bundle-DocURL tag
+
+** Improvments
+ * Update to shell 1.4.0
+
+Changes from 1.0.2 to 1.2.0
+---------------------------
+
+** Bug
+ * [FELIX-729] - Shell-TUI causes 100% CPU load when using javaw launcher
+
+Changes from 1.0.1 to 1.0.2
+---------------------------
+
+* [2008-08-12] Added OBR descriptor and updated to bundle plugin version
+ 1.4.3. (FELIX-669)
+
+Changes from 1.0.0 to 1.0.1
+---------------------------
+
+* [2008-04-21] Re-release to make bytecode executable on jre 1.3.
+
+Changes from 0.8.0-incubator to 1.0.0
+-------------------------------------
+
+* None.
diff --git a/main.distribution/doc/changelog_shell.txt b/main.distribution/doc/changelog_shell.txt
new file mode 100644
index 0000000..1026d54
--- /dev/null
+++ b/main.distribution/doc/changelog_shell.txt
@@ -0,0 +1,52 @@
+Changes form 1.2.0 to 1.4.0
+---------------------------
+
+** Bug
+ * [FELIX-1019] - New shell commands "requirers" and "exports" do not handle invalid bundle case properly
+
+** Improvement
+ * [FELIX-1058] - [PATCH] Add a "find" command to the shell
+ * [FELIX-1145] - Modify help shell command to avoid issues with long command descriptions
+ * [FELIX-1151] - Improve naming and consistency of shell commands for inspecting dependencies
+
+** New Feature
+ * [FELIX-1052] - Add log shell command
+ * [FELIX-1181] - Add support for activation policy in shell "start" command
+ * [FELIX-1510] - There is no command to set the initial bundle start level
+
+Changes from 1.0.2 to 1.2.0
+---------------------------
+
+** Bug
+ * [FELIX-703] - Cannot install ShellGUIPlugin with OBR
+
+** Improvement
+ * [FELIX-669] - Shell & Shell TUI OBR descriptions
+ * [FELIX-1008] - Rename "packages" command to "exports" to match better with new "imports" command
+
+** New Feature
+ * [FELIX-741] - Modify shell start/stop commands to support transient starting/stopping of bundles
+ * [FELIX-1006] - Add command to shell to list a bundles imported packages
+ * [FELIX-1009] - Add requires/requirers commands to shell
+
+Changes from 1.0.1 to 1.0.2
+---------------------------
+
+* [2008-08-12] Added OBR descriptor and updated to bundle plugin version
+ 1.4.3. (FELIX-669)
+* [2008-05-08] Modified "update" command to not append ".jar" to URLs and
+ modified the "install" command to use the same code. (FELIX-544)
+
+Changes from 1.0.0 to 1.0.1
+---------------------------
+
+* [2008-04-21] Re-release to make bytecode executable on jre 1.3.
+
+Changes from 0.8.0-incubator to 1.0.0
+-------------------------------------
+
+* [2006-12-15] Changed the symbolic name, since it was being calculated
+ incorrectly.
+* [2007-05-03] Modified 'ps' so that it displays reasonable defaults if
+ headers are missing. Also added ability to display symbolic name.
+* [2007-06-14] Modified refresh command to accept bundle IDs.
diff --git a/main.distribution/pom.xml b/main.distribution/pom.xml
new file mode 100644
index 0000000..53d5928
--- /dev/null
+++ b/main.distribution/pom.xml
@@ -0,0 +1,138 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+ <parent>
+ <groupId>org.apache.felix</groupId>
+ <artifactId>felix-parent</artifactId>
+ <version>1.2.0</version>
+ <relativePath>../pom/pom.xml</relativePath>
+ </parent>
+ <modelVersion>4.0.0</modelVersion>
+ <packaging>pom</packaging>
+ <name>Apache Felix Main Distribution</name>
+ <artifactId>org.apache.felix.main.distribution</artifactId>
+ <version>2.1.0-SNAPSHOT</version>
+ <dependencies>
+ <dependency>
+ <groupId>${pom.groupId}</groupId>
+ <artifactId>org.apache.felix.framework</artifactId>
+ <version>${framework.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>${pom.groupId}</groupId>
+ <artifactId>org.apache.felix.shell</artifactId>
+ <version>${shell.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>${pom.groupId}</groupId>
+ <artifactId>org.apache.felix.shell.tui</artifactId>
+ <version>${shell.tui.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>${pom.groupId}</groupId>
+ <artifactId>org.apache.felix.bundlerepository</artifactId>
+ <version>${obr.version}</version>
+ </dependency>
+ </dependencies>
+ <properties>
+ <framework.version>2.0.3</framework.version>
+ <shell.version>1.4.2</shell.version>
+ <shell.tui.version>1.4.1</shell.tui.version>
+ <obr.version>1.4.3</obr.version>
+ </properties>
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-dependency-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>copy</id>
+ <phase>generate-resources</phase>
+ <goals>
+ <goal>copy</goal>
+ </goals>
+ <configuration>
+ <artifactItems>
+ <artifactItem>
+ <groupId>${pom.groupId}</groupId>
+ <artifactId>org.apache.felix.shell</artifactId>
+ <version>${shell.version}</version>
+ <type>jar</type>
+ <overWrite>true</overWrite>
+ <outputDirectory>${project.basedir}/bundle</outputDirectory>
+ </artifactItem>
+ <artifactItem>
+ <groupId>${pom.groupId}</groupId>
+ <artifactId>org.apache.felix.shell.tui</artifactId>
+ <version>${shell.tui.version}</version>
+ <type>jar</type>
+ <overWrite>true</overWrite>
+ <outputDirectory>${project.basedir}/bundle</outputDirectory>
+ </artifactItem>
+ <artifactItem>
+ <groupId>${pom.groupId}</groupId>
+ <artifactId>org.apache.felix.bundlerepository</artifactId>
+ <version>${obr.version}</version>
+ <type>jar</type>
+ <overWrite>true</overWrite>
+ <outputDirectory>${project.basedir}/bundle</outputDirectory>
+ </artifactItem>
+ <artifactItem>
+ <groupId>${pom.groupId}</groupId>
+ <artifactId>org.apache.felix.main</artifactId>
+ <version>${framework.version}</version>
+ <type>jar</type>
+ <overWrite>true</overWrite>
+ <outputDirectory>${project.basedir}/bin</outputDirectory>
+ <destFileName>felix.jar</destFileName>
+ </artifactItem>
+ </artifactItems>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ <plugin>
+ <artifactId>maven-assembly-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>assemble</id>
+ <phase>package</phase>
+ <goals>
+ <goal>single</goal>
+ </goals>
+ <configuration>
+ <descriptors>
+ <descriptor>assembly.xml</descriptor>
+ </descriptors>
+ <appendAssemblyId>false</appendAssemblyId>
+ <finalName>felix-framework-${framework.version}</finalName>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ <resources>
+ <resource>
+ <directory>src/main/resources</directory>
+ <filtering>true</filtering>
+ </resource>
+ </resources>
+ </build>
+</project>
