Author: marrs
Date: Wed Mar 4 19:59:46 2015
New Revision: 1664129
URL: http://svn.apache.org/r1664129
Log:
Reformatted component and dependencies pages.
Modified:
felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/components.mdtext
felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/dependencies.mdtext
Modified:
felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/components.mdtext
URL:
http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/components.mdtext?rev=1664129&r1=1664128&r2=1664129&view=diff
==============================================================================
---
felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/components.mdtext
(original)
+++
felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/components.mdtext
Wed Mar 4 19:59:46 2015
@@ -2,23 +2,40 @@ Title: Apache Felix Dependency Manager -
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.
+You can either use the Java API or the Java Annotations and this reference
section describes both.
+
+# Types of Components
+
+There are different types of Dependency Manager components:
+
+* [*Component*](component-singleton.html): 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.
+* [*Aspect Service*](component-singleton.html): 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).
+* [*Adapter Service*](component-singleton.html): 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.
+* [*Bundle Adapter Service*](component-singleton.html): creates an OSGi
service a service on top of a given bundle.
+* [*Resource Adapter Service*](component-singleton.html): creates an OSGi
service on top of a specific Resource.
+* [*Factory Configuration Adapter Service*](component-singleton.html): creates
an OSGi service from ConfigAdmin, using a factoryPid, and a
ManagedServiceFactory.
+
+# Component
+
## Life cycle
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
*active* state of the hosting bundle.
Each component you define gets its own life cycle, which is explained in the
state diagram below.
-{gliffy:name=state-diagram|align=center|size=L|version=2}
+TODO {gliffy:name=state-diagram|align=center|size=L|version=2}
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.
Changes in the state of the component will trigger the following life cycle
methods:
+
* `init`,
* `start`,
* `stop` and
* `destroy`.
The dependency manager will look for methods with these names and one of the
following signatures in this order:
+
* (Component),
* ().
@@ -38,14 +55,6 @@ Out of the box, there already is support
# Annotations
-This page describes the different types of Dependency Manager components:
-
-* *Component*: 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.
-* *Aspect Service*: 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).
-* *Adapter Service*: 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.
-* *Bundle Adapter Service*: creates an OSGi service a service on top of a
given bundle.
-* *Resource Adapter Service*: creates an OSGi service on top of a specific
Resource.
-* *Factory Configuration Adapter Service*: creates an OSGi service from
ConfigAdmin, using a factoryPid, and a ManagedServiceFactory.
## @Component
@@ -146,9 +155,9 @@ Usage example:
:::java
/**
- * This component will be activated once the bundle is started and when
all required dependencies
- * are available.
- */
+ * This component will be activated once the bundle is started and when
all required dependencies
+ * are available.
+ */
@Component
class X implements Z {
@ConfigurationDependency(pid="MyPid")
@@ -173,9 +182,11 @@ Example using a factorySet, where the X
@Component(factorySet="MyComponentFactory", factoryConfigure="configure")
class X implements Z {
void configure(Dictionary conf) {
- // Configure or reconfigure our component. The conf is provided
by the factory,
- // and all public properties (which don't start with a dot) are
propagated with the
- // Service properties eventually specified in the properties
annotation attribute.
+ // Configure or reconfigure our component. The conf is provided
by
+ // the factory, and all public properties (which don't
+ // start with a dot) are propagated with the Service
+ // properties eventually specified in the properties
+ // annotation attribute.
}
@ServiceDependency
@@ -185,7 +196,8 @@ Example using a factorySet, where the X
@Start
void start() {
- // Our component is starting and is about to be registered in the
OSGi registry as a Z service.
+ // Our component is starting and is about to be registered
+ // in the OSGi registry as a Z service.
}
public void doService() {
@@ -193,13 +205,14 @@ Example using a factorySet, where the X
}
}
- /**
+ /**
* This class will instantiate some X component instances
*/
- @Component
- class Y {
+ @Component
+ class Y {
+ // This Set acts as a Factory API for creating X component instances.
@ServiceDependency(filter="(dm.factory.name=MyComponentFactory)")
- Set<Dictionary> _XFactory; // This Set acts as a Factory API for
creating X component instances.
+ Set<Dictionary> _XFactory;
@Start
void start() {
@@ -215,7 +228,8 @@ Example using a factorySet, where the X
x1.put("foo", "bar1_modified");
_XFactory.add(x1);
- // Destroy all components (Notice that invoking _XFactory.clear()
also destroys every X instances)
+ // Destroy all components (Notice that invoking
+ // _XFactory.clear() also destroys every X instances)
_XFactory.remove(x1);
_XFactory.remove(x2);
}
Modified:
felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/dependencies.mdtext
URL:
http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/dependencies.mdtext?rev=1664129&r1=1664128&r2=1664129&view=diff
==============================================================================
---
felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/dependencies.mdtext
(original)
+++
felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/dependencies.mdtext
Wed Mar 4 19:59:46 2015
@@ -1,24 +1,30 @@
-### Dependencies
+# Dependencies
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).
-#### Injection
+## Injection
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.
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.
-#### Callbacks
+## Callbacks
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 `added`, `changed` and `removed`.
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.
-#### Types of Dependencies
+## Types of Dependencies
-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.
+Out of the box, several types of dependencies are supported:
-##### Implementing Your Own Dependency
+* [Service](dependency-service.html)
+* [Configuration](dependency-configuration.html)
+* [Bundle](dependency-bundle.html)
+* [Resource](dependency-resource.html)
+
+However, it's quite easy to add your own custom type of dependency too, as is
described below.
+
+## Implementing Your Own Dependency
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.
An example implementation can be found in one of the many test cases for the
dependency manager: ` CustomDependencyTest `. This implements a dependency that
can be made available and unavailable by manipulating a ` Toggle ` which can be
made available or unavailable. You basically have to implement two interfaces:
` Dependency ` and ` DependencyActivation `. 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.
-
