You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@felix.apache.org by ma...@apache.org on 2015/03/04 20:59:47 UTC
svn commit: r1664129 - in
/felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference:
components.mdtext dependencies.mdtext
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.
-