Author: buildbot
Date: Tue Mar 10 21:03:25 2015
New Revision: 943247
Log:
Staging update by buildbot for felix
Added:
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/annotations.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/background.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/bundles-and-dependencies.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/design-patterns.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/development.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/diagrams/
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/diagrams/adapter.png
(with props)
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/diagrams/adapter.uxf
(with props)
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/diagrams/aspect.png
(with props)
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/diagrams/aspect.uxf
(with props)
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/diagrams/resourceadapter.png
(with props)
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/diagrams/resourceadapter.uxf
(with props)
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/diagrams/resources.png
(with props)
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/diagrams/resources.uxf
(with props)
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/diagrams/singleton.png
(with props)
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/diagrams/singleton.uxf
(with props)
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/history.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/javadocs.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/migrating-from-earlier-versions.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/migrating-from-other-solutions.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/performance-tuning.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/resources.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/whatsnew.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/component-adapter.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/component-aspect.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/component-bundle-adapter.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/component-factory-configuration-adapter.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/component-resource-adapter.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/component-singleton.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/components.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/dependencies.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-bundle.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-configuration.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-resource.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/dependency-service.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/diagrams/
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/diagrams/concurrent-serial-queue.png
(with props)
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/diagrams/serial-queue.png
(with props)
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/diagrams/statediagram.png
(with props)
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/diagrams/statediagram.uxf
(with props)
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/external-links.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/reference/thread-model.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/tutorials/
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/tutorials/getting-started.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/tutorials/leveraging-the-shell.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/tutorials/working-with-annotations.html
Removed:
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4.html
Modified:
websites/staging/felix/trunk/content/ (props changed)
websites/staging/felix/trunk/content/documentation/subprojects.html
websites/staging/felix/trunk/content/index.html
websites/staging/felix/trunk/content/sitemap.html
Propchange: websites/staging/felix/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Tue Mar 10 21:03:25 2015
@@ -1 +1 @@
-1665693
+1665695
Modified: websites/staging/felix/trunk/content/documentation/subprojects.html
==============================================================================
--- websites/staging/felix/trunk/content/documentation/subprojects.html
(original)
+++ websites/staging/felix/trunk/content/documentation/subprojects.html Tue Mar
10 21:03:25 2015
@@ -72,7 +72,7 @@
<li><a href="/documentation/subprojects/apache-felix-autoconf.html">Apache
Felix Auto Configuration</a></li>
<li><a href="/documentation/subprojects/apache-felix-commons.html">Apache
Felix Commons</a></li>
<li><a href="/documentation/subprojects/apache-felix-config-admin.html">Apache
Felix Configuration Admin Service</a></li>
-<li><a
href="/documentation/subprojects/apache-felix-dependency-manager-4.html">Apache
Felix Dependency Manager 4</a></li>
+<li><a
href="/documentation/subprojects/apache-felix-dependency-manager.html">Apache
Felix Dependency Manager 4</a></li>
<li><a
href="/documentation/subprojects/apache-felix-deployment-admin.html">Apache
Felix Deployment Admin</a></li>
<li><a href="/documentation/subprojects/apache-felix-event-admin.html">Apache
Felix Event Admin</a></li>
<li><a href="/documentation/subprojects/apache-felix-file-install.html">Apache
Felix File Install</a></li>
Added:
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager.html
==============================================================================
---
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager.html
(added)
+++
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager.html
Tue Mar 10 21:03:25 2015
@@ -0,0 +1,136 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd";>
+<html>
+<!--
+
+ 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.
+-->
+ <head>
+ <title>Apache Felix - Apache Felix Dependency Manager 4</title>
+ <link rel="icon" href="/res/favicon.ico">
+ <link rel="stylesheet" href="/res/site.css" type="text/css" media="all">
+ <link rel="stylesheet" href="/res/codehilite.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/";>
+ <img border="0" alt="Apache Felix" src="/res/logo.png">
+ </a>
+ </div>
+ <div class="header">
+ <a href="http://www.apache.org/";>
+ <img border="0" alt="Apache" src="/res/apache.png">
+ </a>
+ </div>
+ </div>
+
+ <div class="menu">
+ <p><a href="/news.html">news</a> <br />
+<a href="/license.html">license</a> <br />
+<a href="/downloads.cgi">downloads</a> <br />
+<a href="/documentation.html">documentation</a> <br />
+<a href="/mailinglists.html">mailing lists</a> <br />
+<a href="/documentation/community/contributing.html">contributing</a> <br />
+<a href="/sitemap.html">site map</a> <br />
+<a href="http://www.apache.org/";>asf</a> <br />
+<a href="http://www.apache.org/security/";>security</a> <br />
+<a href="http://www.apache.org/foundation/sponsorship.html";>sponsorship</a>
<br />
+<a href="http://www.apache.org/foundation/thanks.html";>sponsors</a> </p>
+<iframe
+ src="http://www.apache.org/ads/button.html";
+ style="border-width:0; float: left"
+ frameborder="0"
+ scrolling="no"
+ width="135"
+ height="135">
+</iframe>
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a
href="/documentation.html">Documentation</a> » <a
href="/documentation/subprojects.html">Apache Felix Subproject Documentation</a>
+ </div>
+
+
+
+ <h1>Apache Felix Dependency Manager 4</h1>
+ <p>Welcome to the Dependency Manager, a great bundle for managing your
components and dependencies!</p>
+<h2 id="introduction">Introduction</h2>
+<p>In a service oriented architecture, applications are built out of
components that are packaged in bundles and interact through services. These
components, that both publish services and depend on other services, form
networks that are often dynamic in nature. That makes managing these
dependencies something the developer needs to address.</p>
+<p>Whilst the OSGi framework provides the low-level building blocks to do that
in the form of service listeners and trackers, these should not be used
directly by developers. Instead, a more declarative approach works best, and
the Dependency Manager provides this in the form of a declarative API and/or
annotations that allow you to dynamically declare and change dependencies.</p>
+<p>On top of that, a set of OSGi design patterns are defined and supported
that can be used as building blocks for more complex applications.</p>
+<p>The documentation for the dependency manager is split into three
sections:</p>
+<ol>
+<li>Step-by-step tutorials which provide a good introduction to the technology
and should get you started quickly.</li>
+<li>Overviews and guides that provide more in-depth knowledge about specific
aspects of the dependency manager.</li>
+<li>Reference materials that describe all the individual nuts and bolts.</li>
+</ol>
+<p>Below is the full table of contents.</p>
+<h2 id="table-of-contents">Table of Contents</h2>
+<h3 id="step-by-step-tutorials">Step-by-step Tutorials</h3>
+<ul>
+<li><a
href="apache-felix-dependency-manager-4/tutorials/getting-started.html">Getting
started</a></li>
+<li><a
href="apache-felix-dependency-manager-4/tutorials/working-with-annotations.html">Working
with annotations</a></li>
+<li><a
href="apache-felix-dependency-manager-4/tutorials/leveraging-the-shell.html">Leveraging
the shell</a></li>
+</ul>
+<h3 id="overviews-and-guides">Overviews and Guides</h3>
+<ul>
+<li><a
href="apache-felix-dependency-manager-4/guides/history.html">History</a></li>
+<li><a
href="apache-felix-dependency-manager-4/guides/background.html">Background</a></li>
+<li><a href="apache-felix-dependency-manager-4/guides/whatsnew.html">What's
new in version 4</a></li>
+<li><a
href="apache-felix-dependency-manager-4/guides/bundles-and-dependencies.html">Bundles
and dependencies</a></li>
+<li><a
href="apache-felix-dependency-manager-4/guides/migrating-from-earlier-versions.html">Migrating
from earlier versions</a></li>
+<li><a
href="apache-felix-dependency-manager-4/guides/migrating-from-other-solutions.html">Migrating
from other solutions</a></li>
+<li><a
href="apache-felix-dependency-manager-4/guides/annotations.html">Annotations</a></li>
+<li><a
href="apache-felix-dependency-manager-4/guides/performance-tuning.html">Performance
Tuning</a></li>
+<li><a
href="apache-felix-dependency-manager-4/guides/development.html">Development</a></li>
+<li><a
href="apache-felix-dependency-manager-4/guides/design-patterns.html">Design
Patterns</a></li>
+<li><a
href="apache-felix-dependency-manager-4/guides/resources.html">Resources</a></li>
+<li><a
href="apache-felix-dependency-manager-4/guides/javadocs.html">Javadocs</a></li>
+</ul>
+<h3 id="reference-guide">Reference Guide</h3>
+<ul>
+<li><a
href="apache-felix-dependency-manager-4/reference/components.html">Components</a><ul>
+<li><a
href="apache-felix-dependency-manager-4/reference/component-singleton.html">Singleton</a></li>
+<li><a
href="apache-felix-dependency-manager-4/reference/component-aspect.html">Aspect</a></li>
+<li><a
href="apache-felix-dependency-manager-4/reference/component-adapter.html">Adapter</a></li>
+<li><a
href="apache-felix-dependency-manager-4/reference/component-resource-adapter.html">Resource
Adapter</a></li>
+<li><a
href="apache-felix-dependency-manager-4/reference/component-bundle-adapter.html">Bundle
Adapter</a></li>
+<li><a
href="apache-felix-dependency-manager-4/reference/component-factory-configuration-adapter.html">Factory
Configuration Adapter</a></li>
+</ul>
+</li>
+<li><a
href="apache-felix-dependency-manager-4/reference/dependencies.html">Dependencies</a><ul>
+<li><a
href="apache-felix-dependency-manager-4/reference/dependency-service.html">Service</a></li>
+<li><a
href="apache-felix-dependency-manager-4/reference/dependency-configuration.html">Configuration</a></li>
+<li><a
href="apache-felix-dependency-manager-4/reference/dependency-bundle.html">Bundle</a></li>
+<li><a
href="apache-felix-dependency-manager-4/reference/dependency-resource.html">Resource</a></li>
+</ul>
+</li>
+<li><a
href="apache-felix-dependency-manager-4/reference/thread-model.html">Thread
Model</a></li>
+<li><a
href="apache-felix-dependency-manager-4/reference/external-links.html">External
Links and Articles</a></li>
+</ul>
+ <div class="timestamp" style="margin-top: 30px; font-size: 80%;
text-align: right;">
+ Rev. 1665695 by marrs on Tue, 10 Mar 2015 21:02:41 +0000
+ </div>
+ <div class="trademarkFooter">
+ Apache Felix, Felix, Apache, the Apache feather logo, and the Apache
Felix project
+ logo are trademarks of The Apache Software Foundation. All other marks
mentioned
+ may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+ </body>
+</html>
Added:
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/annotations.html
==============================================================================
---
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/annotations.html
(added)
+++
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/annotations.html
Tue Mar 10 21:03:25 2015
@@ -0,0 +1,404 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd";>
+<html>
+<!--
+
+ 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.
+-->
+ <head>
+ <title>Apache Felix - Dependency Manager SpellChecker Sample</title>
+ <link rel="icon" href="/res/favicon.ico">
+ <link rel="stylesheet" href="/res/site.css" type="text/css" media="all">
+ <link rel="stylesheet" href="/res/codehilite.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/";>
+ <img border="0" alt="Apache Felix" src="/res/logo.png">
+ </a>
+ </div>
+ <div class="header">
+ <a href="http://www.apache.org/";>
+ <img border="0" alt="Apache" src="/res/apache.png">
+ </a>
+ </div>
+ </div>
+
+ <div class="menu">
+ <p><a href="/news.html">news</a> <br />
+<a href="/license.html">license</a> <br />
+<a href="/downloads.cgi">downloads</a> <br />
+<a href="/documentation.html">documentation</a> <br />
+<a href="/mailinglists.html">mailing lists</a> <br />
+<a href="/documentation/community/contributing.html">contributing</a> <br />
+<a href="/sitemap.html">site map</a> <br />
+<a href="http://www.apache.org/";>asf</a> <br />
+<a href="http://www.apache.org/security/";>security</a> <br />
+<a href="http://www.apache.org/foundation/sponsorship.html";>sponsorship</a>
<br />
+<a href="http://www.apache.org/foundation/thanks.html";>sponsors</a> </p>
+<iframe
+ src="http://www.apache.org/ads/button.html";
+ style="border-width:0; float: left"
+ frameborder="0"
+ scrolling="no"
+ width="135"
+ height="135">
+</iframe>
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a
href="/documentation.html">Documentation</a> » <a
href="/documentation/subprojects.html">Apache Felix Subproject
Documentation</a> » <a
href="/documentation/subprojects/apache-felix-dependency-manager.html">Apache
Felix Dependency Manager 4</a>
+ </div>
+
+
+
+ <h1>Dependency Manager SpellChecker Sample</h1>
+ <p>This section presents a quick overview of the capabilities and usage
of the
+DependencyManager java 5 annotations. In particular, we will recap the
DependencyManager
+annotation architecture, and identify some simple usage scenarios using a
SpellChecker
+sample application with annotated components.
+The application is available from the felix trunk, in the
dependencymanager/samples.annotation
+subproject.</p>
+<h2 id="architecture">Architecture</h2>
+<p>Instead of writing Activators which extends the DependencyActivatorBase
class, service
+components can now be annotated using the annotations provided by the
+<em>org.apache.felix.dependencymanager.annotation</em> bundle. Annotations are
not reflectively
+parsed at runtime; but we use a BND plugin which scans annotations at
compilation phase
+and generates a compact metadata file in the bundle's
META-INF/dependencymanager
+subdirectory. This has the following benefits:</p>
+<ul>
+<li>JVM startup speed is not affected, and class files are not parsed when the
framework is starting</li>
+<li>Moreover, since the annotations are not retained by the VM at runtime, it
is not necessary to load the annotation API bundle at runtime.</li>
+</ul>
+<p>At runtime, the metadata generated during the compilation phase are
processed by a
+specific DependencyManager Runtime bundle, which is in charge of managing the
service
+component lifecycle and dependencies. This Runtime bundle actually uses the
+DependencyManager programmatic API in order to manage the annotated
components.
+Annotated components can then be inspected with the DependencyManager Gogo
shell, as it is
+the case with DM components declared through the programmatic DM API.</p>
+<h2 id="registering-a-service">Registering a Service</h2>
+<p>To register a service, your can annotate your class with a
<em>@Component</em> annotation, and
+an instance of your class will be registered under all directly implemented
interfaces
+into the OSGi registry. You can however take control on the interfaces to be
exposed, and
+in this case, you can use the <em>provides</em> attribute, which takes a list
of classes to
+expose from the registry.</p>
+<p>To illustrate this, we are now introducing a SpellChecker application which
provides a
+Felix "spellcheck" Gogo shell command. Gogo is the new shell supported by the
Felix
+Framework. Our "spellcheck" command is implemented by the SpellChecker
component which
+accepts a string as parameter. This string is then checked for proper
existence. To do
+the checking, The SpellChecker class has a required/multiple (1..N)
dependency over
+every available DictionaryService services. Such DictionaryService represents
a real
+dictionary for a given language (it has a <em>lang</em> service property),
and is
+configurable/instantiable from the OSGi Configuration Admin Service.</p>
+<p>Configuration Admin service provides a mechanism for configuring components
+(using ManagedService interfaces), and WebConsole actually implements this
service.
+ConfigAdmin is also able to instantiate some Services (using
ManagedServiceFactory
+interfaces).</p>
+<p>Now we have introduced the background, here is the SpellCheck component:</p>
+<div class="codehilite"><pre><span class="nd">@Component</span><span
class="o">(</span><span class="n">provides</span><span class="o">={</span><span
class="n">SpellChecker</span><span class="o">.</span><span
class="na">class</span><span class="o">},</span>
+ <span class="n">properties</span><span class="o">={</span><span
class="nd">@Property</span><span class="o">(</span><span
class="n">name</span><span class="o">=</span><span
class="n">CommandProcessor</span><span class="o">.</span><span
class="na">COMMAND_SCOPE</span><span class="o">,</span> <span
class="n">value</span><span class="o">=</span><span
class="s">"dmsample.annotation"</span><span class="o">),</span>
+ <span class="nd">@Property</span><span
class="o">(</span><span class="n">name</span><span class="o">=</span><span
class="n">CommandProcessor</span><span class="o">.</span><span
class="na">COMMAND_FUNCTION</span><span class="o">,</span> <span
class="n">values</span><span class="o">={</span><span
class="s">"spellcheck"</span><span class="o">})})</span>
+<span class="kd">public</span> <span class="kd">class</span> <span
class="nc">SpellChecker</span> <span class="o">{</span>
+ <span class="c1">// --- Gogo Shell command</span>
+
+ <span class="nd">@Descriptor</span><span class="o">(</span><span
class="s">"checks if word is found from an available
dictionary"</span><span class="o">)</span>
+ <span class="kd">public</span> <span class="kt">void</span> <span
class="nf">spellcheck</span><span class="o">(</span><span
class="nd">@Descriptor</span><span class="o">(</span><span class="s">"the
word to check"</span><span class="o">)</span><span class="n">String</span>
<span class="n">word</span><span class="o">)</span> <span class="o">{</span>
+ <span class="c1">// Check the proper existence of the word parameter,
using injected DictionaryService instances</span>
+ <span class="c1">// ...</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>In the code above, you see that the SpellCheck is annotated with the
<em>@Component</em>
+annotation. Gogo runtime does not required shell commands to implement a
specific
+interface. Commands just have to register some Pojos in the OSGi registry,
but the only
+thing required is to provide the Pojos with two service properties (
COMMAND_SCOPE, and
+COMMAND_FUNCTION) which will be used by the Gogo runtime when instropecting
the Pojo
+for invoking the proper functions.</p>
+<p>So, coming back to the sample code, the SpellChecker class registers
itself into the OSGi registry, using the <em>provides</em> attribute, which
just refer to our SpellChecker class, and the two mandatory Gogo service
properties are also specified using the <em>@Property</em> annotation. It is
not shown here, but service properties can also be provided dynamically from a
method that can return a Map, and annotated with the <em>@Start</em> lifecycle
callback, but we will see this feature in a another section.</p>
+<h2 id="depending-on-a-service">Depending on a Service</h2>
+<p>Our SpellChecker component can expose itself as a Gogo shell command, but
before being
+registered into the OSGi registry, we also need to be injected with two
dependencies:
+one required dependency (at minimum) on a DictionaryService, and another
optional one on
+a LogService. First, let's look at the DictionaryService, which is a simple
interface:</p>
+<div class="codehilite"><pre><span class="kd">public</span> <span
class="kd">interface</span> <span class="nc">DictionaryService</span> <span
class="o">{</span>
+ <span class="cm">/**</span>
+<span class="cm"> * Check for the existence of a word.</span>
+<span class="cm"> * @param word the word to be checked.</span>
+<span class="cm"> * @return true if the word is in the dictionary, false
otherwise.</span>
+<span class="cm"> */</span>
+ <span class="kd">public</span> <span class="kt">boolean</span> <span
class="nf">checkWord</span><span class="o">(</span><span
class="n">String</span> <span class="n">word</span><span class="o">);</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>And here is our previous SpellChecker component, augmented with two new
ServiceDependency
+annotations:</p>
+<div class="codehilite"><pre><span class="nd">@Component</span><span
class="o">(</span><span class="n">provides</span><span class="o">={</span><span
class="n">SpellChecker</span><span class="o">.</span><span
class="na">class</span><span class="o">},</span>
+ <span class="n">properties</span><span class="o">={</span><span
class="nd">@Property</span><span class="o">(</span><span
class="n">name</span><span class="o">=</span><span
class="n">CommandProcessor</span><span class="o">.</span><span
class="na">COMMAND_SCOPE</span><span class="o">,</span> <span
class="n">value</span><span class="o">=</span><span
class="s">"dmsample.annotation"</span><span class="o">),</span>
+ <span class="nd">@Property</span><span
class="o">(</span><span class="n">name</span><span class="o">=</span><span
class="n">CommandProcessor</span><span class="o">.</span><span
class="na">COMMAND_FUNCTION</span><span class="o">,</span> <span
class="n">values</span><span class="o">={</span><span
class="s">"spellcheck"</span><span class="o">})})</span>
+<span class="kd">public</span> <span class="kd">class</span> <span
class="nc">SpellChecker</span> <span class="o">{</span>
+ <span class="nd">@ServiceDependency</span><span class="o">(</span><span
class="n">required</span> <span class="o">=</span> <span
class="kc">false</span><span class="o">)</span>
+ <span class="kd">private</span> <span class="n">LogService</span> <span
class="n">m_log</span><span class="o">;</span>
+
+ <span class="kd">private</span> <span
class="n">CopyOnWriteArrayList</span><span class="o"><</span><span
class="n">DictionaryService</span><span class="o">></span> <span
class="n">m_dictionaries</span> <span class="o">=</span> <span
class="k">new</span> <span class="n">CopyOnWriteArrayList</span><span
class="o"><</span><span class="n">DictionaryService</span><span
class="o">>();</span>
+
+ <span class="nd">@ServiceDependency</span><span class="o">(</span><span
class="n">removed</span> <span class="o">=</span> <span
class="s">"removeDictionary"</span><span class="o">)</span>
+ <span class="kd">protected</span> <span class="kt">void</span> <span
class="nf">addDictionary</span><span class="o">(</span><span
class="n">DictionaryService</span> <span class="n">dictionary</span><span
class="o">)</span> <span class="o">{</span>
+ <span class="n">m_dictionaries</span><span class="o">.</span><span
class="na">add</span><span class="o">(</span><span
class="n">dictionary</span><span class="o">);</span>
+ <span class="o">}</span>
+
+ <span class="kd">protected</span> <span class="kt">void</span> <span
class="nf">removeDictionary</span><span class="o">(</span><span
class="n">DictionaryService</span> <span class="n">dictionary</span><span
class="o">)</span> <span class="o">{</span>
+ <span class="n">m_dictionaries</span><span class="o">.</span><span
class="na">remove</span><span class="o">(</span><span
class="n">dictionary</span><span class="o">);</span>
+ <span class="o">}</span>
+
+ <span class="c1">// --- Gogo Shell command</span>
+
+ <span class="nd">@Descriptor</span><span class="o">(</span><span
class="s">"checks if word is found from an available
dictionary"</span><span class="o">)</span>
+ <span class="kd">public</span> <span class="kt">void</span> <span
class="nf">spellcheck</span><span class="o">(</span><span
class="nd">@Descriptor</span><span class="o">(</span><span class="s">"the
word to check"</span><span class="o">)</span><span class="n">String</span>
<span class="n">word</span><span class="o">)</span> <span class="o">{</span>
+ <span class="n">m_log</span><span class="o">.</span><span
class="na">log</span><span class="o">(</span><span
class="n">LogService</span><span class="o">.</span><span
class="na">LOG_INFO</span><span class="o">,</span> <span
class="s">"Checking spelling of word \""</span> <span
class="o">+</span> <span class="n">word</span>
+ <span class="o">+</span> <span class="s">"\" using the
following dictionaries: "</span> <span class="o">+</span> <span
class="n">m_dictionaries</span><span class="o">);</span>
+
+ <span class="k">for</span> <span class="o">(</span><span
class="n">DictionaryService</span> <span class="n">dictionary</span> <span
class="o">:</span> <span class="n">m_dictionaries</span><span
class="o">)</span> <span class="o">{</span>
+ <span class="k">if</span> <span class="o">(</span><span
class="n">dictionary</span><span class="o">.</span><span
class="na">checkWord</span><span class="o">(</span><span
class="n">word</span><span class="o">))</span> <span class="o">{</span>
+ <span class="n">System</span><span class="o">.</span><span
class="na">out</span><span class="o">.</span><span
class="na">println</span><span class="o">(</span><span class="s">"word
"</span> <span class="o">+</span> <span class="n">word</span> <span
class="o">+</span> <span class="s">" is correct"</span><span
class="o">);</span>
+ <span class="k">return</span><span class="o">;</span>
+ <span class="o">}</span>
+ <span class="o">}</span>
+ <span class="n">System</span><span class="o">.</span><span
class="na">err</span><span class="o">.</span><span
class="na">println</span><span class="o">(</span><span class="s">"word
"</span> <span class="o">+</span> <span class="n">word</span> <span
class="o">+</span> <span class="s">" is incorrect"</span><span
class="o">);</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>There are many things to describe in the code above:</p>
+<p>First, we define an optional dependency on the LogService, by defining a
+<em>@ServiceDependency(required=false)</em> annotation on our m_logService
field: This
+means that our component will be provided into the OSGi registry even if there
+is no available LogService, and in this case, a NullObject will be injected in
+our class field;
+This will avoid to check for nullability, when using the m_logService field.
+All optional dependencies applied on class fields are injected with a
+NullObject (when not available).
+The NullObject can be invoked and will do nothing. For a lot of cases that is
+good enough to handle optional dependencies. But when you really want to check
+if an optional service is there or not, then you have to apply the optional
+dependency on a callback method, which will be called when the optional
+service is available.</p>
+<p>Next comes the dependency on the DictionaryService. Here, we use a
<em>ServiceDependency</em>
+annotation, but this time we apply it on a method
(<em>add/removeDictionary</em>). There is no
+need to specify the "<em>required=true</em>" flag because it is the default
value. Notice that
+this behavior is different from the API, where service dependencies are
optional by default
+. We use a callback method, because we just need to register all available
+DictionaryService services in our dictionary list, which is used when checking
word
+existence. This list is a copy on write list because the dependency may be
injected at
+any time, possibly from another thread. So, using a copy on write list avoid
us to use synchronized methods.</p>
+<h2 id="creating-a-service-from-configadmin">Creating a Service from
ConfigAdmin</h2>
+<p>The <em>@Component</em> annotation is not the only one for creating
services. Another one is
+the <em>@FactoryConfigurationAdapterService</em> annotation which allows to
instantiate many
+instances of the same annotated service class from ConfigAdmin (and
WebConsole).
+To illustrate this, let's take a look at our DictionaryImpl class which is
part of the
+SpellChecker sample. This service is required by the SpellChecker component,
when
+checking for proper word existence. And you can instantiate as many
DictionaryService as
+you want, from ConfigAdmin ...</p>
+<div class="codehilite"><pre><span
class="nd">@FactoryConfigurationAdapterService</span><span
class="o">(</span><span class="n">factoryPid</span><span
class="o">=</span><span
class="s">"DictionaryImplFactoryPid"</span><span class="o">,</span>
<span class="n">updated</span><span class="o">=</span><span
class="s">"updated"</span><span class="o">)</span>
+<span class="kd">public</span> <span class="kd">class</span> <span
class="nc">DictionaryImpl</span> <span class="kd">implements</span> <span
class="n">DictionaryService</span> <span class="o">{</span>
+ <span class="cm">/**</span>
+<span class="cm"> * We store all configured words in a thread-safe data
structure, because ConfigAdmin</span>
+<span class="cm"> * may invoke our updated method at any time.</span>
+<span class="cm"> */</span>
+ <span class="kd">private</span> <span class="kd">final</span> <span
class="n">CopyOnWriteArrayList</span><span class="o"><</span><span
class="n">String</span><span class="o">></span> <span
class="n">m_words</span> <span class="o">=</span> <span class="k">new</span>
<span class="n">CopyOnWriteArrayList</span><span class="o"><</span><span
class="n">String</span><span class="o">>();</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * Our Dictionary language.</span>
+<span class="cm"> */</span>
+ <span class="kd">private</span> <span class="n">String</span> <span
class="n">m_lang</span><span class="o">;</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * Our service will be initialized from ConfigAdmin, and
we also handle updates in this method.</span>
+<span class="cm"> * @param config The configuration where we'll lookup
our words list (key="words").</span>
+<span class="cm"> */</span>
+ <span class="kd">protected</span> <span class="kt">void</span> <span
class="nf">updated</span><span class="o">(</span><span
class="n">Dictionary</span><span class="o"><</span><span
class="n">String</span><span class="o">,</span> <span class="o">?></span>
<span class="n">config</span><span class="o">)</span> <span class="o">{</span>
+ <span class="n">m_lang</span> <span class="o">=</span> <span
class="o">(</span><span class="n">String</span><span class="o">)</span> <span
class="n">config</span><span class="o">.</span><span class="na">get</span><span
class="o">(</span><span class="s">"lang"</span><span
class="o">);</span>
+ <span class="n">m_words</span><span class="o">.</span><span
class="na">clear</span><span class="o">();</span>
+ <span class="n">String</span><span class="o">[]</span> <span
class="n">words</span> <span class="o">=</span> <span class="o">(</span><span
class="n">String</span><span class="o">[])</span> <span
class="n">config</span><span class="o">.</span><span class="na">get</span><span
class="o">(</span><span class="s">"words"</span><span
class="o">);</span>
+ <span class="k">for</span> <span class="o">(</span><span
class="n">String</span> <span class="n">word</span> <span class="o">:</span>
<span class="n">words</span><span class="o">)</span> <span class="o">{</span>
+ <span class="n">m_words</span><span class="o">.</span><span
class="na">add</span><span class="o">(</span><span class="n">word</span><span
class="o">);</span>
+ <span class="o">}</span>
+ <span class="o">}</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * Check if a word exists if the list of words we have
been configured from ConfigAdmin/WebConsole.</span>
+<span class="cm"> */</span>
+ <span class="kd">public</span> <span class="kt">boolean</span> <span
class="nf">checkWord</span><span class="o">(</span><span
class="n">String</span> <span class="n">word</span><span class="o">)</span>
<span class="o">{</span>
+ <span class="k">return</span> <span class="n">m_words</span><span
class="o">.</span><span class="na">contains</span><span class="o">(</span><span
class="n">word</span><span class="o">);</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Our DictionaryImpl class implements a DictionaryService, and our class will
be registered
+under that interface (all directly implemented interfaces are used when
registering the
+service, but you can select some others using the <em>provides</em>
attribute).
+The <em>@FactoryConfigurationAdapterService</em> annotation will instantiate
our service for
+each configuration created from web console (and matching our
"DictionaryImplFactoryPid"
+factoryPid).</p>
+<p>We also use the <em>updated</em> attribute, which specifies a callback
method which will handle
+properties configured by ConfigAdmin. The updated callback will also be
called when our
+properties are changing. Every properties are propagated to our service
properties,
+unless the properties starting with a dot ("."). Configuration properties
starting with
+a dot (".") are considered private and are not propagated.</p>
+<p>Notice that you can mix standard bnd metatype annotations with DM
annotations, in order
+describe configurations meta data (default values, property labels, etc ...
see http://www.aqute.biz/Bnd/MetaType).
+So, let's revisit our DisctionaryImpl service, but this time with meta type
support:</p>
+<p>First, we define an interface for describing our configuration metadata,
with bnd metatype annotations:</p>
+<div class="codehilite"><pre><span class="kn">import</span> <span
class="nn">java.util.List</span><span class="o">;</span>
+
+<span class="kn">import</span> <span
class="nn">aQute.bnd.annotation.metatype.Meta.AD</span><span class="o">;</span>
+<span class="kn">import</span> <span
class="nn">aQute.bnd.annotation.metatype.Meta.OCD</span><span class="o">;</span>
+
+<span class="nd">@OCD</span><span class="o">(</span><span
class="n">name</span><span class="o">=</span><span class="s">"Spell
Checker Dictionary (annotation)"</span><span class="o">,</span> <span
class="n">factory</span> <span class="o">=</span> <span
class="kc">true</span><span class="o">,</span> <span
class="n">description</span> <span class="o">=</span> <span
class="s">"Declare here some Dictionary instances"</span><span
class="o">)</span>
+<span class="kd">public</span> <span class="kd">interface</span> <span
class="nc">DictionaryConfiguration</span> <span class="o">{</span>
+ <span class="nd">@AD</span><span class="o">(</span><span
class="n">description</span> <span class="o">=</span> <span
class="s">"Describes the dictionary language"</span><span
class="o">,</span> <span class="n">deflt</span> <span class="o">=</span> <span
class="s">"en"</span><span class="o">)</span>
+ <span class="n">String</span> <span class="nf">lang</span><span
class="o">();</span>
+
+ <span class="nd">@AD</span><span class="o">(</span><span
class="n">description</span> <span class="o">=</span> <span
class="s">"Declare here the list of words supported by this dictionary.
This properties starts with a Dot and won't be propagated with Dictionary
OSGi service properties"</span><span class="o">)</span>
+ <span class="n">List</span><span class="o"><</span><span
class="n">String</span><span class="o">></span> <span
class="n">words</span><span class="o">();</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Next, here is our DictionaryImpl that will use the bnd "Configurable"
helper in order to retrieve the actual configuration:</p>
+<div class="codehilite"><pre><span class="kn">import</span> <span
class="nn">org.apache.felix.dm.annotation.api.FactoryConfigurationAdapterService</span><span
class="o">;</span>
+<span class="kn">import</span> <span
class="nn">org.apache.felix.dm.annotation.api.ServiceDependency</span><span
class="o">;</span>
+<span class="kn">import</span> <span
class="nn">org.apache.felix.dm.annotation.api.Start</span><span
class="o">;</span>
+<span class="kn">import</span> <span
class="nn">org.osgi.service.log.LogService</span><span class="o">;</span>
+<span class="kn">import</span> <span
class="nn">aQute.bnd.annotation.metatype.Configurable</span><span
class="o">;</span>
+
+<span class="nd">@FactoryConfigurationAdapterService</span><span
class="o">(</span><span class="n">factoryPidClass</span> <span
class="o">=</span> <span class="n">DictionaryConfiguration</span><span
class="o">.</span><span class="na">class</span><span class="o">,</span> <span
class="n">propagate</span> <span class="o">=</span> <span
class="kc">true</span><span class="o">,</span> <span class="n">updated</span>
<span class="o">=</span> <span class="s">"updated"</span><span
class="o">)</span>
+<span class="kd">public</span> <span class="kd">class</span> <span
class="nc">DictionaryImpl</span> <span class="kd">implements</span> <span
class="n">DictionaryService</span> <span class="o">{</span>
+ <span class="kd">private</span> <span class="kd">final</span> <span
class="n">CopyOnWriteArrayList</span><span class="o"><</span><span
class="n">String</span><span class="o">></span> <span
class="n">m_words</span> <span class="o">=</span> <span class="k">new</span>
<span class="n">CopyOnWriteArrayList</span><span class="o"><</span><span
class="n">String</span><span class="o">>();</span>
+ <span class="kd">private</span> <span class="n">String</span> <span
class="n">m_lang</span><span class="o">;</span>
+
+ <span class="kd">protected</span> <span class="kt">void</span> <span
class="nf">updated</span><span class="o">(</span><span
class="n">Dictionary</span><span class="o"><</span><span
class="n">String</span><span class="o">,</span> <span class="o">?></span>
<span class="n">config</span><span class="o">)</span> <span class="o">{</span>
+ <span class="k">if</span> <span class="o">(</span><span
class="n">config</span> <span class="o">!=</span> <span
class="kc">null</span><span class="o">)</span> <span class="o">{</span>
+ <span class="c1">// use bnd "Configurable" helper to get
an implementation for our DictionaryConfiguration.</span>
+ <span class="n">DictionaryConfiguration</span> <span
class="n">cnf</span> <span class="o">=</span>
+ <span class="n">Configurable</span><span
class="o">.</span><span class="na">createConfigurable</span><span
class="o">(</span><span class="n">DictionaryConfiguration</span><span
class="o">.</span><span class="na">class</span><span class="o">,</span> <span
class="n">config</span><span class="o">);</span>
+
+ <span class="n">m_lang</span> <span class="o">=</span> <span
class="n">cnf</span><span class="o">.</span><span class="na">lang</span><span
class="o">();</span>
+ <span class="n">m_words</span><span class="o">.</span><span
class="na">clear</span><span class="o">();</span>
+ <span class="k">for</span> <span class="o">(</span><span
class="n">String</span> <span class="n">word</span> <span class="o">:</span>
<span class="n">cnf</span><span class="o">.</span><span
class="na">words</span><span class="o">())</span> <span class="o">{</span>
+ <span class="n">m_words</span><span class="o">.</span><span
class="na">add</span><span class="o">(</span><span class="n">word</span><span
class="o">);</span>
+ <span class="o">}</span>
+ <span class="o">}</span>
+ <span class="o">}</span>
+
+ <span class="kd">public</span> <span class="kt">boolean</span> <span
class="nf">checkWord</span><span class="o">(</span><span
class="n">String</span> <span class="n">word</span><span class="o">)</span>
<span class="o">{</span>
+ <span class="k">return</span> <span class="n">m_words</span><span
class="o">.</span><span class="na">contains</span><span class="o">(</span><span
class="n">word</span><span class="o">);</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<h2 id="providing-an-aspect">Providing an Aspect</h2>
+<p>As we have seen in the previous section, there are many annotations that
can be used
+to specify a service. Another one is the <em>@AspectService</em> annotation.
This annotation
+allows to <em>decorate</em> an existing service in order to add certain
"capabilities" to it,
+like adding a specific caching mechanism to a storage service or
implementing logging.
+Aspects can be plugged to an existing service at runtime, and can also be
removed
+dynamically. This is transparent, and the clients using the existing service
are not
+interrupted, they are just rebound with the aspect service.</p>
+<p>As an example, we go back to our SpellChecker application, and we are now
looking at the
+DictionaryAspect class. This class uses the <em>@Aspect</em> Service
annotation in
+order to add some custom words to an English DictionaryService (with the
+service property lang=en).
+The Extra words to add to the English Dictionary will be configured from
+ConfigAdmin. That's why the class also uses a
<em>@ConfigurationDependency</em> annotation:</p>
+<div class="codehilite"><pre><span class="nd">@AspectService</span><span
class="o">(</span><span class="n">ranking</span> <span class="o">=</span> <span
class="mi">10</span><span class="o">,</span> <span class="n">filter</span>
<span class="o">=</span> <span class="s">"(lang=en)"</span><span
class="o">)</span>
+<span class="kd">public</span> <span class="kd">class</span> <span
class="nc">DictionaryAspect</span> <span class="kd">implements</span> <span
class="n">DictionaryService</span> <span class="o">{</span>
+ <span class="cm">/**</span>
+<span class="cm"> * This is the service this aspect is applying to.</span>
+<span class="cm"> */</span>
+ <span class="kd">private</span> <span class="kd">volatile</span> <span
class="n">DictionaryService</span> <span
class="n">m_originalDictionary</span><span class="o">;</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * We store all configured words in a thread-safe data
structure, because ConfigAdmin may</span>
+<span class="cm"> * invoke our updated method at any time.</span>
+<span class="cm"> */</span>
+ <span class="kd">private</span> <span
class="n">CopyOnWriteArrayList</span><span class="o"><</span><span
class="n">String</span><span class="o">></span> <span
class="n">m_words</span> <span class="o">=</span> <span class="k">new</span>
<span class="n">CopyOnWriteArrayList</span><span class="o"><</span><span
class="n">String</span><span class="o">>();</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * Defines a configuration dependency for retrieving our
english custom words (by default,</span>
+<span class="cm"> * our PID is our full class name).</span>
+<span class="cm"> */</span>
+ <span class="nd">@ConfigurationDependency</span>
+ <span class="kd">protected</span> <span class="kt">void</span> <span
class="nf">updated</span><span class="o">(</span><span
class="n">Dictionary</span><span class="o"><</span><span
class="n">String</span><span class="o">,</span> <span class="o">?></span>
<span class="n">config</span><span class="o">)</span> <span class="o">{</span>
+ <span class="n">m_words</span><span class="o">.</span><span
class="na">clear</span><span class="o">();</span>
+ <span class="n">String</span><span class="o">[]</span> <span
class="n">words</span> <span class="o">=</span> <span class="o">(</span><span
class="n">String</span><span class="o">[])</span> <span
class="n">config</span><span class="o">.</span><span class="na">get</span><span
class="o">(</span><span class="s">"words"</span><span
class="o">);</span>
+ <span class="k">for</span> <span class="o">(</span><span
class="n">String</span> <span class="n">word</span> <span class="o">:</span>
<span class="n">words</span><span class="o">)</span> <span class="o">{</span>
+ <span class="n">m_words</span><span class="o">.</span><span
class="na">add</span><span class="o">(</span><span class="n">word</span><span
class="o">);</span>
+ <span class="o">}</span>
+ <span class="o">}</span>
+
+ <span class="cm">/**</span>
+<span class="cm"> * Checks if a word is found from our custom word list. if
not, delegate to the decorated</span>
+<span class="cm"> * dictionary.</span>
+<span class="cm"> */</span>
+ <span class="kd">public</span> <span class="kt">boolean</span> <span
class="nf">checkWord</span><span class="o">(</span><span
class="n">String</span> <span class="n">word</span><span class="o">)</span>
<span class="o">{</span>
+ <span class="k">if</span> <span class="o">(</span><span
class="n">m_words</span><span class="o">.</span><span
class="na">contains</span><span class="o">(</span><span
class="n">word</span><span class="o">))</span> <span class="o">{</span>
+ <span class="k">return</span> <span class="kc">true</span><span
class="o">;</span>
+ <span class="o">}</span>
+ <span class="k">return</span> <span
class="n">m_originalDictionary</span><span class="o">.</span><span
class="na">checkWord</span><span class="o">(</span><span
class="n">word</span><span class="o">);</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>The annotation does the following: because our class implements the
DictionaryService
+contract, it will instantiate our service each time it finds another existing
+DictionaryService matching the filter attribute we provide in the annotation
+(filter="(lang=en)"). And it will inject the existing service in our
+m_originalDictionary field, by reflection. But we can also specify a field
attribute in
+the annotation, if we want to explicitly inject the existing service in a
given class
+field. So, any client depending on an English DictionaryService will be
transparently
+rebound to our aspect Dictionary.</p>
+<p>In the Annotation, also notice the <em>ranking</em> attribute: It is the
level used to organize
+the aspect chain ordering (multiple aspects may be applied on a given
service).</p>
+<p>The <em>ConfigurationDependency</em> is another dependency that we have
not seen before: it is
+used to configure the extra English words from ConfigAdmin. This annotation
normally
+requires a pid parameter, which is a persistent identifier uniquely
identifying our
+component, but by default, the pid is set to the fully qualified name of our
class.</p>
+<h2 id="how-to-run-the-sample-code">How to run the sample code</h2>
+<p>Just import the Dependency source distribution in bndtools and check the
following samples:</p>
+<ul>
+<li>org.apache.felix.dependencymanager.samples/src/org/apache/felix/dependencymanager/samples/dictionary/annot/README</li>
+<li>org.apache.felix.dependencymanager.samples/src/org/apache/felix/dependencymanager/samples/dictionary/api/README</li>
+</ul>
+ <div class="timestamp" style="margin-top: 30px; font-size: 80%;
text-align: right;">
+ Rev. 1664580 by pderop on Fri, 6 Mar 2015 10:14:58 +0000
+ </div>
+ <div class="trademarkFooter">
+ Apache Felix, Felix, Apache, the Apache feather logo, and the Apache
Felix project
+ logo are trademarks of The Apache Software Foundation. All other marks
mentioned
+ may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+ </body>
+</html>
Added:
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/background.html
==============================================================================
---
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/background.html
(added)
+++
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/background.html
Tue Mar 10 21:03:25 2015
@@ -0,0 +1,101 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd";>
+<html>
+<!--
+
+ 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.
+-->
+ <head>
+ <title>Apache Felix - Apache Felix Dependency Manager - Background</title>
+ <link rel="icon" href="/res/favicon.ico">
+ <link rel="stylesheet" href="/res/site.css" type="text/css" media="all">
+ <link rel="stylesheet" href="/res/codehilite.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/";>
+ <img border="0" alt="Apache Felix" src="/res/logo.png">
+ </a>
+ </div>
+ <div class="header">
+ <a href="http://www.apache.org/";>
+ <img border="0" alt="Apache" src="/res/apache.png">
+ </a>
+ </div>
+ </div>
+
+ <div class="menu">
+ <p><a href="/news.html">news</a> <br />
+<a href="/license.html">license</a> <br />
+<a href="/downloads.cgi">downloads</a> <br />
+<a href="/documentation.html">documentation</a> <br />
+<a href="/mailinglists.html">mailing lists</a> <br />
+<a href="/documentation/community/contributing.html">contributing</a> <br />
+<a href="/sitemap.html">site map</a> <br />
+<a href="http://www.apache.org/";>asf</a> <br />
+<a href="http://www.apache.org/security/";>security</a> <br />
+<a href="http://www.apache.org/foundation/sponsorship.html";>sponsorship</a>
<br />
+<a href="http://www.apache.org/foundation/thanks.html";>sponsors</a> </p>
+<iframe
+ src="http://www.apache.org/ads/button.html";
+ style="border-width:0; float: left"
+ frameborder="0"
+ scrolling="no"
+ width="135"
+ height="135">
+</iframe>
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a
href="/documentation.html">Documentation</a> » <a
href="/documentation/subprojects.html">Apache Felix Subproject
Documentation</a> » <a
href="/documentation/subprojects/apache-felix-dependency-manager.html">Apache
Felix Dependency Manager 4</a>
+ </div>
+
+
+
+ <h1>Apache Felix Dependency Manager - Background</h1>
+ <h2 id="background">Background</h2>
+<p>In an OSGi framework, services are deployed using bundles and these bundles
feature two types of dependencies: </p>
+<ol>
+<li>Package dependencies. A bundle can export a package which others import.
These dependencies, although dynamic, are relatively easy to handle and the
whole resolution process is handled by the OSGi framework for you.</li>
+<li>Service dependencies. Services, implemented by components inside of
bundles, can have their own life cycle within that of their containing bundle
and therefore can be registered and unregistered at any time. Other components
often depend on these services and need to deal with changes in their
availability. </li>
+</ol>
+<p>When you look at dependency management, there are two aspects you need to
take into account: </p>
+<p>The first is managing software configurations. This means you need to
manage the dependencies from a configuration standpoint. What you are managing
are bundles, since those are the units of deployment. What you need to manage
are the package and service dependencies between bundles. Package dependencies
are always visible by examining the bundle manifest and when a bundle is
installed the framework will try to resolve such dependencies before that
bundle can even be started. Service dependencies are only optionally described
in the manifest by a list of services a bundle might export as well as a list
it might use (import). The words 'optionally' and 'might' already indicate that
these aren't things we can depend on. Even worse, these keywords have by now
been deprecated. Besides that, the framework doesn't have to perform any checks
on these attributes.</p>
+<p>The second is managing service dependencies at runtime. As mentioned
before, a service oriented architecture is dynamic by design, so your
implementation should be able to deal with this. Bundles can start in any order
and any service can go away or be replaced by a different implementation at any
point in time. OSGi itself offers basic assistance for tracking services. You
can track them yourself by registering as a service listener. A slightly more
advanced way is to create a service tracker, which you can subsequently query,
or have it notify you on changes. All of these are too low-level to be good
building blocks for developers.</p>
+<p>In real implementations, you are probably going to track multiple services.
Using service trackers in such a scenario has the tendency to result in
dependency logic that is entangled in the implementation instead of being
expressed in a declarative way. Using a declarative way to specify dependencies
has clear advantages when it comes to monitoring and managing them, a task that
becomes more and more important in modern, federated, service oriented
environments.</p>
+<p>The Dependency Manager provides you with the right building blocks to
declaratively specify dependencies using a straightforward Java API that is
easy to maintain and refactor.</p>
+<h2 id="design-goals">Design Goals</h2>
+<p>The goals that drove the design of the dependency manager are:</p>
+<ul>
+<li>Provide a clean separation between a component implementation and the
"glue" that binds it to the OSGi framework. The component implementation should
not have to contain any OSGi specific code. In other words, it should be a POJO
(Plain Old Java Object).</li>
+<li>Minimize the amount of code that needs to be written. The specification
and management of dependencies should be automated as much as possible, whilst
still providing enough flexibility to customize the system.</li>
+<li>Be extensible. Even though the core bundle provides a lot of different
dependencies already, you should be able to add your own types of dependencies
easily.</li>
+<li>Easy to monitor and debug. Being a dynamic system, it's important to be
able to see what the state of all components and dependencies are at any point
in time.</li>
+<li>Supporting powerful high level design patterns. When building real-world
applications, more complex patterns need to be used, such as aspects and
adapters. Support for these needs to be built into the core.</li>
+</ul>
+ <div class="timestamp" style="margin-top: 30px; font-size: 80%;
text-align: right;">
+ Rev. 1663924 by marrs on Wed, 4 Mar 2015 10:39:19 +0000
+ </div>
+ <div class="trademarkFooter">
+ Apache Felix, Felix, Apache, the Apache feather logo, and the Apache
Felix project
+ logo are trademarks of The Apache Software Foundation. All other marks
mentioned
+ may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+ </body>
+</html>
Added:
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/bundles-and-dependencies.html
==============================================================================
---
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/bundles-and-dependencies.html
(added)
+++
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/bundles-and-dependencies.html
Tue Mar 10 21:03:25 2015
@@ -0,0 +1,112 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd";>
+<html>
+<!--
+
+ 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.
+-->
+ <head>
+ <title>Apache Felix - Dependency Manager - Bundles and Dependencies</title>
+ <link rel="icon" href="/res/favicon.ico">
+ <link rel="stylesheet" href="/res/site.css" type="text/css" media="all">
+ <link rel="stylesheet" href="/res/codehilite.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/";>
+ <img border="0" alt="Apache Felix" src="/res/logo.png">
+ </a>
+ </div>
+ <div class="header">
+ <a href="http://www.apache.org/";>
+ <img border="0" alt="Apache" src="/res/apache.png">
+ </a>
+ </div>
+ </div>
+
+ <div class="menu">
+ <p><a href="/news.html">news</a> <br />
+<a href="/license.html">license</a> <br />
+<a href="/downloads.cgi">downloads</a> <br />
+<a href="/documentation.html">documentation</a> <br />
+<a href="/mailinglists.html">mailing lists</a> <br />
+<a href="/documentation/community/contributing.html">contributing</a> <br />
+<a href="/sitemap.html">site map</a> <br />
+<a href="http://www.apache.org/";>asf</a> <br />
+<a href="http://www.apache.org/security/";>security</a> <br />
+<a href="http://www.apache.org/foundation/sponsorship.html";>sponsorship</a>
<br />
+<a href="http://www.apache.org/foundation/thanks.html";>sponsors</a> </p>
+<iframe
+ src="http://www.apache.org/ads/button.html";
+ style="border-width:0; float: left"
+ frameborder="0"
+ scrolling="no"
+ width="135"
+ height="135">
+</iframe>
+ </div>
+
+ <div class="main">
+ <div class="breadcrump" style="font-size: 80%;">
+ <a href="/">Home</a> » <a
href="/documentation.html">Documentation</a> » <a
href="/documentation/subprojects.html">Apache Felix Subproject
Documentation</a> » <a
href="/documentation/subprojects/apache-felix-dependency-manager.html">Apache
Felix Dependency Manager 4</a>
+ </div>
+
+
+
+ <h1>Dependency Manager - Bundles and Dependencies</h1>
+ <p>The dependency manager project consists of the following bundles. For
each bundle, we also list its dependencies in the form of package imports, plus
a suggestion on a bundle that resolves them.</p>
+<ul>
+<li>
+<p><code>org.apache.felix.dependencymanager</code> - 4.0.0 - This is the core
bundle, containing the code for working with the Java based API.</p>
+<ul>
+<li>org.osgi.framework;version="[1.5,2)" - provided by the OSGi framework
itself</li>
+<li>org.osgi.util.tracker;version="[1.4,2)" - provided by the OSGi framework
itself</li>
+<li>org.osgi.service.cm;version="[1.3,2)" - provided by Apache Felix
Configuration Admin, or the OSGi Compendium bundle</li>
+<li>org.osgi.service.metatype;version="[1.1,2)" - provided by Apache Felix
Metatype, or the OSGi Compendium bundle</li>
+</ul>
+</li>
+<li>
+<p><code>org.apache.felix.dependencymanager.runtime</code> - 4.0.0 - This is
the runtime bundle that you need, together with the core bundle above, if you
want to work with annotations.</p>
+<ul>
+<li>org.osgi.framework;version="[1.5,2)" - provided by the OSGi framework
itself</li>
+<li>org.osgi.service.packageadmin;version="[1.2,2)" - provided by the OSGi
framework itself</li>
+<li>org.apache.felix.dm;version="[4,5)" - provided by the core bundle</li>
+<li>org.apache.felix.dm.context;version="[4,5)" - provided by the core
bundle</li>
+<li>org.osgi.service.log;version="[1.3,2)" - provided by Apache Felix Log
Service, or the OSGi Compendium bundle</li>
+</ul>
+</li>
+<li>
+<p><code>org.apache.felix.dependencymanager.shell</code> - 4.0.0 - This is the
shell bundle. It only contains the shell commands, so you need it if you want
to use those.</p>
+<ul>
+<li>org.apache.felix.dm;version="[4.0,5)" - provided by the core bundle</li>
+<li>org.apache.felix.service.command;version="[0.10,1)";status=provisional</li>
+<li>org.osgi.framework;version="[1.5,2)" - provided by the OSGi framework
itself</li>
+</ul>
+</li>
+<li><code>org.apache.felix.dependencymanager.annotation</code> - 4.0.0 - This
is not a bundle, but code you need when compiling your bundles that contain
annotations.</li>
+</ul>
+ <div class="timestamp" style="margin-top: 30px; font-size: 80%;
text-align: right;">
+ Rev. 1665690 by marrs on Tue, 10 Mar 2015 20:57:44 +0000
+ </div>
+ <div class="trademarkFooter">
+ Apache Felix, Felix, Apache, the Apache feather logo, and the Apache
Felix project
+ logo are trademarks of The Apache Software Foundation. All other marks
mentioned
+ may be trademarks or registered trademarks of their respective owners.
+ </div>
+ </div>
+ </body>
+</html>
