Author: buildbot
Date: Wed Mar 4 20:00:11 2015
New Revision: 942354
Log:
Staging update by buildbot for felix
Modified:
websites/staging/felix/trunk/content/ (props changed)
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/components.html
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/dependencies.html
Propchange: websites/staging/felix/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Wed Mar 4 20:00:11 2015
@@ -1 +1 @@
-1664113
+1664129
Modified:
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/components.html
==============================================================================
---
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/components.html
(original)
+++
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/components.html
Wed Mar 4 20:00:11 2015
@@ -69,19 +69,35 @@
<h1>Apache Felix Dependency Manager - Components</h1>
<p>Components are declared by the dependency manager and can be
implemented by POJOs that contain no references to the OSGi framework
whatsoever. Components are the main building blocks of your OSGi application.
They have a life cycle, can register themselves as services and have zero or
more dependencies.</p>
+<p>You can either use the Java API or the Java Annotations and this reference
section describes both.</p>
+<h1 id="types-of-components">Types of Components</h1>
+<p>There are different types of Dependency Manager components:</p>
+<ul>
+<li><a href="component-singleton.html"><em>Component</em></a>: Components are
the main building blocks for OSGi applications. They can publish themselves as
a service, and/or they can have dependencies. These dependencies will influence
their life cycle as component will only be activated when all required
dependencies are available.</li>
+<li><a href="component-singleton.html"><em>Aspect Service</em></a>: A service
that provides a non-functional aspect on top of an existing service. In aspect
oriented programming, an aspect, or interceptor can sit between a client and
another target service used by the client. An Aspect Service first tracks a
target service and is created once the target service is detected. Then the
Aspect Service is provided, but with a higher ranking, and the client is
transparently updated with the aspect. Aspects can be chained and may apply to
the same target service (and in this case, the ranking of the Aspect service is
used to chain aspects in the proper order).</li>
+<li><a href="component-singleton.html"><em>Adapter Service</em></a>: A Service
that adapts another existing service into a new one. Like with aspects,
sometimes you want to create adapters for certain services, which add certain
behavior that results in the publication of (in this case) a different service.
Adapters can dynamically be added and removed and allow you to keep your basic
services implementations clean and simple, adding extra features on top of them
in a modular way.</li>
+<li><a href="component-singleton.html"><em>Bundle Adapter Service</em></a>:
creates an OSGi service a service on top of a given bundle.</li>
+<li><a href="component-singleton.html"><em>Resource Adapter Service</em></a>:
creates an OSGi service on top of a specific Resource.</li>
+<li><a href="component-singleton.html"><em>Factory Configuration Adapter
Service</em></a>: creates an OSGi service from ConfigAdmin, using a factoryPid,
and a ManagedServiceFactory.</li>
+</ul>
+<h1 id="component">Component</h1>
<h2 id="life-cycle">Life cycle</h2>
<p>The dependency manager, as part of a bundle, shares the generic bundle life
cycle explained in the OSGi specification. The life cycle of the dependency
manager itself, and the components it manages, can be located inside the
<em>active</em> state of the hosting bundle.</p>
<p>Each component you define gets its own life cycle, which is explained in
the state diagram below.</p>
-<p>{gliffy:name=state-diagram|align=center|size=L|version=2}</p>
+<p>TODO {gliffy:name=state-diagram|align=center|size=L|version=2}</p>
<p>A component is associated with an instance. This instance can either be
specified directly, or you can specify its class. If you do the latter, the
actual instance will be created lazily. </p>
-<p>Changes in the state of the component will trigger the following life cycle
methods:
-<em> <code>init</code>,
-</em> <code>start</code>,
-<em> <code>stop</code> and
-</em> <code>destroy</code>.</p>
-<p>The dependency manager will look for methods with these names and one of
the following signatures in this order:
-<em> (Component),
-</em> ().</p>
+<p>Changes in the state of the component will trigger the following life cycle
methods:</p>
+<ul>
+<li><code>init</code>, </li>
+<li><code>start</code>, </li>
+<li><code>stop</code> and </li>
+<li><code>destroy</code>.</li>
+</ul>
+<p>The dependency manager will look for methods with these names and one of
the following signatures in this order:</p>
+<ul>
+<li>(Component),</li>
+<li>().</li>
+</ul>
<p>If you don't specify anything, the methods with these names will be invoked
on the instance. By using <code>setCallbacks()</code> you can however change
this behavior: You can change the names of the methods to look for. Any methods
that are set to <code>null</code> will not be invoked at all. Another thing you
can do is to specify a different instance to invoke these methods on. If you do
that, you will usually want to use the first signature, which gives you a
reference to the <code>Component</code> whose life cycle method was invoked.</p>
<h2 id="interfaces-and-properties">Interfaces and properties</h2>
<p>Components in the context of the dependency manager can be published as
OSGi services under one or more interface names, plus optionally a set of
properties. This is no different than a normal OSGi service. It's important to
mention that you don't have to register a service. If you don't, you basically
created a component that can do work and have dependencies and a managed life
cycle.</p>
@@ -90,16 +106,7 @@
<h2 id="factories">Factories</h2>
<p>Out of the box, there already is support for lazy instantiation, meaning
that the dependency manager can create component instances for you when their
required dependencies are resolved. However, sometimes creating a single
instance using a default constructor is not enough. In those cases, you can
tell the dependency manager to delegate the creation process to a factory.</p>
<h1 id="annotations">Annotations</h1>
-<p>This page describes the different types of Dependency Manager
components:</p>
-<ul>
-<li><em>Component</em>: Components are the main building blocks for OSGi
applications. They can publish themselves as a service, and/or they can have
dependencies. These dependencies will influence their life cycle as component
will only be activated when all required dependencies are available.</li>
-<li><em>Aspect Service</em>: A service that provides a non-functional aspect
on top of an existing service. In aspect oriented programming, an aspect, or
interceptor can sit between a client and another target service used by the
client. An Aspect Service first tracks a target service and is created once the
target service is detected. Then the Aspect Service is provided, but with a
higher ranking, and the client is transparently updated with the aspect.
Aspects can be chained and may apply to the same target service (and in this
case, the ranking of the Aspect service is used to chain aspects in the proper
order).</li>
-<li><em>Adapter Service</em>: A Service that adapts another existing service
into a new one. Like with aspects, sometimes you want to create adapters for
certain services, which add certain behavior that results in the publication of
(in this case) a different service. Adapters can dynamically be added and
removed and allow you to keep your basic services implementations clean and
simple, adding extra features on top of them in a modular way.</li>
-<li><em>Bundle Adapter Service</em>: creates an OSGi service a service on top
of a given bundle.</li>
-<li><em>Resource Adapter Service</em>: creates an OSGi service on top of a
specific Resource.</li>
-<li><em>Factory Configuration Adapter Service</em>: creates an OSGi service
from ConfigAdmin, using a factoryPid, and a ManagedServiceFactory.</li>
-</ul>
-<h2 id="component">@Component</h2>
+<h2 id="component_1">@Component</h2>
<p>This annotation annotates an implementation class that optionally publishes
an OSGi service, and optionally has some dependencies, with a managed
lifecycle. </p>
@@ -182,9 +189,9 @@ factory that instantiated this component
be also updated with all public properties (which don't start with a dot).</p>
<p>Usage example:</p>
<div class="codehilite"><pre><span class="cm">/**</span>
-<span class="cm"> * This component will be activated once the bundle is
started and when all required dependencies</span>
-<span class="cm"> * are available.</span>
-<span class="cm"> */</span>
+<span class="cm"> * This component will be activated once the bundle is
started and when all required dependencies</span>
+<span class="cm"> * are available.</span>
+<span class="cm"> */</span>
<span class="nd">@Component</span>
<span class="kd">class</span> <span class="nc">X</span> <span
class="kd">implements</span> <span class="n">Z</span> <span class="o">{</span>
<span class="nd">@ConfigurationDependency</span><span
class="o">(</span><span class="n">pid</span><span class="o">=</span><span
class="s">"MyPid"</span><span class="o">)</span>
@@ -208,9 +215,11 @@ be also updated with all public properti
<div class="codehilite"><pre> <span class="nd">@Component</span><span
class="o">(</span><span class="n">factorySet</span><span
class="o">=</span><span class="s">"MyComponentFactory"</span><span
class="o">,</span> <span class="n">factoryConfigure</span><span
class="o">=</span><span class="s">"configure"</span><span
class="o">)</span>
<span class="kd">class</span> <span class="nc">X</span> <span
class="kd">implements</span> <span class="n">Z</span> <span class="o">{</span>
<span class="kt">void</span> <span class="nf">configure</span><span
class="o">(</span><span class="n">Dictionary</span> <span
class="n">conf</span><span class="o">)</span> <span class="o">{</span>
- <span class="c1">// Configure or reconfigure our component. The conf
is provided by the factory,</span>
- <span class="c1">// and all public properties (which don't start
with a dot) are propagated with the</span>
- <span class="c1">// Service properties eventually specified in the
properties annotation attribute.</span>
+ <span class="c1">// Configure or reconfigure our component. The conf
is provided by </span>
+ <span class="c1">// the factory, and all public properties (which
don't</span>
+ <span class="c1">// start with a dot) are propagated with the
Service</span>
+ <span class="c1">// properties eventually specified in the
properties</span>
+ <span class="c1">// annotation attribute.</span>
<span class="o">}</span>
<span class="nd">@ServiceDependency</span>
@@ -220,7 +229,8 @@ be also updated with all public properti
<span class="nd">@Start</span>
<span class="kt">void</span> <span class="nf">start</span><span
class="o">()</span> <span class="o">{</span>
- <span class="c1">// Our component is starting and is about to be
registered in the OSGi registry as a Z service.</span>
+ <span class="c1">// Our component is starting and is about to be
registered</span>
+ <span class="c1">// in the OSGi registry as a Z service.</span>
<span class="o">}</span>
<span class="kd">public</span> <span class="kt">void</span> <span
class="nf">doService</span><span class="o">()</span> <span class="o">{</span>
@@ -228,13 +238,14 @@ be also updated with all public properti
<span class="o">}</span>
<span class="o">}</span>
-<span class="cm">/**</span>
+ <span class="cm">/**</span>
<span class="cm"> * This class will instantiate some X component
instances</span>
<span class="cm"> */</span>
-<span class="nd">@Component</span>
-<span class="kd">class</span> <span class="nc">Y</span> <span
class="o">{</span>
+ <span class="nd">@Component</span>
+ <span class="kd">class</span> <span class="nc">Y</span> <span
class="o">{</span>
+ <span class="c1">// This Set acts as a Factory API for creating X
component instances.</span>
<span class="nd">@ServiceDependency</span><span class="o">(</span><span
class="n">filter</span><span class="o">=</span><span
class="s">"(dm.factory.name=MyComponentFactory)"</span><span
class="o">)</span>
- <span class="n">Set</span><span class="o"><</span><span
class="n">Dictionary</span><span class="o">></span> <span
class="n">_XFactory</span><span class="o">;</span> <span class="c1">// This Set
acts as a Factory API for creating X component instances.</span>
+ <span class="n">Set</span><span class="o"><</span><span
class="n">Dictionary</span><span class="o">></span> <span
class="n">_XFactory</span><span class="o">;</span>
<span class="nd">@Start</span>
<span class="kt">void</span> <span class="nf">start</span><span
class="o">()</span> <span class="o">{</span>
@@ -250,14 +261,15 @@ be also updated with all public properti
<span class="n">x1</span><span class="o">.</span><span
class="na">put</span><span class="o">(</span><span
class="s">"foo"</span><span class="o">,</span> <span
class="s">"bar1_modified"</span><span class="o">);</span>
<span class="n">_XFactory</span><span class="o">.</span><span
class="na">add</span><span class="o">(</span><span class="n">x1</span><span
class="o">);</span>
- <span class="c1">// Destroy all components (Notice that invoking
_XFactory.clear() also destroys every X instances)</span>
+ <span class="c1">// Destroy all components (Notice that
invoking</span>
+ <span class="c1">// _XFactory.clear() also destroys every X
instances)</span>
<span class="n">_XFactory</span><span class="o">.</span><span
class="na">remove</span><span class="o">(</span><span class="n">x1</span><span
class="o">);</span>
<span class="n">_XFactory</span><span class="o">.</span><span
class="na">remove</span><span class="o">(</span><span class="n">x2</span><span
class="o">);</span>
<span class="o">}</span>
<span class="o">}</span>
</pre></div>
<div class="timestamp" style="margin-top: 30px; font-size: 80%;
text-align: right;">
- Rev. 1664040 by marrs on Wed, 4 Mar 2015 15:21:58 +0000
+ Rev. 1664129 by marrs on Wed, 4 Mar 2015 19:59:46 +0000
</div>
<div class="trademarkFooter">
Apache Felix, Felix, Apache, the Apache feather logo, and the Apache
Felix project
Modified:
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/dependencies.html
==============================================================================
---
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/dependencies.html
(original)
+++
websites/staging/felix/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/dependencies.html
Wed Mar 4 20:00:11 2015
@@ -68,20 +68,27 @@
<h1></h1>
- <h3 id="dependencies">Dependencies</h3>
+ <h1 id="dependencies">Dependencies</h1>
<p>The dependency manager supports many different types of dependencies, all
of which can be required or optional. A dependency can be added to one or more
components and it is possible to add them dynamically (even from within the
component itself if necessary, which allows for some really dynamic dependency
configuration).</p>
-<h4 id="injection">Injection</h4>
+<h2 id="injection">Injection</h2>
<p>One way to deal with dependencies is to have them injected into your
component instances automatically. All you need to do is simply declare a field
of the same type as your dependency, make the member volatile so any changes
will become visible immediately and you're done. If a dependency is optional, a
null object will be injected if the dependency is not available.</p>
<p>Sometimes you need more control over injection, so optionally you can even
specify the name of the field to inject into. This allows you to depend on
different dependencies of the same type, or simply to prevent injection into
more than one field.</p>
-<h4 id="callbacks">Callbacks</h4>
+<h2 id="callbacks">Callbacks</h2>
<p>When keeping track of multiple instances of a dependency, or when you
simply want something to happen whenever a dependency becomes (un)available or
changes, you can define callbacks, like <code>added</code>,
<code>changed</code> and <code>removed</code>. Optionally, you can provide the
dependency manager with an instance to invoke these callback methods on. If you
don't, they'll be invoked on the component instance.</p>
-<h4 id="types-of-dependencies">Types of Dependencies</h4>
-<p>Out of the box, several types of dependencies are supported: service,
bundle, configuration, resource and temporal service. However, it's quite easy
to add your own custom type of dependency too.</p>
-<h5 id="implementing-your-own-dependency">Implementing Your Own Dependency</h5>
+<h2 id="types-of-dependencies">Types of Dependencies</h2>
+<p>Out of the box, several types of dependencies are supported:</p>
+<ul>
+<li><a href="dependency-service.html">Service</a></li>
+<li><a href="dependency-configuration.html">Configuration</a></li>
+<li><a href="dependency-bundle.html">Bundle</a></li>
+<li><a href="dependency-resource.html">Resource</a></li>
+</ul>
+<p>However, it's quite easy to add your own custom type of dependency too, as
is described below.</p>
+<h2 id="implementing-your-own-dependency">Implementing Your Own Dependency</h2>
<p>All dependencies share a common API which you can implement yourself if you
need a special type of dependency. Whilst not entirely trivial, this allows you
to create your own types of dependencies. This can be useful for various
scenarios where you want to have components that depend on things that are not
services, bundles or configuration.</p>
<p>An example implementation can be found in one of the many test cases for
the dependency manager: <code>CustomDependencyTest</code>. This implements a
dependency that can be made available and unavailable by manipulating a
<code>Toggle</code> which can be made available or unavailable. You basically
have to implement two interfaces: <code>Dependency</code> and
<code>DependencyActivation</code>. The former contains the bulk of the methods
that you will need to implement and depending on the actual features you want
your dependency to support, you have to implement some or all of them. The
JavaDoc for each method plus the example code should get you started. The
latter contains a couple of life cycle methods to start and stop tracking your
custom dependency.</p>
<div class="timestamp" style="margin-top: 30px; font-size: 80%;
text-align: right;">
- Rev. 1664040 by marrs on Wed, 4 Mar 2015 15:21:58 +0000
+ Rev. 1664129 by marrs on Wed, 4 Mar 2015 19:59:46 +0000
</div>
<div class="trademarkFooter">
Apache Felix, Felix, Apache, the Apache feather logo, and the Apache
Felix project
