felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ma...@apache.org
Subject svn commit: r1664129 - in /felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference: components.mdtext dependencies.mdtext
Date Wed, 04 Mar 2015 19:59:47 GMT
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.
-



Mime
View raw message