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/10 22:16:26 UTC
svn commit: r1665701 -
/felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/
Author: marrs
Date: Tue Mar 10 21:16:26 2015
New Revision: 1665701
URL: http://svn.apache.org/r1665701
Log:
Updated titles and some formatting.
Modified:
felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/annotations.mdtext
felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/background.mdtext
felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/design-patterns.mdtext
felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/development.mdtext
felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/history.mdtext
felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/javadocs.mdtext
felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/migrating-from-earlier-versions.mdtext
felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/migrating-from-other-solutions.mdtext
felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/performance-tuning.mdtext
felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/resources.mdtext
felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/whatsnew.mdtext
Modified: felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/annotations.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/annotations.mdtext?rev=1665701&r1=1665700&r2=1665701&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/annotations.mdtext (original)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/annotations.mdtext Tue Mar 10 21:16:26 2015
@@ -1,14 +1,9 @@
-Title: Dependency Manager SpellChecker Sample
-Excerpt: Basic concepts using a full SpellChecker sample code.
+Title: Dependency Manager - Annotations
-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.
+This section presents a quick overview of the capabilities and usage of the DependencyManager Java 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.
-## Architecture
+# Architecture
Instead of writing Activators which extends the DependencyActivatorBase class, service
components can now be annotated using the annotations provided by the
@@ -27,7 +22,7 @@ DependencyManager programmatic API in or
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.
-## Registering a Service
+# Registering a Service
To register a service, your can annotate your class with a *@Component* annotation, and
an instance of your class will be registered under all directly implemented interfaces
@@ -76,7 +71,7 @@ for invoking the proper functions.
So, coming back to the sample code, the SpellChecker class registers itself into the OSGi registry, using the *provides* attribute, which just refer to our SpellChecker class, and the two mandatory Gogo service properties are also specified using the *@Property* 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 *@Start* lifecycle callback, but we will see this feature in a another section.
-## Depending on a Service
+# Depending on a Service
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:
@@ -157,7 +152,7 @@ DictionaryService services in our dictio
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.
-## Creating a Service from ConfigAdmin
+# Creating a Service from ConfigAdmin
The *@Component* annotation is not the only one for creating services. Another one is
the *@FactoryConfigurationAdapterService* annotation which allows to instantiate many
@@ -270,7 +265,7 @@ Next, here is our DictionaryImpl that wi
}
-## Providing an Aspect
+# Providing an Aspect
As we have seen in the previous section, there are many annotations that can be used
to specify a service. Another one is the *@AspectService* annotation. This annotation
@@ -344,7 +339,7 @@ used to configure the extra English word
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.
-## How to run the sample code
+# How to run the sample code
Just import the Dependency source distribution in bndtools and check the following samples:
Modified: felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/background.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/background.mdtext?rev=1665701&r1=1665700&r2=1665701&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/background.mdtext (original)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/background.mdtext Tue Mar 10 21:16:26 2015
@@ -1,6 +1,6 @@
-Title: Apache Felix Dependency Manager - Background
+Title: Dependency Manager - Background
-## Background
+# Background
In an OSGi framework, services are deployed using bundles and these bundles feature two types of dependencies:
@@ -17,7 +17,7 @@ In real implementations, you are probabl
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.
-## Design Goals
+# Design Goals
The goals that drove the design of the dependency manager are:
Modified: felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/design-patterns.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/design-patterns.mdtext?rev=1665701&r1=1665700&r2=1665701&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/design-patterns.mdtext (original)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/design-patterns.mdtext Tue Mar 10 21:16:26 2015
@@ -1,22 +1,22 @@
-Title: Apache Felix Dependency Manager - Design Patterns
+Title: Dependency Manager - Design Patterns
-## OSGi Design Patterns
+# OSGi Design Patterns
This section lists a couple of design patterns as they can be applied in an OSGi context.
-### Singleton Service
+## Singleton Service
Provides a service as long as its dependencies are resolved.
-#### Motivation
+### Motivation
In a dynamic framework, services can come and go. Components that publish a service are often themselves dependent on other services to perform their task. In such cases, they have a dependency on those services and it makes sense to only publish their own services when these dependencies are available. Being able to declare such dependencies in code ensures consistent life cycle behavior.
-#### Structure
+### Structure
<img src="./diagrams/singleton.png" alt="Singleton" style="width: 190px"/>
-#### Code Example
+### Code Example
public class Activator extends DependencyActivatorBase {
@@ -39,19 +39,19 @@ In a dynamic framework, services can com
}
-### Aspect Service
+## Aspect Service
Provides an aspect on top of a specific type of service.
-#### Motivation
+### Motivation
In aspect oriented programming, supporting functions are isolated from the main application's business logic. This increases modularity at the source level by allowing the separation of cross-cutting concerns. In OSGi we want to extend this modularity to the runtime, therefore we implement aspects to work on certain services, where the aspect itself publishes that same service but (usually) with a higher priority. This allows you to dynamically add and remove aspects.
-#### Structure
+### Structure
<img src="./diagrams/aspect.png" alt="Aspect" style="width: 190px"/>
-#### Code Example
+### Code Example
public class Activator extends DependencyActivatorBase {
@@ -78,19 +78,19 @@ In aspect oriented programming, supporti
}
-### Adapter Service
+## Adapter Service
Provides an adapter for a specific type of service.
-#### Motivation
+### Motivation
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.
-#### Structure
+### Structure
<img src="./diagrams/adapter.png" alt="Adapter" style="width: 190px"/>
-#### Code Example
+### Code Example
public class Activator extends DependencyActivatorBase {
@@ -119,45 +119,45 @@ Like with aspects, sometimes you want to
}
-### Resource Adapter Service
+## Resource Adapter Service
Provides an adapter for a specific type of resource.
-#### Motivation
+### Motivation
Resource adapters are similar to normal adapters, but instead of requiring a service, they require a resource and provide a service on top of it. Resources are an abstraction that is introduced by the dependency manager, represented as a URL. They can be implemented to serve resources embedded in bundles, somewhere on a file system or in a content repository or database.
-#### Structure
+### Structure
<img src="./diagrams/resourceadapter.png" alt="Singleton" style="width: 180px"/>
-### Temporal Dependency
+## Temporal Dependency
Provides a proxy that hides the service dynamics of a dependency, even if it disappears for a short time.
-#### Motivation
+### Motivation
As a service consumer, you sometimes do not want to deal with the dynamics of services and the fact that they tend to go away for short periods of time whilst their hosting bundle gets updated. A temporal dependency provides you with a proxy that hides these dynamics and blocks your calls if you try to invoke a method on a service that is currently "updating". The maximum time to wait is configurable and you will get an exception if no new service becomes available before that time.
-#### Structure
+### Structure
-### Null Object
+## Null Object
Provides an implementation of an object that does nothing and can be used in the absence of the real object.
-#### Motivation
+### Motivation
When a component depends on a service, but the dependency is optional, it means that it will use this service when available, but it can still operate if it's not. Constantly checking in your code if a service is actually available tends to lead to code with a lot of "`if (service != null) service.invoke();`" constructions which do not help with code readability. Instead, the dependency manager offers you a mechanism where it will inject null objects for services that are currently not available so you can simply invoke methods on them that "do nothing".
-#### Structure
+### Structure
-### Whiteboard
+## Whiteboard
Handles listeners by leveraging the OSGi service registry to publish and look them up.
-#### Motivation
+### Motivation
The traditional model for dealing with listeners in Java needlessly complicates things in an OSGi context. Instead of having listeners registering themselves with the component that will invoke them on any change, a listener simply registers itself in the service registry and the component will do a lookup of all relevant services. This is explained in more detail on the OSGi.org wiki in the ["Listeners considered harmful: the 'whiteboard' pattern"](http://www.osgi.org/wiki/uploads/Links/whiteboard.pdf) article.
-#### Structure
+### Structure
Modified: felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/development.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/development.mdtext?rev=1665701&r1=1665700&r2=1665701&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/development.mdtext (original)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/development.mdtext Tue Mar 10 21:16:26 2015
@@ -1,12 +1,12 @@
-Title: Apache Felix Dependency Manager - Development
+Title: Dependency Manager - Development
When downloading or checking out the source code, please also consult release/resources/src/README.src for up to date instructions on how to build that particular version.
-## Prerequisites
+# Prerequisites
If you are building a released `org.apache.felix.dependencymanager-r<n>-src.zip` artifact, then you also have to extract the `org.apache.felix.dependencymanager-r<n>-deps.zip` in the same directory where you have extracted the source archive. There is no need to do this if you have checked out from the Felix trunk in Subversion.
-## Compilation Using gradle:
+# Compilation Using gradle:
- Install Java 7.
@@ -26,7 +26,7 @@ If you are building a released `org.apac
$ ./gradlew check
-## Compilation Using Eclipse:
+# Compilation Using Eclipse:
- Install either Eclipse Kepler SR2 or Eclipse Luna.
- Use the dependency manager folder as the root of your workspace.
Modified: felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/history.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/history.mdtext?rev=1665701&r1=1665700&r2=1665701&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/history.mdtext (original)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/history.mdtext Tue Mar 10 21:16:26 2015
@@ -1,12 +1,12 @@
-Title: Apache Felix Dependency Manager - History
+Title: Dependency Manager - History
-## The early years
+# The early years
The first version of the Dependency Manager was created when Marcel started working on his first commercial OSGi project back in 2002. At that time, the OSGi specification was still at R2, and the only solution for managing dependencies was "service binder" which did not support the dynamics we needed at that time. Therefore, dependency manager was created, based on a fluent, declarative Java API.
In 2005, after writing a white paper, dependency manager was presented at the OSGi DevCon in Paris. At that time, the project had been open sourced, but not yet at Apache. When the Oscar project finally decided to move to the incubator, where it became Felix, Dependency Manager was one of the subprojects that joined.
-## Life at Apache
+# Life at Apache
The move to Apache definitely gave the project a lot more visibility and, besides a larger user base, also attracted a few very talented developers. Xander did a lot of work in getting some of the higher level design patterns implemented, and Pierre added support for annotations and ensured that the code ran well on really big, multi-core systems.
Modified: felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/javadocs.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/javadocs.mdtext?rev=1665701&r1=1665700&r2=1665701&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/javadocs.mdtext (original)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/javadocs.mdtext Tue Mar 10 21:16:26 2015
@@ -1,5 +1,4 @@
-Title: Apache Felix Dependency Manager - Javadocs
-Excerpt: Dependency Manager javadocs
+Title: Dependency Manager - JavaDocs
-The various Dependency Manager javadocs for the API, the Annotations, and the Runtime can be found from the [main felix apidocs homepage](http://felix.apache.org/apidocs/).
+The various Dependency Manager JavaDocs for the API, the Annotations, and the Runtime can be found from the [main felix apidocs homepage](http://felix.apache.org/apidocs/).
Modified: felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/migrating-from-earlier-versions.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/migrating-from-earlier-versions.mdtext?rev=1665701&r1=1665700&r2=1665701&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/migrating-from-earlier-versions.mdtext (original)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/migrating-from-earlier-versions.mdtext Tue Mar 10 21:16:26 2015
@@ -65,6 +65,3 @@ For example:
</build>
</project>
-# Migrating from version 2
-
-...
Modified: felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/migrating-from-other-solutions.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/migrating-from-other-solutions.mdtext?rev=1665701&r1=1665700&r2=1665701&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/migrating-from-other-solutions.mdtext (original)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/migrating-from-other-solutions.mdtext Tue Mar 10 21:16:26 2015
@@ -1,6 +1,6 @@
Title: Apache Felix Dependency Manager - Migrating from other solutions
-TODO
+Watch this space! :)
# Declarative Services
Modified: felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/performance-tuning.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/performance-tuning.mdtext?rev=1665701&r1=1665700&r2=1665701&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/performance-tuning.mdtext (original)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/performance-tuning.mdtext Tue Mar 10 21:16:26 2015
@@ -1,6 +1,6 @@
-Title: Apache Felix Dependency Manager - Performance Tuning
+Title: Dependency Manager - Performance Tuning
-### Filter Indices
+# Filter Indices
Filter indices allow you to speed up the service resolution process by skipping the services registry, in favor of a fast index on given service properties.
@@ -16,11 +16,11 @@ The implementation ships with three kind
- *Aspect indices* work with Dependency Manager Aspect services, and will provide indexing for the specific filters that they use.
- *Adapter indices* work like Aspect indices, but for Adapter services.
-#### Performance
+## Performance
The index isn't free, but reduces the linear (and wasteful) filter-based lookup to an indexed log(n) lookup. You can expect noticeable speedup if you have at least several hundred services.
-#### Examples
+## Examples
-Dorg.apache.felix.dependencymanager.filterindex=objectClass
Sets an index on `objectClass`, speeding up lookups for any filter that contains an `objectClass` in its filter (all regular services do).
Modified: felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/resources.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/resources.mdtext?rev=1665701&r1=1665700&r2=1665701&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/resources.mdtext (original)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/resources.mdtext Tue Mar 10 21:16:26 2015
@@ -1,4 +1,4 @@
-Title: Resource adapters
+Title: Dependency Manager - Resource adapters
Resource adapters are a special type of adapters which can adapt a resource into an OSGi service. These resources can be all kinds of resources, e.g. bundle resources, files, database records, anything as long as it can be resolved though a URL.
Modified: felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/whatsnew.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/whatsnew.mdtext?rev=1665701&r1=1665700&r2=1665701&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/whatsnew.mdtext (original)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager/guides/whatsnew.mdtext Tue Mar 10 21:16:26 2015
@@ -1,6 +1,6 @@
-Title: Apache Felix Dependency Manager - What's new in version 4?
+Title: Dependency Manager - What's new in version 4?
-## New thread model
+# New thread model
DependencyManager 4.0 has been significantly reworked to improve support for concurrency. The following principles form the basis of the new concurrency model in DM4.
@@ -25,7 +25,7 @@ Here, all components will be handled by
You will find a full description of the new thread model in the [Reference](../reference/thread-model.html) section.
-## New features
+# New features
In addition, some new features have been implemented in dependency manager:
@@ -54,7 +54,7 @@ Use "add-require-capability=true" option
* The Annotations "Factory Sets" are deprecated (FELIX-4684): You can now use a DS-like ComponentFactory API by a nice api which is exported by the runtime bundle.
See this [example](https://svn.apache.org/repos/asf/felix/trunk/dependencymanager/org.apache.felix.dependencymanager.samples/src/org/apache/felix/dependencymanager/samples/device/annot/DeviceAndParameterFactory.java) from the samples in the source distribution.
-## Sample codes
+# Sample code
The source distribution includes many sample codes which can be run directly under Eclipse and BndTools. The samples are available in the
org.apache.felix.dependencymanager.samples/ module.