You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@felix.apache.org by dj...@apache.org on 2021/07/11 23:13:54 UTC
[felix-antora-site] 05/18: remove ipojo doc (unmaintained)
This is an automated email from the ASF dual-hosted git repository.
djencks pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/felix-antora-site.git
commit 59ddb56a6e0c064d6c01ba2b5625c1d3f61d98cf
Author: David Jencks <dj...@apache.org>
AuthorDate: Sun Jul 11 15:40:09 2021 -0700
remove ipojo doc (unmaintained)
---
modules/ROOT/pages/documentation/subprojects.adoc | 5 +-
.../subprojects/apache-felix-ipojo.adoc | 50 --
.../dive-into-the-ipojo-manipulation-depths.adoc | 244 -----
.../how-to-use-ipojo-manipulation-metadata.adoc | 85 --
.../how-to-write-your-own-handler.adoc | 985 ---------------------
.../apache-felix-ipojo-eclipse-integration.adoc | 72 --
.../apache-felix-ipojo-feature-overview.adoc | 51 --
.../apache-felix-ipojo-dosgi.adoc | 161 ----
.../how-to-use-ipojo-annotations.adoc | 377 --------
.../ipojo-advanced-tutorial.adoc | 602 -------------
.../ipojo-composition-tutorial.adoc | 620 -------------
.../ipojo-hello-word-maven-based-tutorial.adoc | 547 ------------
.../ipojo-in-10-minutes.adoc | 609 -------------
.../apache-felix-ipojo-junit4osgi.adoc | 30 -
...apache-felix-ipojo-junit4osgi-architecture.adoc | 43 -
.../apache-felix-ipojo-junit4osgi-maven.adoc | 225 -----
.../apache-felix-ipojo-junit4osgi-methods.adoc | 84 --
.../apache-felix-ipojo-junit4osgi-tutorial.adoc | 345 --------
.../apache-felix-ipojo-keypoints.adoc | 70 --
.../apache-felix-ipojo-successstories.adoc | 69 --
.../apache-felix-ipojo-supportedosgi.adoc | 53 --
.../apache-felix-ipojo-supportedvms.adoc | 74 --
.../apache-felix-ipojo-testing-components.adoc | 104 ---
.../apache-felix-ipojo-online-manipulator.adoc | 61 --
.../apache-felix-ipojo-tools/ipojo-ant-task.adoc | 129 ---
.../ipojo-arch-command.adoc | 179 ----
.../ipojo-karaf-feature.adoc | 24 -
.../ipojo-maven-plug-in.adoc | 241 -----
.../ipojo-webconsole-plugin.adoc | 73 --
.../apache-felix-ipojo-tools/junit4osgi.adoc | 219 -----
.../apache-felix-ipojo-api.adoc | 375 --------
.../apache-felix-ipojo-instances.adoc | 427 ---------
.../describing-components.adoc | 34 -
.../describing-components/Callback.jpeg | Bin 9842 -> 0 bytes
.../architecture-handler.adoc | 65 --
.../configuration-handler.adoc | 181 ----
.../controller-lifecycle-handler.adoc | 61 --
.../event-admin-handlers.adoc | 345 --------
.../extender-pattern-handler.adoc | 148 ----
.../injecting-bundle-context.adoc | 72 --
.../describing-components/ipojo-jmx-handler.adoc | 291 ------
.../lifecycle-callback-handler.adoc | 168 ----
.../providing-osgi-services.adoc | 435 ---------
.../service-requirement-handler.adoc | 867 ------------------
.../temporal-service-dependency.adoc | 187 ----
.../white-board-pattern-handler.adoc | 159 ----
.../instance-vs-service-controller.adoc | 84 --
.../ipojo-advanced-topics.adoc | 9 -
.../combining-ipojo-and-configuration-admin.adoc | 306 -------
...tructing-pojo-objects-with-factory-methods.adoc | 42 -
.../how-to-use-ipojo-factories.adoc | 298 -------
.../ipojo-extender-configuration.adoc | 145 ---
.../ipojo-factory-service.adoc | 169 ----
.../ipojo-hierarchical-composition-overview.adoc | 313 -------
.../service-binding-interceptors.adoc | 241 -----
.../using-ipojo-introspection-api.adoc | 274 ------
.../ipojo-advanced-topics/using-stereotypes.adoc | 94 --
.../apache-felix-ipojo-userguide/ipojo-faq.adoc | 431 ---------
.../using-xml-schemas.adoc | 68 --
.../apache-felix-ipojo-why-choose-ipojo.adoc | 107 ---
.../articles-and-presentations.adoc | 18 -
.../developing-camel-mediators-with-ipojo.adoc | 164 ----
.../subprojects/apache-felix-ipojo/download.adoc | 118 ---
.../subprojects/apache-felix-ipojo/ipojo-news.adoc | 89 --
.../apache-felix-ipojo/ipojo-reference-card.adoc | 904 -------------------
.../apache-felix-ipojo/ipojo-support.adoc | 29 -
.../apache-felix-ipojo/related-works.adoc | 18 -
67 files changed, 1 insertion(+), 14166 deletions(-)
diff --git a/modules/ROOT/pages/documentation/subprojects.adoc b/modules/ROOT/pages/documentation/subprojects.adoc
index ec0e33e..ba582b2 100644
--- a/modules/ROOT/pages/documentation/subprojects.adoc
+++ b/modules/ROOT/pages/documentation/subprojects.adoc
@@ -64,10 +64,6 @@ If this project is not using Maven, refer to the docs for the subproject on how
| A simple and extensible framework to retrieve inventory information about applications running in an OSGi Framework.
| https://github.com/apache/felix-dev/tree/master/inventory[source]
-| xref:documentation/subprojects/apache-felix-ipojo.adoc[iPOJO]
-| A sophisticated service-oriented component model to simplify OSGi-based development.
-| https://github.com/apache/felix-dev/tree/master/ipojo[source]
-
| xref:documentation/subprojects/apache-felix-log.adoc[Log]
| A simple, memory-based implementation of the OSGi Log service specification.
| https://github.com/apache/felix-dev/tree/master/log[source]
@@ -121,6 +117,7 @@ The last documentation may be found in the https://github.com/apache/felix-site-
* https://github.com/apache/felix-site-pub/blob/last-cms/documentation/subprojects/apache-felix-autoconf.html[Auto Configuration]
* https://github.com/apache/felix-site-pub/blob/last-cms/documentation/subprojects/apache-felix-commons.html[Commons]
* https://github.com/apache/felix-site-pub/blob/last-cms/documentation/subprojects/apache-felix-deployment-admin.html[Deployment Admin]
+* https://github.com/apache/felix-site-pub/blob/last-cms/documentation/subprojects/apache-felix-ipojo.html[iPOJO]
* xref:documentation/subprojects/apache-felix-jaas.adoc[JAAS Support]
* xref:documentation/subprojects/apache-felix-lightweight-http-service.adoc[Lightweight HTTP Service]
* xref:documentation/subprojects/apache-felix-manifest-generator-mangen.adoc[Manifest Generator (mangen)]
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo.adoc
deleted file mode 100644
index 78885fe..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo.adoc
+++ /dev/null
@@ -1,50 +0,0 @@
-= Apache Felix iPOJO
-
-image::/ipojo/ipojo-logo-150.png[]
-
-current iPOJO release: {{ipojo.release}}
-current iPOJO snapshot: {{ipojo.snapshot}}
-
-== What's iPOJO ?
-
-*iPOJO* is a _service component runtime_ aiming to simplify OSGi application development.
-It natively supports *ALL* the dynamism of OSGi.
-iPOJO is made to run modern applications exhibiting modularity and requiring runtime adaption and autonomic behavior.</p> image:/ipojo/cubes.png[]
-
-== Main features
-
-* __ Components are developed as POJOs - no dependencies or complex API
-* __ Use annotations, XML or a fluent API to declare your components and instances
-* __ Require and provide services without requiring code, while being amazingly powerful
-* __ iPOJO applications are natively resilient to dynamism
-* __ Extensible and customizable, develop your own component model
-* __ iPOJO applications are supporting dynamic adaptation, and exhibit autonomic behavior
-
-== Why choose iPOJO
-
-* xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-successstories.adoc#schneider[iPOJO at Schneider Electric]
-* xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-successstories.adoc#ugasp[iPOJO at Ubidreams]
-* xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-successstories.adoc[others success stories]
-* xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-keypoints.adoc[iPOJO Key points]
-* xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-why-choose-ipojo.adoc[Why choose iPOJO]
-
-== Getting started
-
-* __ http://repo1.maven.org/maven2/org/apache/felix/org.apache.felix.ipojo.distribution.quickstart/{{ipojo.release}}/org.apache.felix.ipojo.distribution.quickstart-{{ipojo.release}}.zip[Quickstart Distribution]
-* xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-in-10-minutes.adoc[iPOJO in 10 minutes]
-* xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/how-to-use-ipojo-annotations.adoc[Using Annotations]
-* xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-hello-word-maven-based-tutorial.adoc[Maven tutorial]
-* xref:documentation/subprojects/apache-felix-ipojo/ipojo-support.adoc[Support]
-
-== The developer corner
-
-* xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components.adoc[Describing components]
-* xref:documentation/subprojects/apache-felix-ipojo/ipojo-reference-card.adoc[iPOJO Reference Card]
-* xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-eclipse-integration.adoc[Eclipse Integration]
-* xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/apache-felix-ipojo-online-manipulator.adoc[Online Manipulator]
-* xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-faq.adoc[FAQ]
-
-'''
-
-== News {{ refs.ipojo-news.headers.excerpt|markdown }}
-__ [all news\...]({{ refs.ipojo-news.path }})
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/dive-into-the-ipojo-manipulation-depths.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/dive-into-the-ipojo-manipulation-depths.adoc
deleted file mode 100644
index f6ffd79..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/dive-into-the-ipojo-manipulation-depths.adoc
+++ /dev/null
@@ -1,244 +0,0 @@
-= Dive into the iPOJO Manipulation depths
-
-iPOJO (primitive) components are managed using byte code manipulation.
-Don't be afraid, you don't have to be fluent in byte code to understand components.
-This page explains how the manipulation works and how your class file is transformed.
-This manipulation takes care to *NOT* change the behavior of the manipulated class.
-
-
-
-== Why manipulate bundle byte code?
-
-The iPOJO byte code manipulation goals are two-fold:
-
-* Preparing classes to be managed at run time and
-* Translating XML or annotation metadata into an internal format to avoid run-time XML and annotation parsing.
-
-image::documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/process.png[]
-
-[cols=2*]
-|===
-| iPOJO follows a container approach and more specially employs http://en.wikipedia.org/wiki/Inversion_of_control[inversion of control] and [dependency injections
-| http://en.wikipedia.org/wiki/Dependency_injection].
-The iPOJO container manages component instantiation and injection (service, properties and so on...).
-To inject values and supervise the execution inside component implementation class, iPOJO uses an interception and injection framework.
-To facilitate this, iPOJO uses class byte code manipulation.
-|===
-
-image::documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/injection.png[]
-
-Besides manipulating byte code, iPOJO translates the XML or annotation metadata to an internal syntax.
-This eliminates any run-time dependencies on the particular metadata format.
-
-== How bundle byte code is manipulated
-
-For each class used as a component implementation class, the manipulation process prepares the class to be managed at run time.
-This means providing the ability to intercept methods and field accesses.
-This manipulation is independent of the component metadata.
-A component class will always result in the same final manipulated class, regardless of its metadata.
-This means it is possible to use a class as the implementation of several component types.
-As illustrated in the following image, the manipulated class instance interacts with an instance manager that delegates to handlers.
-The metadata impacts the set of handlers;
-it does not impact the manipulated class, nor the instance manager (which is the iPOJO container foundation).
-
-image::documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/principles.png[]
-
-The following image explains what happens during the manipulation.
-
-image::documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/manipulation.png[]
-
-First, each manipulated class implements the `POJO` interface.
-This interface introduces a method to get a reference to the instance container.
-So, you can detect whether an object is managed by iPOJO by checking if the object implements this interface.
-A special field, named `\*\*IM` is injected, which contains a reference to the instance container object (`InstanceManager` at run time.
-
-For each field, getter and setter methods are generated.
-They are called `\*\*get$FIELD*NAME` and `\*\*set$FIELD*NAME`.
-A boolean field is injected named `\*\*F$FIELD_NAME`.
-This flag enables or disables the container delegation for this field.
-When delegation is disabled, the field is managed as a regular field: getter and setter methods just return and set the field value.
-When delegation is enabled, the field never receives a value, the container stores the field value.
-The getter method asks the container to get the value.
-The setter method asks to the container to update the stored value.
-All the field accesses (except ones from specific constructors) of the class are adapted to call the getter or the setter method.
-
-In order to intercept methods, each method is substituted by a generated method.
-Each method is renamed to `\*\*METHOD_NAME` and becomes private.
-The original method is replaced by iPOJO code.
-This code allows method interception.
-As with fields, method delegation is enabled or disabled by an injected boolean field.
-If the method is not to be intercepted, the iPOJO-generated method just calls the original method.
-Otherwise, the iPOJO-generated method notifies the container of method entries, exits, and potential errors.
-
-Finally, the constructors are also manipulated.
-Empty constructors and constructors receiving a `BundleContext` object are manipulated as others methods.
-However, they receive another argument: the `InstanceManager`.
-This instance manager is set just after the call to the super constructor.
-While setting the instance manager, all flags enabling/disabling delegation are set.
-This allows the component to use injected values inside the constructor code itself.
-Constructors receiving other kind of arguments are not manipulated, and so can be used to create non-managed instance.
-In this case, fields won't be delegated, and methods won't be intercepted.
-
-=== The annotation special case
-
-The manipulation has a special behavior when a visible (at run time) method or constructor annotation is detected.
-As the methods are replaced by private methods, the annotations are moved to the iPOJO-generated methods, such as in:
-
-[source,java]
- public class MyClass {
- @MyAnnotation
- public void myMethod() {
- //my code here
- }
- }
-
-is transformed into:
-
-[source,java]
- public class MyClass {
- @MyAnnotation
- public void myMethod() {
- // iPojo code here
- }
- private void _myMethod() {
- // my code here
- }
-
-== Avoiding XML at run time
-
-iPOJO does not use XML or annotations at run time.
-The manipulation process replaces the XML or annotation metadata by an internal format (between LISP and XML).
-The XML or annotation metadata are translated and written into the bundle manifest.
-Additionally, various type information in the component metadata is computed during the byte code manipulation phase to avoid having to use reflection at run time (which would require loading the class) to get class elements (such as available fields, methods, implemented interfaces, and so on).
-
-If you want to see how XML or annotation metadata are _tortured_, just open the manifest file of a manipulated bundle, and look at the `iPOJO-COMPONENTS` entry (and appreciate the Lisp-like syntax :-))...
-
-== Extending manipulator
-
-Annotations are more and more used to provide a simple and elegant programming model.
-iPOJO had supported generic annotations (`@Component`, `@Handler`, ...) for a long time.
-But supporting your own annotations and bind them to a particular handler in iPOJO was awkward (naming conventions, id and parent resolution, ...).
-
-For example, how to re-use an external annotation (let's say `@javax.inject.Inject`) that do not respect the iPOJO naming convention ?
-Or how can you contribute information to the component's metadata when an annotation is found ?
-
-The solution is to extend the manipulator with new annotation' support.
-
-=== Annotation Binding Module
-
-That can be done through the implementation of a `Module`:
-
-[source,java]
-----
-import org.apache.felix.ipojo.manipulator.spi.AbsBindingModule;
-import org.apache.felix.ipojo.manipulator.spi.AnnotationVisitorFactory;
-import org.apache.felix.ipojo.manipulator.spi.BindingContext;
-import org.objectweb.asm.AnnotationVisitor;
-
-public class SampleBindingModule extends AbsBindingModule {
-
- public void configure() {
- // When @Hello is found, execute the provided AnnotationVisitor
- bind(Hello.class)
- .to(new AnnotationVisitorFactory() {
- public AnnotationVisitor newAnnotationVisitor(BindingContext context) {
- return new HelloVisitor(context.getWorkbench());
- }
- });
- }
-}
-----
-
-The `AbsBindingModule.configure()` method has to be implemented by each new Module.
-It contains the annotation binding specification(s).
-An annotation binding simply declares what to do when a given annotation is found.
-
-In the example case, when the `@Hello` annotation is encountered in a class' bytecode, the manipulator will find an annotation binding for `@Hello` and call it's `AnnotationVisitorFactory.newAnnotationVisitor()` method to obtain a dedicated `AnnotationVisitor` (here `HelloVisitor`).
-
-=== Visitors
-
-Here are the `@Hello` annotation and `HelloVisitor` class for better understanding:
-
-[source,java]
- @Target(ElementType.TYPE)
- public @interface Hello {
- String name();
- }
-
-The `@Hello` annotation has a mandatory `name` attribute.
-
-[source,java]
-----
-public class HelloVisitor extends EmptyVisitor implements AnnotationVisitor {
-
- private Element hello = new Element("hello", "org.apache.felix.ipojo.sample");
-
- private ComponentWorkbench workbench;
-
- public HelloVisitor(ComponentWorkbench workbench) {
- this.workbench = workbench;
- }
-
- /**
- * Visit @Hello annotation attributes.
- */
- public void visit(String name, Object value) {
- if (name.equals("name")) {
- hello.addAttribute(new Attribute("name", value.toString()));
- return;
- }
- }
-
- /**
- * Append to the "component" element computed attribute.
- */
- public void visitEnd() {
- workbench.getElements().put(hello, null);
- }
-}
-----
-
-The `HelloVisitor` is an ASM `AnnotationVisitor`.
-`AnnotationVisitor.visit(String, Object)` is called for each declared attribute of the annotation.
-Declared means that if an attribute is non-mandatory and was not part of the annotation declaration, it will not be visible by the `AnnotationVisitor`.
-Each attribute is visited only once.
-In HelloVisitor we only react to the `name` attribute, and store its value as an Attribute in the Element.
-
-Finally, in `visitEnd()`, we contribute our Element to the workbench.
-
-=== Declaring the Module
-
-Last work to do: declare the new `Module` in a `META-INF/services/org.apache.felix.ipojo.manipulator.spi.Module` file:
-
-[source,sh]
- org.apache.felix.ipojo.sample.SampleBindingModule
-
-At this point, we can use the jar file that contains the extension within the manipulator.
-In maven, it's as simple as adding a plugin dependency to the `maven-bundle-plugin` (in addition of the `bnd-ipojo-plugin`).
-In ant, It's probably a matter of changing the classpath.
-
-=== Finally
-
-At the end, all this mechanics will help you to simply your code from:
-[source,xml]
- <ipojo xmlns:s="org.apache.felix.ipojo.sample">
- <component ...>
- <s:hello name="Guillaume" />
- </component>
- </ipojo>
-
-with a non-annotated component's class:
-
-[source,java]
- public class MyComponent {
- // ...
- }
-
-to a more elegant (and concise), with no XML:
-
-[source,java]
- @Component
- @Hello(name = "Guillaume")
- public class MyComponent {
- // ...
- }
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/how-to-use-ipojo-manipulation-metadata.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/how-to-use-ipojo-manipulation-metadata.adoc
deleted file mode 100644
index 533fb80..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/how-to-use-ipojo-manipulation-metadata.adoc
+++ /dev/null
@@ -1,85 +0,0 @@
-= How to use iPOJO Manipulation Metadata
-
-_During the manipulation process, iPOJO gathers information about the manipulated classes.
-These metadata are stored inside the bundle manifest and are used to avoid reflection on the manipulated class.
-By using these metadata, your handler can check that the implementation class contains required fields, methods, check implemented interfaces._
-
-
-
-== Contained information
-
-Manipulation metadata contains:
-
-* Interfaces implemented by component type implementation
-* Fields of the component type implementation
-* Methods of the component type implementation
-
-Field Metadata contains field name and type.
-Method Metadata contains method name, the sorted list of argument types and return type.
-
-== Building Manipulation Metadata
-
-Manipulation (i.e.
-PojoMetadata) can be obtained form the factory of a (primitive) component type such as in:
-
-[source,java]
- public void configure(InstanceManager im, Element metadata, Dictionary configuration) {
- ...
- PojoMetadata manipulation = getFactory().getPojoMetadata();
- ...
- }
-
-== Getting Metadata
-
-From the manipulation metadata, you can query manipulation information by using following methods:
-
-* `MethodMetadata[] getMethods()` : Get all methods
-* `FieldMetadata[] getFields()` : Get all fields
-* `String[] getInterfaces()` : Get all implemented interfaces
-* `FieldMetadata getField(String name)` : Look for the field with the given name.
-Returns null if not found.
-* `FieldMetadata getField(String name, String type)`: Look for the field with the given name and type.
-Returns null if not found.
-* `boolean isInterfaceImplemented(String itf)` : Is the given interface name implemented by the manipulated class.
-* `MethodMetadata getMethod(String name)` : Look for the method with the given name.
-Returns null if not found.
-Returns the first found if several method match.
-* `MethodMetadata[] getMethods(String name)` : Look for all methods with the given name.
-Returns an empty array if not found.
-* `MethodMetadata getMethod(String name, String[] types)` : Look for the method with the given name and argument type list.
-Returns null if not found.
-
-From a Field Metadata object, you can obtain the field name, type, and 'reflective' type.
-From a Method Metadata object, you can obtain the method name, the argument type array, and the returned type ('void' for void method).
-
-== Creating Callback from Manipulation Metadata
-
-You often need to invoke method on the POJO objects.
-iPOJO provides an helper class, named Callback, allow you to manage this invocation easily.
-You can obtain a Callback object from the Method Metadata.
-By this way, you are sure that the method exists in the implementation.
-To create the callback, use the following code:
-
-[source,java]
- PojoMetadata manip = getFactory().getPojoMetadata();
- MethodMetadata method = manip.getMethod("your_method_name");
- Callback cb = new Callback(method, im);
-
-Then you can directly invoke your method:
-
-[source,java]
- Object[] args = ...; // Build your argument array
- cb.call(args);
- ...
-
-== Types & Reflective Types
-
-When querying field (or a method argument) type, the API returns following code identifiers:
-
-* For primitive types : int, long, short, byte, char, double, float, boolean
-* For primitives type arrays : int[], long[], short[], byte[], char[], double[], float[], boolean[]
-* For object : qualified class name as java.lang.String
-* For object arrays : the qualified class name of the content type followed by [] as java.lang.String[]
-
-Array types are different from Java internal/reflective array types.
-To get the internal/reflective array type for field type you can use the `getReflectiveType` method.
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/how-to-write-your-own-handler.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/how-to-write-your-own-handler.adoc
deleted file mode 100644
index a7d3192..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/how-to-write-your-own-handler.adoc
+++ /dev/null
@@ -1,985 +0,0 @@
-= How to write your iPOJO Handler
-
-_This document explains how developers can use iPOJO extensibility mechanism to extend the (primitive) component instance container.
-Such extensibility mechanism does not require to modify the iPOJO core._
-
-
-
-First, iPOJO concepts are briefly explained.
-The second section explains the steps to create a handler.
-The two last sections describes the implementation and the usage of two small example handlers : a Log Handler, logging messages inside the OSGi log service, and a Property Handler, injecting properties values inside fields.
-
-The code is available in this link:{attachmentsdir}/ipojo/ipojo-handler-tutorial-project.zip[archive file].
-
-== iPOJO Concepts
-
-iPOJO is a service oriented component model aiming to simplify OSGi applications development.
-iPOJO is based on the POJO concepts.
-A POJO is a simple Java class without any dependency on its runtime environment.
-In iPOJO, POJO are encapsulated in a container managing the relation between the POJO and the external world.
-This container keeps separated the POJO from the external "wild" world.
-Moreover, this container can be extended, using handlers.
-
-Basically, iPOJO contains two main concepts: component type and component instance.
-A component type is a type of component.
-A component type defines its implementation class, its creation policy, and its container.
-A component instance is a configured instance of a component type.
-This instance is created with the component type factory.
-A component instance inherits of all component type characteristics but has a unique name and its own configuration (set of <key, value>).
-
-Above these concepts, iPOJO runtime will manage component type factories and component instances.
-Each component instance is managed separately (but the factory can delete them).
-
-A component type declares its container configuration.
-Each component instance owns its container conform to the component type container configuration.
-An iPOJO container is composed by an `InstanceManager`, encapsulating the POJO, on which are plugged handlers.
-A handler manages one non functional concern.
-Handlers participate to the component instance lifecycle;
-can interact with the POJO;
-can manage relations with external entity like database, or other POJOs...
-For example, a persistence handler may interact with a database to store and inject POJO state, while an administration handler may use JMX to allow remote configuration of instance properties.
-
-image::documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/POJO-Container-Handler.png[]
-
-iPOJO is an extensible model allowing developer to manage other non functional concerns.
-Indeed, handlers can be developed singly, without modifying the iPOJO core.
-At runtime, iPOJO looks for each handler needed by a component instance and plugs an instance of each (required) handler on the container.
-So iPOJO containers are flexible, light and adaptable to each component.
-When a needed handler cannot be found, the component instance cannot be created.
-
-An external handler is identified by a namespace.
-This namespace will be used by developers to refer to the external handler (when he configures its component type) and by iPOJO to instantiate the handler object.
-
-iPOJO core contains 6 "core" handlers managing service providing, service dependencies, lifecycle callbacks, lifecycle controller, instance dynamic configuration, and component instance architecture.
-Theses handlers follow the same rules than external handlers, except that they use the iPOJO default namespace (i.e.
-`org.apache.felix.ipojo`).
-
-== Handler development basis
-
-=== Fundamentals
-
-As explain above, the handler interacts with the POJO, with the component's container and with the external world (e.g.
-: other components, services, bundles, the OSGi framework, ...).
-The skeleton of such an agent is defined in iPOJO is defined by the `PrimitiveHandler` (abstract) class that can be found in the `org.apache.felix.ipojo` package.
-
-You need to implement the three basic lifecycle methods of this class, but you can extends this model by redefining some other methods (e.g.
-: to intercept POJO method calls, field accesses, ...).
-
-=== Declaring your handler
-
-You first need to declare your handler, so iPOJO will be able to initialize, configure and use it when needed.
-First, you must give a name and a namespace to your handler.
-By doing that, iPOJO can recognize that a certain component uses your handler, so it can initialize it.
-You need to declare, using the `@Handler` annotations.
-You can, of course, declare several handlers, and even declare components using these handlers, in the same bundle.
-
-[source,java]
- @Handler(name = "Log", namespace = LogHandler.NAMESPACE)
- public class LogHandler extends PrimitiveHandler {
- public static final String NAMESPACE = "org.apache.felix.ipojo.log.handler";
- // ...
- }
-
-Then, you must know that a handler is a component (almost) like standard iPOJO components : it can use other handlers (like core handlers : service requirements, provided services, ...).
-You can consequently describe your handler's required services, provided services, etc.
-
-In order to use iPOJO annotations processing, the namespace must be a valid package name and the name must be a valid annotation name (without the '@').
-Refer to the <<annotations,annotations>> section.
-
-=== Handler lifecycle
-
-A handler lifecycle is composed of four different states.
-
-image::documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/Handler-Lifecycle.png[]
-
-* First, when iPOJO parses the metadata of a bundle, it detects that a certain component type use your handler (using XML qualified names, see the following _Using your handler_ section).
-When it finds such a reference, it initializes the handler by calling the `initializeComponentFactory()` method.
-This method should be static but actually can't be so for some technical reasons.
-Consequently, a _mock_ instance of the handler is created, the `initializeComponentFactory()` method is called, and this instance is destroyed.
-This method aims to check the validity of the component type description, avoiding starting invalid factories.If you override this method, you should here set up the component description (e.g.
-: common properties, exported services, ...) and check the handler configuration.
-The parameters passed to this method are the `ComponentTypeDescription` and the component's `Metadata` (i.e.
-: the structure of the component type declaration).
-* Once your handler has been initialized, iPOJO configures it for each created instance of the using components.
-The `ComponentTypeDescription` and the instance specific properties are passed to the `configure()` method of your handler.This method is mandatory so you have to implement it.
-Here you should check the handler configuration (if not already done in the `initializeComponentFactory()` method) and configure the handler with given instance specific properties.
-* Then, iPOJO starts the handler, following the component instance lifecycle, by calling the `start()` method.
-You have to put in this method the activation code of your handler.
-A freshly started handler is by default in an active state (if all its used handlers, like required services, are in an active state).
-* Once started, the handler state can be either in a valid or in an invalid state, depending on its used handlers (a handler is an iPOJO component, so it can depend on other handlers, like service dependencies, provided services, ...
-See the _Handler extends Component_ section).
-The validity of your handler depends on used handlers status, but it also can be changed in your handler code by using the `setValidity()` method.
-* Finally, when the component instance is stopped (generally just before being destroyed), the stop method of the handler is called.
-Place here the inactivation code of your handler.
-
-Keep in mind that the `stop()` method of your handler is called when the component instance is stopped (not necessarily destroyed).
-This instance can be restarted later, so the same instance of your handler must have to ability to restart too.
-
-=== Reading handler and instance configurations
-
-Your handler need to read how it is configured in the using component type description.
-The configuration is written in the `metadata.xml` of the using bundle, but is passed to the `initializeComponentFactory()` and `configure()` methods as an `Element` object.
-
-The `Element` type (from the `org.apache.felix.ipojo.metadata package`), coupled with the `Attribute` type, is used to retrieve the structure and the content of the component configuration.
-The `Element` parameter, passed to the initialization and configuration methods, represents the root of the component type description (i.e.
-the root of the tree is the `component` tag).
-
-Several methods allows to browse the entire configuration from the root `Element` :
-
-* The `getElement()` methods let you access the content of an `Element` (i.e.
-the children elements)
-* The `getAttribute()` methods allows you to access the attributes of an `Element`.
-* The `containsElement()` and `containsAttribute()` methods test the presence of a child-element or an attribute in an `Element`.
-
-_Note :_ As described in the <<description,description>> section, a name and a namespace are associated to each handler.
-To safely retrieve the configuration of this handler from the component metadata, you can take inspiration from the following snippet (the `componentMetadata` variable is the component root `Element` passed to the `initializeComponentFactory()` and `configure()` methods) :
-
-[source,java]
- Element[] log_elements = metadata.getElements("log", NAMESPACE);
-
-For example, the log handler provided in the archive file has the following configure method:
-
-[source,java]
-----
-/**
- * Parses the component's metadata to retrieve the log level in which we log messages.
- *
- * @param metadata component's metadata
- * @param configuration instance configuration (unused in this example)
- * @throws ConfigurationException the configuration is inconsistent
- */
-@Override
-public void configure(Element metadata, Dictionary configuration) throws ConfigurationException {
- // First parse the metadata to check if the log handler logLevel
-
- // Get all Namespace:log element from the metadata
- Element[] log_elements = metadata.getElements("log", NAMESPACE);
-
- // If an element match, parse the logLevel attribute of the first found element
- if (log_elements[0].containsAttribute("level")) {
- String l = log_elements[0].getAttribute("level");
- if (l.equalsIgnoreCase("info")) {
- logLevel = LogService.LOG_INFO;
- } else if (l.equalsIgnoreCase("error")) {
- logLevel = LogService.LOG_ERROR;
- } else if (l.equalsIgnoreCase("warning")) {
- logLevel = LogService.LOG_WARNING;
- }
- }
-
- instanceManager = getInstanceManager();
-}
-----
-
-You can also access instance configuration (properties defined in the `instance` tag).
-The instance properties are directly passed, as a `Dictionary,` to the `configure()` method.
-With these properties, you can easily allow instances to override some component fixed configuration.
-The property handler given in the archive file extract the location of the loaded properties file from the instance configuration:
-
-[source,java]
- // Look if the instance overrides file location :
- String instanceFile = (String) configuration.get("properties.file");
- if (instanceFile != null) {
- m_file = instanceFile;
- }
-
-=== Interacting with the POJO
-
-One of the most interesting features of an handler is the ability to interact with the component's POJO.
-Indeed, you can intercept method calls and returns, inject values in the POJO's fields...
-
-The `getPojoMetadata()` method of the PrimitiveHandler class lets you access the structure of the POJO (represented by the `PojoMetadata` type) without having to use (slow) reflection.
-It allows you to list all fields and methods of the POJO, and get informations about implemented interfaces and the super-class.
-The `PojoMetadata` class implements the following operations :
-
-* The `getInterfaces()` method returns the list of implemented interfaces, while the `isInterfaceImplemented()` methods test if a given interface is implemented by the POJO.
-* The `getSuperClass()` method returns the name of the class extended by the POJO (or `null` instead of `java.lang.Object`).
-* The `getField()` methods lets you access the fields of the POJO.
-The returned object is a `FieldMetadata` that provides information about a particular field inside the POJO.
-* The `getMethod()` methods lets you access the methods of the POJO.
-The returned object is a `MethodMetadata` that provides information about a particular method in the POJO.
-
-Once you've retrieved informations about the POJO structure, you can interact with it, via the `InstanceManager`, accessible in your handler by the `getInstanceManager()` method.
-It allows you to register interceptors, that are called before and after POJO method calls or field accesses.
-
-The property handler is registering field interceptors on injected properties:
-
-[source,java]
-----
-//First get Pojo Metadata metadata :
-PojoMetadata pojoMeta = getPojoMetadata();
-Enumeration e = m_properties.keys();
-while (e.hasMoreElements()) {
- String field = (String) e.nextElement();
- FieldMetadata fm = pojoMeta.getField(field);
-
- if (fm == null) { // The field does not exist
- throw new ConfigurationException("The field " + field + " is declared in the properties file but does not exist in the pojo");
- }
-
- // Then check that the field is a String field
- if (!fm.getFieldType().equals(String.class.getName())) {
- throw new ConfigurationException("The field " + field + " exists in the pojo, but is not a String");
- }
-
- // All checks are ok, register the interceptor.
- getInstanceManager().register(fm, this);
-}
-----
-
-The InstanceManager manages the component instance attached to your handler instance.
-Thus, it can't be available in the `initializeComponentFactory()` because this method is run before the creation of any component instance.
-
-You need to implement some of the following methods to intercept fields accesses :
-
-* The `void onSet(Object pojo, String fieldName, Object value)` method: This method is called each time a field of the POJO is assigned.
-The first parameter is the instance of the concerned POJO, the second is the name of the accessed field and the third is the value assigned to the POJO's field.
-If the field type is a primitive type, this method receives the boxed object.
-* The `Object onGet(Object pojo, String fieldName, Object value)` method : This method is called each time a field of the POJO is read.
-The first parameter is the instance of the concerned POJO, the second is the name of the accessed field and the third is the actual value of the POJO's field.
-If the field type is a primitive type, this method receives the boxed object.
-The returned object is the value the intercepted read process will return.
-It's the standard way to inject a value in the field : returning a specific object whatever the field really contains.
-
-The property handler contains the following ``onGetz and ``onSet` methods:
-
-[source,java]
-----
-/**
- * This method is called at each time the pojo 'get' a listened field. The method return the stored value.
- * @param pojo : pojo object getting the field
- * @param field : field name.
- * @param o : previous value.
- * @return the stored value.
- */
-public Object onGet(Object pojo, String field, Object o) {
- // When the pojo requires a value for a managed field, this method is invoked.
- // So, we have just to return the stored value.
- return m_properties.get(field);
-}
-
-/**
- * This method is called at each time the pojo 'set' a listened field. This method updates the local properties.
- * @param pojo : pojo object setting the field
- * @param field : field name
- * @param newvalue : new value
- */
-public void onSet(Object pojo, String field, Object newvalue) {
- // When the pojo set a value to a managed field, this method is invoked.
- // So, we update the stored value.
- m_properties.put(field, newvalue);
-}
-----
-
-You need to implements some of the following methods to intercept methods accesses.
-When these methods are called, the first parameter is the POJO's instance on which the intercepted method is called and the second parameter contains the descriptor of the called method.
-
-* The `void onEntry(Object pojo, Member method, Object[] args)` method: This method is called before the execution of an intercepted method.
-The third parameter is the list of parameters with which the method have been called.
-The method is executed just after the execution of the `onEntry()` callback.
-* The `void onExit(Object pojo, Member method, Object returnedObj)` method: This method is called right after the successful execution of an intercepted method.
-The third parameter is the value returned by the method (or `null` if the method return type is `void`).
-This value must not be modified.
-* The `void onError(Object pojo, Member method, Throwable throwable)` method: This method is called right after the unexpected return of an intercepted method (i.e.
-when an uncaught exception occurred).
-The third parameter is the thrown object that caused the method termination.
-* The `void onFinally(Object pojo, Member method)` method: This method is called after the termination of an intercepted method (expected or not), after the call of the `onExit()` or `onError()` callback.
-
-The `InstanceManager` has to know your handler wants to intercept fields or methods access, otherwise the implemented callbacks won't be called.
-Thus you need to register each field and method you want to intercept, so the `InstanceManager` will call the appropriated callbacks when the specified field or method is accessed :
-
-The `PrimitiveHandler` abstract class implements the `FieldInterceptor` and `MethodInterceptor` interfaces, which declares the methods described just above.
-You can create your own interceptor class (implementing one or both of these interfaces) and give it to the `InstanceManager` register method instead of the handler object itself.
-
-=== Using your handler
-
-Once your handler has been declared, you can use it in iPOJO components.
-To do so, you first have to be bound to your handler's namespace (using standard XML namespace declaration).
-Then you can configure the handler in your components type description.
-An example of bundle's `metadata.xml` declaring components using the handler is shown hereafter :
-[source,xml]
- <ipojo xmlns:your-shortcut="the.namespace.of.your.handler">
- ...
- <component className="your.component.class">
- ...
- <your-shortcut:HandlerName param1="value1" ...>
- <!--
- Configuration of your handler for
- this component type
- -->
- </your-shortcut:HandlerName>
- ...
- </component>
- ...
- </ipojo>
-
-Obviously, you probably want to use annotations.
-You just have to provide the annotation classes: `handler_namespace.handler_element`.
-For instance, the log handler provides the `org.apache.felix.ipojo.log.handler.Log` annotation:
-
-[source,java]
-----
-package org.apache.felix.ipojo.log.handler;
-
-/**
- * The annotation used to configure the LogHandler.
- */
-public @interface Log {
-
- public enum Level {
- INFO, ERROR, WARNING
- }
-
- /**
- * @return the log level
- */
- Level level();
-}
-----
-
-The remainder of this document describes two examples of handlers:
-
-* A log handler logging messages in the OSGi Log Service
-* A properties handler reading a property files to configure POJO field
-
-== Log Handler example
-
-This section describes how to create a simple handler.
-This handler logs a message in the _OSGi Log Service_ (if present) when the component instance state changes.
-
-=== Handler metadata
-
-The handler namespace is `org.apache.felix.ipojo.log.handler.LogHandler`.
-It is also the name of the handler implementation class.
-You can note that the handler has an optional dependency on a OSGi log service.
-
-[source,java]
-----
-// Declare a handler.
-@Handler(name = "Log", namespace = LogHandler.NAMESPACE)
-public class LogHandler extends PrimitiveHandler {
-
- public static final String NAMESPACE = "org.apache.felix.ipojo.log.handler";
-
- // Handlers are iPOJO components, so can use service dependencies
- @Requires(optional = true, nullable = false)
- LogService log;
- private InstanceManager instanceManager;
- private int logLevel;
-
-//...
-----
-
-=== Handler implementation
-
-The handler needs to override following methods:
-
-* `configure` : to parse the metadata and load the properties file
-* `stateChanged` : to log messages when the instance state changes.
-
-==== LogHandler class
-
-The handler is implemented inside the `LogHandler` class in the `org.apache.felix.ipojo.handler.log` package.
-This class extends the `org.apache.felix.ipojo.PrimitiveHandler` class.
-The handler needs to be notified when component instances becomes valid or invalid, thus it implements the `InstanceStateListener` interface.
-
-==== Configure Method
-
-This method reads the component description and configures the handler.
-Then, the handler registers itself to the instance manager to be informed of the component's validity changes.
-
-[source,java]
-----
-/**
- * Parses the component's metadata to retrieve the log level in which we log messages.
- *
- * @param metadata component's metadata
- * @param configuration instance configuration (unused in this example)
- * @throws ConfigurationException the configuration is inconsistent
- */
-@Override
-public void configure(Element metadata, Dictionary configuration) throws ConfigurationException {
- // First parse the metadata to check if the log handler logLevel
-
- // Get all Namespace:log element from the metadata
- Element[] log_elements = metadata.getElements("log", NAMESPACE);
-
- // If an element match, parse the logLevel attribute of the first found element
- if (log_elements[0].containsAttribute("level")) {
- String l = log_elements[0].getAttribute("level");
- if (l.equalsIgnoreCase("info")) {
- logLevel = LogService.LOG_INFO;
- } else if (l.equalsIgnoreCase("error")) {
- logLevel = LogService.LOG_ERROR;
- } else if (l.equalsIgnoreCase("warning")) {
- logLevel = LogService.LOG_WARNING;
- }
- }
-
- instanceManager = getInstanceManager();
-}
-----
-
-==== StateChanged Method
-
-This method is called by the instance manager to notify that the component instance state changes.
-The handler needs to log a message containing the new state.
-
-[source,java]
- /**
- * Logging messages when the instance state is changing
- *
- * @param state the new state
- */
- public void stateChanged(int state) {
- if (log != null) {
- if (state == InstanceManager.VALID) {
- System.out.println("The component instance " + instanceManager.getInstanceName() + " becomes valid");
- log.log(logLevel, "The component instance " + instanceManager.getInstanceName() + " becomes valid");
- }
- if (state == InstanceManager.INVALID) {
- System.out.println("The component instance " + instanceManager.getInstanceName() + " becomes invalid");
- log.log(logLevel, "The component instance " + instanceManager.getInstanceName() + " becomes invalid");
- }
- }
- }
-
-=== Start and Stop
-
-The handler also contains two methods called by the instance manager when the underlying instance starts and stops.
-
-[source,java]
-----
-/**
- * The instance is starting.
- */
-public void start() {
- if (log != null) {
- log.log(logLevel, "The component instance " + instanceManager.getInstanceName() + " is starting");
- }
-}
-
-/**
- * The instance is stopping.
- */
-public void stop() {
- if (log != null) {
- log.log(logLevel, "The component instance " + instanceManager.getInstanceName() + " is stopping");
- }
-}
-----
-
-== Handler packaging
-
-This handler needs to be packaged inside an iPOJO bundle.
-The bundle will import the `org.apache.felix.ipojo`, `org.osgi.framework` and `org.osgi.service.log` packages.
-
-=== Handler usage
-
-To use this handler, a component use the `Log` annotation, with a level attribute.
-This level attribute's value can be `"error"`, `"warning"` or `"info"`.
-Here is an usage example:
-
-[source,java]
-----
-package org.apache.felix.ipojo.log.handler.example;
-
-import org.apache.felix.ipojo.annotations.*;
-import org.apache.felix.ipojo.foo.FooService;
-import org.apache.felix.ipojo.log.handler.Log;
-
-@Component(immediate = true)
-@Log(level = Log.Level.INFO) // We configure the handler.
-@Instantiate(name = "my.simple.consumer")
-public class SimpleComponent {
-
- @Requires
- FooService fs;
-
- @Validate
- public void starting() {
- System.out.println("Starting...");
- fs.foo();
- }
-
- @Invalidate
- public void stopping() {
- System.out.println("Stopping...");
- }
-}
-----
-
-=== Playing with the handler
-
-The archive contains a project named `Log-Handler-In-Felix`, which once built, provides a Felix framework with all the bundles deployed.
-
-Unzip the archive, and build the whole project using Maven: `mvn clean install`.
-It builds the log handler and the property handler.
-Then navigate to the felix-framework-VERSION directory:
-
-[source,sh]
- mvn clean install
- #...
- cd Log-Handler-In-Felix/target/felix-framework-4.2.1/
- java -jar bin/felix.jar
-
-Once you have launched Felix, you get the Gogo Shell prompt:
-
-[source,sh]
-----
-Starting...
-Foo
-The component instance my.simple.consumer becomes valid
-____________________________
-Welcome to Apache Felix Gogo
-
-g! lb
-START LEVEL 1
- ID|State |Level|Name
- 0|Active | 0|System Bundle (4.2.1)
- 1|Active | 1|Apache Felix Bundle Repository (1.6.6)
- 2|Active | 1|Apache Felix Gogo Command (0.12.0)
- 3|Active | 1|Apache Felix Gogo Runtime (0.10.0)
- 4|Active | 1|Apache Felix Gogo Shell (0.10.0)
- 5|Active | 1|Apache Felix iPOJO (1.8.6)
- 6|Active | 1|Apache Felix iPOJO Gogo Command (1.0.1)
- 7|Active | 1|iPOJO Log Handler Consumer (1.9.0.SNAPSHOT)
- 8|Active | 1|iPOJO Foo Service (1.9.0.SNAPSHOT)
- 9|Active | 1|iPOJO Log Handler (1.9.0.SNAPSHOT)
- 10|Active | 1|Apache Felix Log Service (1.0.1)
-g!
-----
-
-You can already see some of the messages printed by the handler (`The component instance my.simple.consumer becomes valid`).
-To see more message, stop and start the Foo Service bundle:
-
-[source,sh]
- g! stop 8
- The component instance my.simple.consumer becomes invalid
- Stopping...
- g! start 8
- g! Starting...
- Foo
- The component instance my.simple.consumer becomes valid
-
-By stopping the Foo service bundle, you withdrew the foo service from the service registry making our component invalid (and unhappy).
-The handler is notified of the new state and logs a message.
-When the bundle restarts, the service is republished.
-So the instance becomes valid again.
-The handler is notified and logs another message.
-
-== Properties Handler example
-
-This section presents a second handler.
-This handler loads a property file containing field name and initial value.
-Then it injects and maintains these values inside POJO fields.
-In this example, only String values are managed.
-
-This handler is always valid, so do not participate to the component instance lifecycle.
-Moreover, the handler does not need to be notified when the component instance state changed.
-But, it need to be notified when POJO fields need a value or change their value.
-
-=== Handler implementation
-
-The handler needs to override following methods:
-
-* `configure` : to parse the metadata and load the properties file
-* `stop` : to store the properties
-* `onGet` : to inject a values inside a field
-* `onSet` : to obtain the new field value
-
-==== PropertiesHandler class
-
-The handler is implemented by the `PropertiesHandler` class present in the `org.apache.felix.ipojo.properties.handler` package.
-The class has several fields:
-
-* The properties to maintain (`m_properties`)
-* The properties file name (`m_file`)
-
-NOTE: the file name is the absolute path on the local machine of the file.
-
-[source,java]
-----
-/**
- * This handler load a properties file containing property value.
- * The handler injects this values inside fields. When stopped the handler stores updated value inside the file. The
- * properties file contains <pre>field-name : field-value</pre> (field-value are strings)
- *
- * Instances can override file locations by setting the {@literal properties.file} property.
- *
- * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
- */
-@Handler(name="properties", namespace = PropertiesHandler.NAMESPACE)
-public class PropertiesHandler extends PrimitiveHandler {
-
- /**
- * The Handler namespace.
- */
- public static final String NAMESPACE = "org.apache.felix.ipojo.handler.properties";
-
- /**
- * The loaded properties.
- */
- private Properties m_properties = new Properties();
-
- /**
- * The properties file location, configured in the component's metadata.
- */
- private String m_file;
-----
-
-==== Configure Method
-
-This method begins by parsing the component type metadata.
-The handler needs a properties element from its namespace.
-According to the result, the configure method can return immediately or parse the file attribute (to get the properties file path).
-Then, it builds a field list (String array) to register to field notification.
-By registering with a field array, the handler is going to be notified of field access.
-
-[source,java]
-----
-/**
- * This method is the first to be invoked.
- * This method aims to configure the handler. It receives the component type metadata and the instance
- * configuration. The method parses given metadata and registers fields to inject.
- *
- * Step 3 : when the instance configuration contains the properties.file property, it overrides the properties file location.
- *
- * @param metadata : component type metadata
- * @param configuration : instance description
- * @throws ConfigurationException : the configuration of the handler has failed.
- */
-@SuppressWarnings("unchecked")
-public void configure(Element metadata, Dictionary configuration) throws ConfigurationException {
- // Get all elements to configure the handler
- Element[] elem = metadata.getElements("properties", NAMESPACE);
-
- switch (elem.length) {
- case 0:
- // No matching element in metadata, throw a configuration error.
- // It actually happen only if you force the handler to be plugged.
- throw new ConfigurationException("No properties found");
- case 1:
- // One 'properties' found, get attributes.
- m_file = elem[0].getAttribute("file");
- if (m_file == null) {
- // if file is null, throw a configuration error.
- throw new ConfigurationException("Malformed properties element : file attribute must be set");
- }
- break;
- default:
- // To simplify we handle only one properties element.
- throw new ConfigurationException("Only one properties element is supported");
- }
-
- // Look if the instance overrides file location :
- String instanceFile = (String) configuration.get("properties.file");
- if (instanceFile != null) {
- m_file = instanceFile;
- }
-
- // Load properties
- try {
- loadProperties();
- } catch (IOException e) {
- throw new ConfigurationException("Error when reading the " + m_file + " file : " + e.getMessage());
- }
-
- // Register fields
- // By convention, properties file entry are field name, so look for each property to get field list.
-
- //First get Pojo Metadata metadata :
- PojoMetadata pojoMeta = getPojoMetadata();
- Enumeration e = m_properties.keys();
- while (e.hasMoreElements()) {
- String field = (String) e.nextElement();
- FieldMetadata fm = pojoMeta.getField(field);
-
- if (fm == null) { // The field does not exist
- throw new ConfigurationException("The field " + field + " is declared in the properties file but does not exist in the pojo");
- }
-
- // Then check that the field is a String field
- if (!fm.getFieldType().equals(String.class.getName())) {
- throw new ConfigurationException("The field " + field + " exists in the pojo, but is not a String");
- }
-
- // All checks are ok, register the interceptor.
- getInstanceManager().register(fm, this);
- }
-}
-----
-
-Notice that the handler is using the instance configuration.
-So instances can set their own file location using the `properties.file` property.
-
-==== The start and stop methods
-
-The start method does nothing, but needs to be implemented.
-
-[source,java]
- public void start() {}
-
-The stop method stores properties inside the properties file.
-
-[source,java]
- public void stop() {
- try {
- saveProperties();
- } catch (IOException e) {
- // Log an error message by using the iPOJO logger
- error("Cannot read the file : " + m_file, e);
- }
- m_properties = null;
- }
-
-==== onGet and onSet methods
-
-The onGet method is called when the POJO need a field value.
-When called, the method needs to return the stored value.The onSet method is called when the POJO modifies a field value.
-If the new value if null, the handler will remove this properties from the property list.
-
-[source,java]
-----
-public Object onGet(Object pojo, String field, Object o) {
- // When the pojo requires a value for a managed field,
- // this method is invoked.
- // So, we have just to return the stored value.
- return m_properties.get(field);
-}
-
-public void onSet(Object pojo, String field, Object newvalue) {
- // When the pojo set a value to a managed field,
- // this method is invoked.
- // So, we update the stored value.
- m_properties.put(field, newvalue);
-}
-----
-
-=== Creating the annotation
-
-The handler provides an annotation to ease its use:
-
-[source,java]
-----
-package org.apache.felix.ipojo.handler.properties;
-
-/**
- * The Properties annotation.
- * This annotation may be used in POJO class to used the Property handler.
- * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
- */
-public @interface Properties {
-
- /**
- * Returns the property file used by the handler.
- */
- String file();
-
-}
-----
-
-=== Handler packaging
-
-This handler needs to be inside a bundle importing the `org.apache.felix.ipojo` packages and exporting the `org.apache.felix.ipojo.properties.handler` package.
-
-=== Playing with the handler
-
-As for the log handler , the archive contains a felix distribution with all bundles deployed.
-
-[source,sh]
- cd Property-Handler-In-Felix/target/felix-framework-4.2.1/
- java -jar bin/felix.jar
-
-In Gogo you immediately see the loaded properties:
-
-[source,sh]
- -- listing properties --
- property2="bbb"
- property1="aaa"
- PropertiesTester is starting ...
- Property 1 : "aaa"
- Property 2 : "bbb"
- Update properties
- -- listing properties --
- property2="bbb"
- property1="aaa"
- PropertiesTester is starting ...
- Property 1 : "aaa"
- Property 2 : "bbb"
- Update properties
- ____________________________
- Welcome to Apache Felix Gogo
- g!
-
-In this example, we have two instances of the same component type loading different properties files.
-The first instance loads the default properties file.
-The second one is configured to read another one.
-This configuraiton is given in the instance configuration:
-[source,xml]
- <ipojo>
- <!-- Declare an instance illustrating instance configuration -->
- <instance component="PropertiesTester"
- name="instance-using-properties-i1">
- <property name="props.file"
- value="props\properties-i1.properties" />
- </instance>
- </ipojo>
-
-== Advanced topics
-
-=== Handler reconfiguration
-
-iPOJO has the ability to reconfigure component instances while they are running.
-When instances are reconfigured, their used handler need to update their configuration (if they support such an operation).
-To do so, reconfigurable handlers must override the `reconfigure()` method, which notify the concerned handlers of the new instance configuration (represented as a `Dictionary`).
-
-
-[#description]
-=== Describing your handler
-
-Handlers have the possibility to describe their state, overriding the `getDescription()` method and the `HandlerDescription` class.
-By default, only the handler's name and validity are displayed in component instance's description (informations displayed by the (`arch -instance an.instance.name` command).
-The standard way to add description to your handler is shown hereafter :
-
-[source,java]
- public class YourHandler extends PrimitiveHandler {
- ...
- // Method returning the handler description.
- public HandlerDescription getDescription() {
- return new YourHandlerDescription(this);
- }
-
- ...
-
- private class YourHandlerDescription extends HandlerDescription {
- public Description(PrimitiveHandler h) { super(h); }
-
- // Method returning the custom description of this handler.
- public Element getHandlerInfo() {
- // Needed to get the root description element.
- Element elem = super.getHandlerInfo();
- // Add here attributes and sub-elements
- // into the root description element.
- // Example : elem.addAttribute(new Attribute("param", "value"));
- Element subElement = new Element("subElement", "");
- subElement.addAttribute(new Attribute("subParam", "subValue"));
- elem.addElement(subElement);
- ...
- return elem;
- }
- }
- }
-
-[#annotations]
-== Handler's annotations
-
-Your handle can also provide annotations.
-Annotations will allows users to configure the Handler from the source code (avoiding XML edition).
-iPOJO supports annotation of external handlers.
-Indeed, it detects annotations and re-creates the `Element-Attribute` structure.
-So, first, external Handler annotations _MUST_ follow some principles:
-
-* The annotation package must be the Handler namespace
-* The annotation name must be the Handler name
-* The package must contain either the 'ipojo' or the 'handler' word.
-
-So, when iPOJO detects the annotation, an Element is created with the annotation package as the `Element namespace` and the annotation name as the `Element name`.
-Then, 'scalar' annotation attributes are mapped to Attribute.
-Sub-annotations (annotation attribute) are mapped to sub-elements.
-For example, the annotation for the property handler is:
-
-[source,java]
-----
-package org.apache.felix.ipojo.properties.handler;
-
-import java.lang.annotation.ElementType;
-import java.lang.annotation.Target;
-
-@Target(ElementType.TYPE)
-public @interface Properties {
-
- String file();
-
-}
-----
-
-This annotations is put on the {\{class}} element, and allows setting the property file:
-
-[source,java]
- @Component
- @Properties(file="/Users/clement/felix/properties/i1.properties")
- public class Example {
- ...
- }
-
-However, your handler can also provide several annotations to represent Element and sub-elements.
-Your annotations can also be placed on different code elements (Type, Field, Method).
-In this case, to recreate the Element/Sub-Element hierarchy, iPOJO processes as following:
-
-* The first annotation of a package `P` is processed by creating the root Element (component sub-element).
-* All others annotations of the package `P` are processed as sub-element of the previously created Element.
-
-For example, the following code:
-
-[source,java]
-----
-import org.apache.felix.ipojo.annotations.Component;
-import org.apache.felix.ipojo.handlers.jmx.Config;
-import org.apache.felix.ipojo.handlers.jmx.Method;
-import org.apache.felix.ipojo.handlers.jmx.Property;
-
-@Component
-@Config(domain="my-domain", usesMOSGi=false) // External handler annotation
-public class JMXSimple {
-
- @Property(name="prop", notification=true, rights="w") //External handler annotation
- String m_foo;
-
- @Method(description="set the foo prop") //External handler annotation
- public void setFoo(String mes) {
- System.out.println("Set foo to " + mes);
- m_foo = mes;
- }
-
- @Method(description="get the foo prop") //External handler annotation
- public String getFoo() {
- return m_foo;
- }
-}
-----
-
-will be translated to:
-
-[source,sh]
- component {
- $classname="org.apache.felix.ipojo.test.scenarios.component.jmx.JMXSimple"
- $public="true" $name="org.apache.felix.ipojo.test.scenarios.component.jmx.JMXSimple"
- org.apache.felix.ipojo.handlers.jmx:config {
- $usesmosgi="false" $domain="my-domain"
- org.apache.felix.ipojo.handlers.jmx:property {
- $rights="w" $notification="true" $field="m_foo" $name="prop" }
- org.apache.felix.ipojo.handlers.jmx:method {
- $description="set the foo prop" $method="setFoo" }
- org.apache.felix.ipojo.handlers.jmx:method {
- $description="get the foo prop" $method="getFoo" }
- }
- }
-
-NOTE: To customize this hierarchy, you can also use the `id/parent` annotation attributse.
-The id attribute is used to refer to an Element.
-An annotation with a `parent` (targeting an `id`) attribute will be processed as a sub-element of the Element identified by the given `id`.
-
-[#schemas]
-== Handler's XSD
-
-Coming soon...
-
-== Conclusion
-
-In this document, we present how-to develop handler for your components.
-We describe two small examples : a log handler and a properties handler.
-These handlers are plugged on (primitive) instance.
-However, it is possible to extends `CompositeHandler` too to customize the composition model.
-
-If you develop handler and you want to share it, feel free to contact us by sending a mail on the Felix mailing list.
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-eclipse-integration.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-eclipse-integration.adoc
deleted file mode 100644
index 5311ffe..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-eclipse-integration.adoc
+++ /dev/null
@@ -1,72 +0,0 @@
-= Building and Running iPOJO bundles from Eclipse
-
-_This page explains how to build and run iPOJO bundles without exiting Eclipse and breaking the compile-run cycle.
-Bundles are executed inside Equinox._
-
-
-
-== 1) Import the iPOJO Bundle project
-
-Download the link:MyiPOJOBundle-1.4.2.zip[project archive], and import it as an _Existing Project into the Workspace_
-
-image:documentation/subprojects/apache-felix-ipojo/Picture 1.png[] image:documentation/subprojects/apache-felix-ipojo/Picture 2.png[] image:documentation/subprojects/apache-felix-ipojo/Picture 3.png[]
-
-Then click on _finish_
-
-== 2) Configure the target platform
-
-image:documentation/subprojects/apache-felix-ipojo/Picture 4.png[] image:documentation/subprojects/apache-felix-ipojo/Picture 5.png[]
-
-The resulting project, you looks like the left picture.
-
-== 3) Develop you bundle
-
-The imported project contains a very simple component using annotations.
-But, obviously you can delete/change it.
-For XML-metadata, use `metadata.xml` file is in the project root.
-
-[source,java]
-----
-@Component
-public class MyComponentImpl {
-
- @Validate
- public void start() {
- System.out.println("I'm started !!!");
- }
-
- @Invalidate
- public void stop() {
- System.out.println("I'm leaving :-(...");
- }
-
-}
-----
-
-Once you're done, you are able to run your bundle !
-
-== 4) Run your bundle
-
-image::documentation/subprojects/apache-felix-ipojo/Picture 6.png[]
-
-Right-click on the _.launch_ file and then go on _Run-As \-> MyiPOJOBundle_.
-Equinox will be started and your iPOJO bundle deployed and started: Once run for the first time, you can re-run it from the {\{run}} icon.
-In the console view, you get your Equinox shell, and you see your application result.
-If you don't edit the given development, the output is as:
-
-image::documentation/subprojects/apache-felix-ipojo/Picture 8.png[]
-
-== Iterate :-)
-
-Then, go back to the step 3, change your components, and see the new result...
-That's it !
-
-== Changes in the 1.4.0
-
-[cols=2*]
-|===
-| The 1.4.0+ iPOJO manipulator allows manipulating classes from a directory ([FELIX-943
-| http://cwiki.apache.org/jira/browse/FELIX-943]).
-This feature is very convenient for the Eclipse integration because it avoids creating the Jar and unzipping it inside the Eclipse build directory.
-Moreover, it allows reusing the Java Eclipse builder (compiling classes).
-|===
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-feature-overview.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-feature-overview.adoc
deleted file mode 100644
index c3557df..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-feature-overview.adoc
+++ /dev/null
@@ -1,51 +0,0 @@
-= Apache Felix iPOJO Feature Overview
-
-_This page is an attempt to put all of the features and benefits of iPOJO into a single high-level list so that it is easy to see why you will want to use iPOJO for your applications.
-This list is not exhaustive, but represents the set of features that are potentially most likely to be needed or are unique._
-
-== Core Features
-
-* _POJO-based approach_ - Most components can simply be POJOs and need not have iPOJO- or OSGi-specific API in them.
-* _Simple service provisioning_ - iPOJO manages all aspects of providing an OSGi service.
-* _Service property management_
- ** Can be controlled by configuration properties.
- ** Can be mapped to member fields and automatically updated by the component instance at run time by just changing the member field value.
-* Service life cycle participation
- ** The component instance can participate in the service life cycle by declaring a boolean member field that indicates when the service is actually valid (normally a service is assumed to be valid if the component instance's dependencies are satisfied).
-* _Rich service dependency model_ - Automatically manages a full spectrum of service dependencies.
- ** _Optional/mandatory_ service dependencies.
- ** _Singular/aggregate_ service dependencies.
- ** _Default service implementations_ - The component can provide default implementations of dependent services if no providers are available.
- ** _Member field or method injection_ - Also supported in combination.
- *** Member field injection does not require cluttering component code with bind/unbind methods.
- *** Member method injection supports various method signatures
- **** method() - Acts as a simple event-callback mechanism.
- **** method(<service-interface>svc) - Receives the service object cast to the appropriate interface.
- **** method(ServiceReference ref) - Receives the OSGi ServiceReference for the service object.
- **** method(ServiceReference ref, <service-interface>svc) - Receives the OSGi ServiceReference and the service object cast to the appropriate interface.
- ** _Binding policies_ - Allow components to control how/when their dependencies are bound.
- *** _Static_ - Static dependencies _cannot_ change without invalidating the component instance, so injected services typically do not change at run time and service departures typically result in the component instance being destroyed and potentially recreated.
- *** _Dynamic_ - Dynamic dependencies _can_ change without invalidating the component instance, so injected services can change at run time, but _do not_ change with respect to service priority changes (i.e., they do not automatically switch if a higher priority service appears).
- *** _Dynamic priority_ - Dynamic priority dependencies _can_ change without invalidating the component instance and _do_ dynamically update based on service priority rankings at run time.
-* _Configuration property management_ - Integrated with OSGi Configuration Admin service.
-* _Member field/member method injection_ - Also supported in combination.
- ** _Service property propagation_ - Configuration properties can be configured to update service properties if the component instance is providing a service.
-* _Sophisticated concurrency handling_ - Externalizes concurrency issues so that component code does not need to worry about services changing while they are in use (i.e., no locking protocol in component code).
-* _Deferred instance creation_ - POJO instances are not created until they are actually needed, thus reducing start-up overhead.
-* _Introspection support_ - Supports introspecting a component instance and the state of its dependencies.
- ** Interactive introspection is supported by an arch command for Felix' shell.
-* _Extensible_ - All iPOJO features are implemented via a set of `handlers`, which is an extensibility mechanism open to developers by which they can support custom functionality (e.g., exporting a provided service remotely, etc.).
-
-== Advanced/Experimental Features
-
-* _Composite model_ - iPOJO supports a flexible architectural-like model for composing services.
- ** _Flexible composites_ - A composite is an abstract component implementation.
- ** _Sub-services and sub-components_ - Unlike traditional component composition, an iPOJO composite can be described in terms of services in addition to sub-components;
-thus sub-service implementation selection is deferred until run time.
- ** _Optional/mandatory_ sub-services and/or sub-components.
- ** _Singular/aggregate_ sub-services and/or sub-components.
- ** _Hierarchical_ - A composite component may contain other composite components.
- ** _Composite scoping_ - A composite acts as a scoping mechanism where sub-services/sub-components are not visible externally and external services are not visible internally.
- ** _Service dependencies_ - A composite has the full expressive capabilities of primitive components when it comes to service dependencies (see above description of service dependencies in core features).
- ** For a composite, a service dependency effectively imports an external service into the composite scope from its parent composite (which may be the OSGi service registry in the root case).
- ** _Composite is just a component_ - Composites can be instantiated and automatically managed just like a primitive component.
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/apache-felix-ipojo-dosgi.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/apache-felix-ipojo-dosgi.adoc
deleted file mode 100644
index 4e7451e..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/apache-felix-ipojo-dosgi.adoc
+++ /dev/null
@@ -1,161 +0,0 @@
-= Using Distributed Services with iPOJO
-
-_Distributed Service defines how to deal with remote services in OSGi.
-This page describes the CXF Distributed OSGi with iPOJO demo.This demo uses iPOJO to create a remote OSGi service from an iPOJO component.
-The consumer side also uses iPOJO to create a component that consumes the remote OSGi service.
-By using iPOJO, you don't need to write code to interact with the OSGi Service Registry at all.
-That's all handled through injection, which hugely simplifies the code.
-Moreover thanks to iPOJO's advanced features such as property propagation, the service is exported without any impact on its implementation._
-
-In this demo, you will show how to use iPOJO:
-
-* to expose a service
-* to propagate properties to make the service remotely accessible
-* to use a "remote" service
-
-This demo can be used with any DOSGi distribution, in this document the single-bundle distribution (1.1) is used with iPOJO 1.6.0 and Felix (2.0.5)
-
-
-
-== Demo design
-
-This demo is quite similar to the DS demo of DOSGi demo in structure.
-It consists of 5 bundles:
-
-* An interface bundle defining the Adder Service interface.
-* This bundle is deployed on both sides.
-* An Adder Service implementation bundle.
-(The service will be exported)
-* An Adder Service importer bundle containing the remote-service file explaining to DOSGi how to import and from where to import the Adder service.
-* An Adder Service consumer bundle.
-
-image::documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/design.png[]
-
-The service implementation and consumer bundle are built using iPOJO.
-The Adder Service interface is as follows:
-
-[source,java]
- public interface AdderService {
- int add(int a,int b);
- }
-
-== Sources
-
-The sources and a pre-configured version of Felix are available in the http://people.apache.org/~clement/ipojo/tutorials/dosgi/dosgi-tutorial.zip[dosgi-tutorial archive].
-Once downloaded unzip the archive.
-To compile, run from the root : `mvn clean install`.
-To run the application.
-go to the `felix` directory containing a pre-configured Felix.
-
-== The Adder Service Implementation
-
-The service implementation is a simplistic implementation of the Adder service, which is instantiated as an iPOJO component.
-This implementation uses annotations to define its component type.
-The `@provides` annotation just says that it provides a service.
-Moreover, the `propagation=true` attribute enables property propagation.
-
-In the http://svn.apache.org/repos/asf/felix/sandbox/clement/ipojo-tutorials/dosgi/AdderServiceProvider/src/main/resources/metadata.xml[metadata.xml] file, an instance of the component type is declared.
-Note that this instance declaration defines three properties used by DOSGi to exports the service.
-These properties instruct Distributed OSGi into making the service available on http://localhost:9090/adder.
-Those properties are not declared in the component type itself.
-Indeed, the component type enables property propagation;
-so all defined properties will be published on exported services.
-This propagation also works with the configuration admin.
-This feature is pretty nice, as it does not impact the component implementation and its description.
-[source,xml]
- <instance component="org.apache.felix.ipojo.remote.adder.impl.AdderServiceImpl">
- <property name="osgi.remote.interfaces"value="*"/>
- <property name="osgi.remote.configuration.type"value="pojo"/>
- <property name="osgi.remote.configuration.pojo.address"value="http://localhost:9090/adder"/>
- </instance>
-
-So let's install the server side in Felix.
-Launch Felix from the `felix` directory with:
-
-[source,sh]
- java -jar bin/felix.jar server
-
-Once the shell prompt appears, execute the following command in the shell:
-
-[source,sh]
- start file:../AdderServiceInterface/target/AdderServiceInterface-0.0.1-SNAPSHOT.jar
- start file:../AdderServiceProvider/target/AdderServiceProvider-0.0.1-SNAPSHOT.jar
-
-At this point, the service should be available remotely (wait until the console stops printing stuff), you can check this by obtaining the WSDL: http://localhost:9090/adder?wsdl
-
-image::documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/wsdl.png[,600px]
-
-== The Adder Service Consumer
-
-The service consumer is also created using iPOJO.
-Thanks to DOSGi, iPOJO can inject the service as any regular OSGi service.
-So, the code is pretty simple:
-
-[source,java]
-----
-@Component
-public class AdderConsumer {
-
- @Requires
- private AdderService adder;
-
- public AdderConsumer() {
- System.out.println("Using adder service: 1 + 1 = "+ adder.add(1, 1));
- }
-}
-----
-
-[cols=2*]
-|===
-| This implementation use iPOJO field injection to receive the AdderService.
-Then, it uses it as a regular field.
-This bundle also contains a [metadata.xml
-| http://svn.apache.org/repos/asf/felix/sandbox/clement/ipojo-tutorials/dosgi/AdderServiceConsumer/src/main/resources/metadata.xml] file declaring an instance of this type without any special configuration:
-|===
-[source,xml]
- <instance component="org.apache.felix.ipojo.remote.consumer.AdderConsumer"/>
-
-However, now we have to tell to DOSGi to import our Adder service.
-To achieve that, we create a very simple bundle that just contains the http://svn.apache.org/repos/asf/felix/sandbox/clement/ipojo-tutorials/dosgi/AdderServiceImporter/src/main/resources/OSGI-INF/remote-service/remote-services.xml[remote-services.xml] file.
-This file is analyzed by CXF in order to import the service.
-[source,xml]
- <service-descriptions xmlns="http://www.osgi.org/xmlns/sd/v1.0.0">
- <service-description>
- <provide interface="org.apache.cxf.dosgi.samples.ds.AdderService"/>
- <property name="osgi.remote.interfaces">*</property>
- <property name="osgi.remote.configuration.type">pojo</property>
- <property name="osgi.remote.configuration.pojo.address">http://localhost:9090/adder</property>
- </service-description>
- </service-descriptions>
-
-Now, let's start another instance of Felix:
-
-[source,sh]
- java -jar bin/felix.jar client
-
-Then, execute the following command in the shell:
-
-[source,sh]
-----
-start file:../AdderServiceInterface/target/AdderServiceInterface-0.0.1-SNAPSHOT.jar
-start file:../AdderServiceConsumer/target/AdderServiceConsumer-0.0.1-SNAPSHOT.jar
-start file:../AdderServiceImporter/target/AdderServiceImporter-0.0.1-SNAPSHOT.jar
-
-... log messages may appear, after a little while the following message appears:
-
-Using adder service: 1 + 1 = 2
-----
-
-The remote adder service has now been invoked.
-You will see the following line on the server side window:
-
-[source,sh]
- Adder service invoked: 1 + 1 = 2
-
-That's it !
-
-== Conclusion
-
-This tutorial has illustrated how to easily create remote services and consume them with iPOJO.
-Subscribe to the Felix users mailing list by sending a message to link:mailto:users-subscribe@felix.apache.org[users-subscribe@felix.apache.org];
-after subscribing, email questions or feedback to link:mailto:users@felix.apache.org[users@felix.apache.org].
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/how-to-use-ipojo-annotations.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/how-to-use-ipojo-annotations.adoc
deleted file mode 100644
index 6c3c6aa..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/how-to-use-ipojo-annotations.adoc
+++ /dev/null
@@ -1,377 +0,0 @@
-= How to use iPOJO annotations
-
-_You can use annotations to define your component types.
-This page presents supported annotations._
-
-
-
-== Getting iPOJO Annotations:
-
-iPOJO Annotations are defines inside the `org.apache.felix.ipojo.annotations project`.
-You can download the Jar file of this project from the link:{{ refs.download.path }}[download] page.
-Sources are available on the [Felix trunk|http://felix.apache.org/site/sourcecode.html].
-Once added to your class path / build path / dependencies, you can use the annotations as normal annotations.
-These annotations are automatically processed by the iPOJO manipulator, and do *not* need to be deployed at runtime.
-
-=== With Eclipse (or any other IDE)
-
-Add the org.apache.felix.ipojo.annotations jar file in your build path.
-Do not forget to use a Java compiler accepting annotations (1.5 or higher).
-
-=== With Maven
-
-Add the following dependency:
-[source,xml]
- <dependency>
- <groupId>org.apache.felix</groupId>
- <artifactId>org.apache.felix.ipojo.annotations</artifactId>
- <version>{{ipojo.release}}</version>
- </dependency>
-
-Moreover, you need to set that the source code and the target code are Java 1.5 code.
-To achieve this, just add the following plugin in your plugins section:
-[source,xml]
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-compiler-plugin</artifactId>
- <configuration>
- <source>1.5</source>
- <target>1.5</target>
- </configuration>
- </plugin>
-
-=== With Ant
-
-Just add the org.apache.felix.ipojo.annotations jar file in your class path.
-
-== An example of usage
-
-To illustrate annotations usage, let taking the tutorial example.
-In this tutorial, there are two components:
-
-* The first one provides the hello service
-* The second one uses the provided hello service You can download the archive containing the examples and a preconfigured version of Felix http://people.apache.org/~clement/ipojo/tutorials/annotations/annotation-tutorial.zip[here].
-
-=== Hello Service Provider
-
-The provider uses two annotations.
-The "component" annotation is mandatory and defines that the class defines a component type.
-Then the "provides" annotation just declare that the defined component type provides a service.
-
-[source,java]
-----
-package ipojo.example.hello.impl;
-
-import ipojo.example.hello.Hello;
-
-import org.apache.felix.ipojo.annotations.Component;
-import org.apache.felix.ipojo.annotations.Provides;
-
-/**
- * Component implementing the Hello service.
- **/
-@Component
-@Provides
-public class HelloImpl implements Hello {
- public String sayHello(String name) {
- return "hello " + name;
- }
-}
-----
-
-=== Hello Service Consumer
-
-The Hello Service Consumer use more annotations.
-First it used the component annotation.
-To defines its "immediate" behavior, it add the 'immediate' attribute.
-Then, it uses the requires annotation to define a service dependency.
-Finally, it uses the validate and invalidate annotations to define lifecycle callbacks.
-
-[source,java]
-----
-package ipojo.example.hello.client;
-
-import org.apache.felix.ipojo.annotations.Component;
-import org.apache.felix.ipojo.annotations.Invalidate;
-import org.apache.felix.ipojo.annotations.Requires;
-import org.apache.felix.ipojo.annotations.Validate;
-
-import ipojo.example.hello.Hello;
-
-@Component(name="AnnotatedHelloClient", immediate=true)
-@Instantiate
-public class HelloClient implements Runnable {
-
-@Requires
-private Hello[] m_hello;
-
-private final static int DELAY=10000;
-private boolean end;
-
- public void run() {
- while (!end) {
- try {
- invoke();
- Thread.sleep(DELAY);
- } catch (InterruptedException ie) { }
- }
-}
-
-public void invoke() {
- for (int i = 0; i < m_hello.length; i++) {
- System.out.println(m_hello[i].
- sayHello("iPOJO"));
- }
-}
-
- @Validate
- public void starting() {
- Thread thread = new Thread(this);
- end = false;
- thread.start();
- }
-
- @Invalidate
- public void stopping() {
- end = true;
- }
-}
-----
-
-== Defined Annotations
-
-This section lists defined annotations and how to use them.
-
-=== @Component
-
-_Goal:_ Defines a component type _Target:_ The component implementation class _Attributes:_
-
-* name : defines the component type name (optional, default = the class name)
-* immediate: defines the component type as immediate (optional, default = "false")
-* architecture: enable the architecture exposition (optional, default = "false")
-* propagation: enable configuration property propagation (on provided services) (optional, default = "false")
-* managedservice : set the Managed Service PID.
-(optional, default = no PID (i.e.
-the managed service will not be exposed)).
-* factoryMethod : set the factory-method.
-The specified method must be a static method and return a pojo object.(optional, default = iPOJO uses the 'regular' constructor).
-* publicFactory : set if the component type is public.
-(optional, default = true).
-
-=== @Provides
-
-_Goal:_ Defines that the component type provide services _Target:_ The component implementation class _Attributes:_
-
-* specifications: defines the provided interface (optional, default = all implemented interfaces)
-* strategy : the service object creation strategy.
-Possible values : SINGLETON, SERVICE, METHOD, INSTANCE or the strategy class name.
-With SINGLETON there is only one POJO per component instance, SERVICE means OSGi Service factory, METHOD delegates the creation to the factory-method of the component, INSTANCE creates one service object per requiring instance.
-For other strategies, specify the qualified name of the CreationStrategy class.
-(optional, default = SINGLETON)
-* properties : array containing `@StaticServiceProperties` defining service properties not attached to fields.
-
-*OSGi Service Factory* The SERVICE strategy refers to the OSGi service factory.
-So, one service object per asking bundle will be created.
-
-=== @Requires
-
-_Goal:_ Defines a service dependency _Target:_ Field, Constructor Parameter _Attributes:_
-
-* filter: defines the LDAP filter (optional)
-* optional: defines if the dependency is optional (optional, default = "false")
-* id: defines the dependency Id (useful to identify bind & unbind methods) (optional, default = field name) (if a dependency with the same id is already created (by a @bind or @unbind annotation), it merges the dependencies).
-* nullable: enable or disable the Null Object injection when the dependency is optional and no providers are available (optional, default = "true")
-* defaultimplementation: set the Default-Implmentation (optional, by default iPOJO uses a Null object)
-* exception : the class of the runtime exception to throw when no service providers are available
-* policy: defines the binding policy (optional)
-* comparator: defines the comparator to use to sort service references (optional, default = OSGi Service Reference Comparator)
-* from : defines the specific provider to use
-* specification : the required service specification.
-This attribute is required for Collection field.
-(optional, default = annotated field type).
-* proxy : enables / disables the proxy injection (enabled by default)
-* timeout : the timeout ins millisecond to wait before applying the _no service action_
-
-=== @ServiceProperty
-
-_Goal:_ Defines a service property _Target:_ Field _Attributes:_
-
-* name: property name (optional, default=field name
-* value: property value (optional, default=no value)
-* mandatory : is the property mandatory?
-(optional, default=false)
-
-*Mandatory property* + A mandatory property must receive a value either from the component type description (value attribute), or the instance configuration.
-
-=== @ServiceController
-
-_Goal:_ Control the service exposition _Target:_ Field (Boolean) _Attributes:_
-
-* value : the default value.
-If set to false, it disables the initial exposition
-* specification : set the target of the controller, must be an exposed service interface.
-By default, the controller targets all services.
-
-=== @Property
-
-_Goal:_ Defines a property _Target:_ Field, Method, Constructor Parameter _Attributes:_
-
-* name: property name (optional, default=field name computed by removing "set" from the method name (for instance setFoo(String ff) will get the Foo name), the argument name for constructor injection)
-* value: property value (optional, default=no value)
-* mandatory : is the property mandatory?
-(optional, default=false)
-
-*Field, Method, Constructor* + If another property with the same name is defined, the method or field or constructor argument is added to the existing property.
-
-=== @Updated
-
-_Goal:_ Defines method called when a reconfiguration is completed.
-_Target:_ a method (receiving a dictionary in argument)
-
-=== @Bind
-
-_Goal:_ Defines a bind method _Target:_ Method _Attributes:_
-
-* Id: Dependency Id, if the id is already defines in a "@requires " or "@unbind" annotation, it adds this method as a bind method of the already created dependency.
-(optional, default= no id, compute an id if the method name begin by "bind" (for instance "bindFoo" will have the "Foo" id))
-* Specification : required dependency (optional)
-* Aggregate : is the dependency an aggregate dependency (optional, default= "false")
-* Optional: is the dependency an optional dependency (optional, default= "false")
-* Filter: dependency LDAP filter (optional)
-* Policy: defines the binding policy (optional)
-* Comparator: defines the comparator to use to sort service references (optional, default = OSGi Service Reference Comparator)
-* From : defines the specific provider to use
-
-=== @Unbind
-
-_Goal:_ Defines an unbind method _Target:_ Method _Attributes:_
-
-* Id: Dependency Id, if the id is already defines in a "@requires" or "@bind" annotation, it adds this method as an unbind method of the already created dependency.
-(optional, default= no id, compute an id if the method name begin by "unbind" (for instance "unbindFoo" will have the "Foo" id))
-* Specification : required dependency (optional)
-* Aggregate : is the dependency an aggregate dependency (optional, default= "false")
-* Optional: is the dependency an optional dependency (optional, default= "false")
-* Filter: dependency LDAP filter (optional)
-* Policy: defines the binding policy (optional)
-* Comparator: defines the comparator to use to sort service references (optional, default = OSGi Service Reference Comparator)
-* From : defines the specific provider to use
-
-=== @Modified
-
-_Goal:_ Defines an `modified` method, called when a bound service is udpated.
-_Target:_ Method _Attributes:_
-
-* Id: Dependency Id, if the id is already defines in a "@requires" or "@bind" annotation, it adds this method as an unbind method of the already created dependency.
-(optional, default= no id, compute an id if the method name begin by "unbind" (for instance "unbindFoo" will have the "Foo" id))
-* Specification : required dependency (optional)
-* Aggregate : is the dependency an aggregate dependency (optional, default= "false")
-* Optional: is the dependency an optional dependency (optional, default= "false")
-* Filter: dependency LDAP filter (optional)
-* Policy: defines the binding policy (optional)
-* Comparator: defines the comparator to use to sort service references (optional, default = OSGi Service Reference Comparator)
-* From : defines the specific provider to use
-
-=== @Validate
-
-_Goal:_ defines a validate lifecycle callback _Target:_ method
-
-=== @Invalidate
-
-_Goal:_ defines a validate lifecycle callback _Target:_ method
-
-=== @PostRegistration
-
-_Goal:_ defines a callback invoked after service registration.
-The callback must have the following signature : `public void name(ServiceReference ref)` _Target:_ method
-
-=== @PostUnregistration
-
-_Goal:_ defines a callback invoked after service unregistration.
-The callback must have the following signature : `public void name(ServiceReference ref)` _Target:_ method
-
-=== @Instantiate
-
-_Goal:_ declare a simple instance (this is equivalent to `+<instance component="..."></instance>+` _Target:_ class _Attribute:_
-
-* name: the instance name (optional)
-
-=== Temporal Dependencies (external handler)
-
-The temporal dependency handler is an external handler.
-However, it can be used with an annotation defined in the iPOJO annotations jar file.
-The annotation is `org.apache.felix.ipojo.handler.temporal.Requires` and targets a field.
-_Attributes:_
-
-* filter : specify the dependency filter
-* timeout : specify the dependency timeout (optional)
-* onTimeout : specify the onTimeout action (null, nullable, empty-array, default-implementation (specify the class name in this case) (optional).
-* specification : the required service specification.
-This attribute is required for Collection field.
-(optional, default = annotated field type).
-* proxy : Inject a proxy instead of the real object.
-This allows passing this reference to collaborators.
-(Default = false)
-
-=== Exposing instances as a JMX MBean (external handler)
-
-The JMX Handler allows exposing an instance as a JMX MBean.
-To configure the JMX handler directly from your code, three annotations are provided.
-They are in the `org.apache.felix.ipojo.handlers.jmx` package
-
-The `@org.apache.felix.ipojo.handlers.jmx.Config` (`@Config` if the package it correctly imported) annotation is a type annotation (so placed on the `class` element.
-This annotation indicates that the instance will be exposed as an MBean.
-This annotation supports:
-
-* usesMOSGi: set to `true` to use MOSGi.
-Otherwise, the MBean will be exposed in the MBean Platform Server (default: `false`).
-* objectname: set the MBean objectname.
-The objectname must follow JMX specification.
-(default: `package-name:factory-name:instance-name`)
-* domain: set the MBean domain.
-(default: `package-name`)
-* name: set the MBean name.
-(default: `instance-name`).
-
-The `@org.apache.felix.ipojo.handlers.jmx.Property` (`@Property`) annotation is a field annotation indicating that the field is exposed in the MBean.
-The supported attributes are:
-
-* name: set the property name
-* rights: set the access permission.
-Possible values are `r` (read only) and `w` (read and write).
-By default, properties are in read-only mode.
-* notification: enables notification on this property.
-By default notifications are disabled.
-
-The `@org.apache.felix.ipojo.handlers.jmx.Method` (`@Method`) annotation is a method annotation indicating that the method is exposed in the MBean.
-Only one attribute can be customized:
-
-* description: set the method description.
-
-== Advanced topics and FAQ
-
-=== Metadata file and annotation merge
-
-It is possible to defines component type both in the metadata file (in XML) and by using annotation.
-However, if a component type defined by using annotations has the same name than a type define in the XML file, the XML descriptor override the annotation defined type.
-However, a warning message is launched during the manipulation.
-
-=== Instance creation
-
-The @Instantiate annotation allows creating an instance, but this declaration is limited:
-
-* it does not support configuration
-* it does not allow naming
-* the instance is created in the global scope (so no composition)
-
-To define instances, you should use the XML descriptor.
-Instance can refer to annotated types by referring to their names.
-
- ::xml
- <instance component="ipojo.example.hello.impl.HelloImpl"/>
- <instance component="AnnotedHelloClient"/>
-
-=== Using Custom Annotations
-
-External handlers can provides their own annotations.
-Using these annotations just requires to add them to your build path.
-To external handlers annotations, please refer to the external handler documentation.
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-advanced-tutorial.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-advanced-tutorial.adoc
deleted file mode 100644
index 78c8333..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-advanced-tutorial.adoc
+++ /dev/null
@@ -1,602 +0,0 @@
-= iPOJO Advanced Tutorial: The iPOJO Snack Bar
-
-_This tutorial illustrates some advanced features of iPOJO_
-
-
-
-== Context
-
-This tutorial is based on a very simple application;
-customers are using a vendor service to buy hot dog or pop corn according to the availability of appropriate providers.
-Both of the vendors implement (and provide) the vendor service.
-The hot dog vendor depends on two others services to get the ingredients (buns and wiener).
-To sell pop corn, the pop corn vendor requires having enough corn in stock.
-
-image::documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/vendor.png[]
-
-== Preparing the tutorial
-
-The tutorial archive is available http://people.apache.org/~clement/ipojo/tutorials/advanced/advanced.tutorial.zip[here].
-This archive contains both the source code and a pre-configured version of Felix.
-First, unzip the archive.
-Then, launch `ant` to compile the bundles composing this tutorial.
-Once compiled, you can launch Felix and start the tutorial.
-To launch, Felix launch the following command from the `felix` directory:
-
-[source,sh]
- java -jar bin/felix.jar
-
-== Writing a component providing two services
-
-The sources of this project are inside the _vendor.buns-and-wieners_ directory.
-The hot dog vendor requires at the same time the bun service and the wiener service.
-In our application these services are provided by the same component.
-This component can be implemented as follows (src\org\apache\felix\ipojo\example\vendor\provider\BunWienerProvider.java):
-
-[source,java]
-----
-public class BunWienerProvider implements BunService, WienerService {
-
- public void getBun() {
- System.out.println("Get a bun");
- }
-
- public void getWiener() {
- System.out.println("Get a wiener");
- }
-}
-----
-
-This class just implements the two service interfaces.
-Its descriptor (contained in the metadata.xml file) is:
-
-[source,xml]
-----
-<ipojo>
-<component
- classname="org.apache.felix.ipojo.example.vendor.provider.BunWienerProvider"
- name="buns_and_wieners" public="false">
- <provides/>
-</component>
-
-<instance component="buns_and_wieners"/>
-</ipojo>
-----
-
-In the descriptor, we declare a component type for this vendor which contains the implementation class.
-The `classname` attribute contains the qualified name of the component implementation.
-The "name" attribute is the component type name.
-It is only used to refer to this type.
-
-The `public=false` attribute disables factory exposition.
-A component type publishing a factory provides a way to create instance of this type from outside this descriptor.
-In our case, we want to guarantee that only one instance (singleton) can be created, so we disable the factory mechanism.
-
-iPOJO manages service publication and providing automatically at runtime.
-The `<provides/>` element means that the component provides services.
-If this element is not present, iPOJO will publish all implemented interfaces by the implementation class (and parent class too).
-In our case, it will publish the BunService and WienerService interfaces.
-
-Finally, we create one instance of our component.
-The instance contains the component attribute describing the component type to use.
-We use the component type name to target the wanted component type.
-
-At runtime, the bundle containing this component will create an instance which provides the BunService and the WienerService.
-
-== Publishing service properties
-
-The sources of this project are inside the _vendor.hotdog_ directory.
-The hot dog vendor only provides the Vendor service.
-To provide this service, it uses a bun service and a wiener service.
-The following code (contained in the _src/org/apache/felix/ipojo/example/vendor/hotdog/HotDogVendor.java_ file) shows a very simple implementation of this component:
-
-[source,java]
- public class HotDogVendor implements Vendor {
-
- /**
- * Bun provider (required service).
- */
- private Bun bunProvider;
-
- /**
- * Wiener provider (required service).
- */
- private Wiener wienerProvider;
-
- /**
- * Sell method.
- * To provide an hotdog, the vendor consume a bun and a wiener.
- * This method is synchronized to avoid serving to client
- * at the same time.
- * @return a hotdog.
- * @see org.apache.felix.ipojo.example.vendor.service.Vendor#sell()
- */
- public synchronized Product sell() {
- bunProvider.getBun();
- wienerProvider.getWiener();
- return new HotDog();
- }
-
-Once implemented, we need to describe this component type.
-The descriptor file is the _metadata.xml_ file.
-The field attributes in the "requires" elements are used to inject the required services.
-At runtime, iPOJO injects automatically a BunService provider in the "bunProvider" field and a WienerService provider in the "wienerProvider" field.
-The implementation uses these fields the same way it would have used any other fields (as illustrated in the sell method).
-
-[source,xml]
-----
-<ipojo>
-<component
- classname="org.apache.felix.ipojo.example.vendor.hotdog.HotDogVendor"
- name="HD" public="false">
- <provides/>
- <requires field="bunProvider"/>
- <requires field="wienerProvider"/>
-</component>
-
-<instance component="HD"/>
-</ipojo>
-----
-
-The component type declares a provided service (the Vendor Service).
-Then, the component declares the two service dependencies (using the "requires" element).
-However, we would like to add a service property on the Vendor service describing the sold product (here, "hotdog").
-To achieve this, we just need to add a property element in the "provides" tags:
-
-[source,xml]
-----
-<ipojo>
-<component
- classname="org.apache.felix.ipojo.example.vendor.hotdog.HotDogVendor"
- name="HD" public="false">
- <provides>
- <property name="product" type="string" value="hotdog"/>
- </provides>
- <requires field="bunProvider"/>
- <requires field="wienerProvider"/>
-</component>
-
-<instance component="HD"/>
-</ipojo>
-----
-
-iPOJO then publishes the "product" property in the "vendor" service registration.
-This property has the "hotdog" value.
-
-== Publishing 'dynamic' properties
-
-The bun service and the wiener service can also expose service properties.
-In our case, these service properties will describe the stock of ingredients.
-Each time the service is used, the property value is decreased.
-To achieve this, we modify the current implementation to add a field representing the property:
-
-[source,java]
-----
-public class BunWienerProvider implements BunService, WienerService {
-
- private int bunStock;
-
- private int wienerStock;
-
- public synchronized void getBun() {
- bunStock = bunStock - 1;
- }
-
- public synchronized void getWiener() {
- wienerStock = wienerStock - 1;
- }
-}
-----
-
-The stock accesses are synchronized to avoid multiple accesses at the same time.
-The component type metadata must also be modified in order to describe this property:
-
-[source,xml]
-----
-<ipojo>
-<component
- classname="org.apache.felix.ipojo.example.vendor.provider.BunProvider"
- name="buns_and_wieners" public="false">
- <provides>
- <property name="buns" field="bunStock" value="10"/>
- <property name="wieners" field="wienerStock" value="10"/>
- </provides>
-</component>
-
-<instance component="buns_and_wieners"/>
-</ipojo>
-----
-
-In the `provides` element, two properties are added.
-This property contains a `field` attribute aiming to attach the service property with a field of the implementation class.
-Then a default value is given.
-In the code, the property fields will obtain the initial value (10).
-Then each time the fields are modified, the service property is updated (as well as the OSGi™ service registration).
-Notice that iPOJO support method injection for property too.
-In this case, a getter method is called to inject the property value.
-
-== Configuring instances
-
-In the previous example, the properties were configured in the component type description.
-It is also possible to customize any property value in the instance declaration.
-This way, each instance can obtain different values.
-
-[source,xml]
-----
-<ipojo>
-<component
- classname="org.apache.felix.ipojo.example.vendor.provider.BunProvider"
- name="buns_and_wieners" public="false">
- <provides>
- <property name="buns" field="bunStock" value="10"/>
- <property name="wieners" field="wienerStock" value="10"/>
- </provides>
-</component>
-
-<instance component="buns_and_wieners">
- <property name="buns" value="9"/>
- <property name="wieners" value="8"/>
-</instance>
-</ipojo>
-----
-
-The previous metadata shows how to push a configuration in instance declarations.
-The instance declaration contains two property elements containing the name of the value of the property.
-Instance configuration override component type initial value.
-Properties are optional by default ; that's means that they do not need to receive a value.
-In this case, default values are the same as the Java default fields values (boolean : false, int : 0, double : 0.0d, ...).
-You can specify that a property must receive a default value from either the component type description or the instance configuration by setting the `mandatory` attribute to `true`.
-
-== Using filter in service requirements
-
-Now that bun and wiener providers publish their remaining stock, the hot dog provider can look for a bun service and a wiener service with a non empty stock.
-To achieve this, we must describe an LDAP filter in the service requirement description.
-The following XML snipped shows this metadata:
-
-[source,xml]
-----
-<ipojo>
-<component
- classname="org.apache.felix.ipojo.example.vendor.hotdog.HotDogVendor"
- name="HD" public="false">
- <provides>
- <property name="product" type="string" value="hotdog"/>
- </provides>
- <requires field="bunProvider" filter="(buns>=1)"/>
- <requires field="wienerProvider" filter="(wieners>=1)"/>
-</component>
-
-<instance component="HD"/>
-</ipojo>
-----
-
-When a provider does no more matches with the LDAP filter, the provider is no more used, and another (matching with the filter) is tracked.
-If no provider fulfilling the constraint is found, the instance becomes invalid and waits a matching provider.
-
-*Instance invalidation and services* + When an instance becomes invalid, all its provided services are withdrawn from the service registry.
-So, this instance is no more *accessible* from the service registry.
-
-== Immediate component instance
-
-Now that we get the hot dog provider, we are going to implement customers.
-Customers are implemented in the _vendor.customer_ project).
-A customer simply looks for a vendor service and buys a product:
-
-[source,java]
- public class Customer {
-
- private VendorService vendor;
-
- private String name;
-
- public Customer() {
- System.out.println("Customer " + name + " bought "
- + vendor.sell() + " from " + vendor.getName());
- }
-
-The previous code shows a possible implementation of a customer.
-However, the "sell" method is called in a constructor, and the constructor can only be called only if an object of the class is created.
-With iPOJO there are two different way to "activate" an instance as soon as it becomes valid.
-
-The first one uses the lifecycle callback (described in the previous tutorial).
-The second one is by declaring the component as an immediate component.
-An immediate component instance creates an object of its implementation as soon as it becomes valid.
-[source,xml]
- <ipojo>
- <component
- classname="org.apache.felix.ipojo.example.vendor.customer.Customer"
- name="customer" immediate="true">
- <requires field="vendor"/>
- <properties>
- <property field="name"/>
- </properties>
- </component>
- </ipojo>
-
-To declare a component immediate, just add `immediate=true` in the component descriptor.
-Then as soon as the vendor service is available, the object is created.
-Moreover, this type declares a property (to give a name to the customers).
-This property is not a service property, but just an internal property.
-As for service properties, the name field will be injected by a value necessary given during the instance creation (i.e.
-contained inside the instance configuration).
-
-By default, all all components that do not provide any service are immediate.
-Other components create call their constructors when they are used for the first time.
-
-*Difference between 'validate' and 'immediate'* + There is a difference between immediate components and components with a `validate` lifecycle callback.
-Indeed, the callback is call at each time the instance becomes valid and calls the constructor only if no object already exists.
-On the other side, the immediate component's constructor is call only once.
-
-== Creating instances from an external component type
-
-In the previous section we have declared a customer component type, which does not have the `public=false` attribute.
-This feature allows separate deployment from instance creation.
-Moreover, we didn't declare instances in the descriptor.
-
-Another metadata file can be used to declare instances from the customer type, this descriptor being contained in another bundle.
-The following descriptor creates 10 customer instances (look at the _vendor.customer.creator\metadata.xml_ file):
-[source,xml]
- <ipojo>
- <instance component="customer">
- <property name="name" value="customer-1"/>
- </instance>
- <instance component="customer">
- <property name="name" value="customer-2"/>
- </instance>
- <instance component="customer">
- <property name="name" value="customer-3"/>
- </instance>
- <instance component="customer">
- <property name="name" value="customer-4"/>
- </instance>
- <instance component="customer">
- <property name="name" value="customer-5"/>
- </instance>
- <instance component="customer">
- <property name="name" value="customer-6"/>
- </instance>
- <instance component="customer">
- <property name="name" value="customer-7"/>
- </instance>
- <instance component="customer">
- <property name="name" value="customer-8"/>
- </instance>
- <instance component="customer">
- <property name="name" value="customer-9"/>
- </instance>
- <instance component="customer">
- <property name="name" value="customer-10"/>
- </instance>
- </ipojo>
-
-Once deployed, this bundle looks for the required factory.
-If it's not available the bundle waits for the factory.
-As soon as the required factory is available, all instances are created.
-When this bundle is stopped, all instances are destroyed.
-
-== Deploying the application
-
-Compile the bundles, by launching ant at the root of the tutorial.
-Then launch Felix is indicated above.
-Once started, launch the following commands
-
-[source,sh]
- start file:../vendor.services/output/vendor.services.jar
- start file:../vendor.buns-and-wieners/output/vendor.buns-and-wieners.jar
- start file:../vendor.hotdog/output/vendor.hotdog.jar
- start file:../vendor.customer/output/vendor.customer.jar
- start file:../vendor.customer.creator/output/vendor.customer.creator.jar
-
-Something like this should appear:
-
-[source,sh]
- Customer customer-1 bought Hotdog from Fenway Park
- Customer customer-2 bought Hotdog from Fenway Park
- Customer customer-3 bought Hotdog from Fenway Park
- Customer customer-4 bought Hotdog from Fenway Park
- Customer customer-5 bought Hotdog from Fenway Park
- Customer customer-6 bought Hotdog from Fenway Park
- Customer customer-7 bought Hotdog from Fenway Park
- Customer customer-8 bought Hotdog from Fenway Park
-
-Only 8 customers can buy a hot-dog, as the stock of wieners and buns can't supply more hot-dog.
-The remainder of this tutorial will try to solve the problem of these two hungry customers.
-
-== Using the lifecycle controller
-
-Sometimes you want to invalidate your instance in the code (for example: to unregister a service).
-That's possible with the lifecycle controller handler.
-Let's take the popcorn vendor with a corn stock from the _vendor.popcorn_ project.
-Each time it sells some popcorn, its stock is decreased.
-When the stock reaches 0, it cannot sell popcorns any more (so the vendor service needs to be withdrawn).
-
-The following implementation (_src\org\apache\felix\ipojo\example\vendor\popcorn\PopCornVendor.java_) uses a field to control the lifecycle.
-
-[source,java]
-----
-/**
- * The corn stock.
- */
-private int m_corn_stock;
-
-/**
- * Lifecycle controller.
- * If set to false, the instance becomes invalid.
- */
-private boolean m_can_sell = true;
-
-/**
- * The sell method.
- * To provide popcorn, the vendor needs to decrease its corn stock level.
- * This method is synchronized to avoid to client being serve at
- * the same time.
- * @return
- * @see org.apache.felix.ipojo.example.vendor.service.Vendor#sell()
- */
-public synchronized Product sell() {
- m_corn_stock--;
- if (m_corn_stock == 0 && m_can_sell) { // Last pop corn
- m_can_sell = false;
- System.out.println("Stop selling popcorn
- ... Run out of stock");
- return new PopCorn();
- } else if (m_corn_stock > 0) { // Normal case
- return new PopCorn();
- } else { // Cannot serve.
- return PopCorn.NO_MORE_POPCORN;
- }
-}
-----
-
-Once the field is set to "false", the instance is invalidated (the vendor service is no more available).
-To configure the controller, you can use the following metadata:
-
-[source,xml]
-----
-<ipojo>
-<component
- classname="org.apache.felix.ipojo.example.vendor.popcorn.PopCornVendor"
- name="popcorn" public="false" architecture="true">
- <provides/>
- <controller field="m_can_sell"/>
-</component>
-
-<instance component="popcorn"/>
-</ipojo>
-----
-
-The instance can be re-validated by setting the field to true.
-So, no deploy the pop corn vendor.
-
-[source,sh]
- -> start file:../vendor.popcorn/output/vendor.popcorn.jar
- Customer customer-10 bought popcorn from D & P
- Customer customer-9 bought popcorn from D & P
-
-Our two last customers are no more hungry.
-However, new customers arrives, we have the following situation:
-
-[source,sh]
- -> update 10
- Customer customer-1 bought popcorn from D & P
- Customer customer-2 bought popcorn from D & P
- Stop selling popcorn ... Run out of stock
- Customer customer-3 bought popcorn from D & P
-
-To recreate new customers, just update the customer.creator bundle (bundle 10).
-So, now we have 7 customers hungry!
-There is neither popcorn nor hotdog!
-
-== Reconfiguring an instance
-
-OSGi specified the Configuration Admin mechanism aiming to handler service and bundle configuration.
-This section will describe how you can use the Configuration Admin and iPOJO to add corn inside our popcorn vendor.
-First, we will change the pop corn vendor to add a method reinjecting the new stock:
-
-[source,java]
- /**
- * A transporter refills the stock of corn.
- * This method is synchronized to avoid to client being served
- * during the update.
- * @param newStock : the stock of corn to add to the current stock.
- */
- public synchronized void refillStock(int newStock) {
- m_corn_stock += newStock;
- System.out.println("Refill the stock : " + m_corn_stock);
- if (m_corn_stock > 0) {
- m_can_sell = true;
- }
- }
-
-Once added, we need to update the component type descriptor to use this method:
-
-[source,xml]
-----
-<ipojo>
-<component
- classname="org.apache.felix.ipojo.example.vendor.popcorn.PopCornVendor"
- name="popcorn" architecture="true">
- <provides/>
- <controller field="m_can_sell"/>
- <properties>
- <property name="stock" method="refillStock" value="5"/>
- </properties>
-</component>
-
-<instance component="popcorn" name="SuperPopCorn">
- <property name="managed.service.pid" value="Super.PopCorn.Stock"/>
-</instance>
-</ipojo>
-----
-
-We add two different things.
-First we add a "stock" property attached to the _refillStock_ method.
-When this instance is configured or reconfigured, this method is called to push the new stock value.
-Then we add the _managed.service.pid_ property inside the instance creation.
-This property will be used by the Configuration Admin to attach configuration to instances.
-The property value must be unique.
-So now, our popcorn vendor can be reconfigured dynamically to get increments its corn stock.
-However, we need to create something refilling the stock ...
-a corn transporter !
-
-Inside the _vendor.corn.transporter_ project, we have a component dealing with the ConfigurationAdmin to push the new pop corn vendor configuration.
-The implementation is contained in the _src\org\apache\felix\ipojo\example\vendor\corn\transporter\CornTransporter.java_ file.
-
-[source,java]
- public class CornTransporter {
-
- private ConfigurationAdmin m_configAdmin;
-
-
- /**
- * Reconfigure the popcorn vendor with the configuration admin.
- */
- public void refillStock() {
- try {
- // Retrieve or Create the instance configuration
- // from the configuration admin
- Configuration configuration =
- m_configAdmin.getConfiguration("Super.PopCorn.Stock",
- "file:../vendor.popcorn/output/vendor.popcorn.jar");
- configuration.setBundleLocation(
- "file:../vendor.popcorn/output/vendor.popcorn.jar");
- Properties props = new Properties();
- props.put("stock", new Integer(15)); // Delivered corn
- configuration.update(props);
- System.out.println("Update the configuration of "
- + configuration.getPid() + "("
- + configuration.getBundleLocation() + ")");
- configuration.delete();
- } catch (IOException e) {
- e.printStackTrace();
- }
- }
- }
-
-Create a new configuration from the configuration admin and configure this configuration to add corn.
-Then, we update this configuration.
-This will reconfigured our popcorn vendor.
-More information on the Configuration Admin is available in the OSGi R4 Compendium.
-
-So, now if we deploy this bundle, we will provide enough corn to feed all the customers:
-
-[source,sh]
- -> start file:../vendor.corn.transporter/output/vendor.corn.transporter.jar
- Update configuration of Super.PopCorn.Stock(
- file:../vendor.popcorn/output/vendor.popcorn.jar)
- Refill the stock : 5
- Customer customer-10 bought popcorn from D & P
- Customer customer-9 bought popcorn from D & P
- Customer customer-8 bought popcorn from D & P
- Customer customer-7 bought popcorn from D & P
- Customer customer-6 bought popcorn from D & P
- Customer customer-5 bought popcorn from D & P
- Customer customer-4 bought popcorn from D & P
-
-That's it!
-
-== Conclusion
-
-This small tutorial has presented some of of the iPOJO features.
-Subscribe to the Felix users mailing list by sending a message to link:mailto:users-subscribe@felix.apache.org[users-subscribe@felix.apache.org];
-after subscribing, email questions or feedback to link:mailto:users@felix.apache.org[users@felix.apache.org].
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-composition-tutorial.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-composition-tutorial.adoc
deleted file mode 100644
index e2f00f6..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-composition-tutorial.adoc
+++ /dev/null
@@ -1,620 +0,0 @@
-= iPOJO Composition Tutorial
-
-_This page describes how works the composition mechanisms provided by iPOJO and how to use it.
-this feature allows you to design applications that will natively support the dynamism and the evolution._
-
-
-
-== Why providing a composition layer?
-
-iPOJO aims to simplify the creation of OSGi (dynamic) applications.
-Creating such as applications is basically a two steps process:
-
-* Developing services and components
-* Assembling them together to create the application
-
-To tackle the first step, iPOJO provides an easy-to-use development model.
-But, this does not help to design the application.
-To conduct the second step, iPOJO provides a composition language allowing to:
-
-* Assemble components and services together
-* Assert service isolation inside a composition
-* Hide/Abstract implementations
-
-=== What about privacy?
-
-Service or component composition has a stringent requirement.
-How to isolate components and services of an application to avoid side effects as an unexpected access to a used service ...iPOJO composites just provide an isolation mechanism.
-Services provided inside a composite ARE NOT published globally (inside the OSGi service registry).
-So, only the component instances living in the same composite can access to those services.
-However, it is also possible to import a service from the parent/global service registry, as well as to export a service to the parent (i.e.
-superior) composite.
-
-== The different types of composition in the OSGi world
-
-Basically there is two types of composition in OSGi:
-
-* The intra-bundle composition
-* The service-based composition
-
-=== Intra-bundle composition
-
-The intra-bundle composition is the policy followed by Spring-DM.
-Each bundle contains components.
-These components can require and provide services from the global (OSGi) registry.
-Moreover, these components can collaborate together inside the bundle without providing/requiring services.
-So the isolation scope of intra-bundle composition is the _bundle_.
-This type of composition allows providing coarse-grain services provided by the collaboration of several components.
-However, it is not possible to update one of those components, as the update unity is the bundle.
-
-=== Service-based composition
-
-There are two types of service composition.
-The behavioral service composition is like http://www.ibm.com/developerworks/library/specification/ws-bpel/[BPEL] for the web services.
-An orchestrator supervises the execution and the collaboration of services like:
-
-. Call service A
-. Call service B
-. ...
-
-The second type of service composition is the structural service composition.
-This aims to provide a kind of Architecture Description Language for service-based applications.
-iPOJO follows this trend.
-This way as several advantages:
-
-* Avoids coupling a composition to specific implementation, and so it supports the dynamic substitution
-* Allows the evolution of used services and components at runtime
-
-This is also the way followed by http://www.ibm.com/developerworks/library/specification/ws-sca/[SCA].
-However, SCA does not specify how the dynamism should be handled.
-
-== The iPOJO composition theory for the dummies
-
-The distinction between component types and instances When you declare a `<component>` (or a `<composite>`) in your metadata, you're declaring a component type.
-Then you declare instances from these component types.
-This mechanism is critic for the iPOJO composition.
-Indeed, inside a composite, you're able to create instances from any (public) component types (Refer to the xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/how-to-use-ipojo-factories.adoc[Factory] web page for further details).
-On the top of this mechanism, we can define the concept of service implementation.
-A service implementation is just a component type where the instances provide a service.
-For example, if the instance from a component type provides the service S, the component type is a service implementation of S, and so can be used to create a provider of S.
-
-== The service context concept
-
-The service context is the concept allowing service isolation.
-OSGi bundle context allows accessing both to bundle-based functionality (like `loadClass`) and to the service registry.
-However, OSGi defines only one service registry, accessible by any bundles.
-iPOJO splits these two interaction types.
-Instances receive an iPOJO Bundle Context delegating bundle-related methods to the "regular" bundle context, and service-related methods to a service context.
-This service context can access to the OSGi service registry or to a new one.
-Each composition instances have a service registry.
-Instances creates inside the composition used this service registry through received the iPOJO Bundle Context.
-
-== Downloads
-
-Download the http://people.apache.org/~clement/ipojo/tutorials/composite/composite-tutorial.zip[archive].
-This archive contains:
-
-* The different applications and component types implemented in this tutorial
-* A preconfigured version of Felix
-* Deployment scripts
-
-Launch `ant` from the base directory of the unzipped archive to create every bundles.
-Then, you can test the different examples by copying and pasting commands from the `script.txt` file (in the felix folder) in the Felix shell.
-
-== Let's start with a first composition
-
-In the xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-in-10-minutes.adoc[iPOJO in 10 minutes] tutorial, we created an application checking a sentence against dictionaries.
-We'll reuse this simple application in this tutorial.
-So first, we need to implements several component types:
-
-* The dictionary service implementation, containing words
-* The Check service implementation, providing methods to check words against dictionaries
-* And the client GUI, using a Check Service to indicate misspelled words.
-
-We will reuse the same implementation than in the previous tutorial.
-The current application is designed as follow:
-
-image::documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/app1.png[]
-
-However, imagine that you want to isolate services provided and required by your application.
-For example, you want to isolate a stateful service or a critical (private) resource.
-
-So, let's imagine a second version of our spellchecker application.
-In this application, the dictionary service, and the checker service are isolated inside a composite.
-So, those services will be accessible only from instances living in the composite.
-The GUI will also be instantiated inside the composite.
-The composition will be something like:
-
-image::documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/app2.png[]
-
-The descriptor of this application is:
-
-[source,xml]
-----
-<ipojo>
-
-<!-- Declares a composition -->
-<composite name="composition1">
- <!-- Instantiates an instance of the English dictionary -->
- <instance component="spell.english.EnglishDictionary"/>
-
- <!-- Instantiates an instance of the Checker -->
- <instance component="spell.checker.SpellCheck"/>
-
- <!-- Instantiates an instance of the GUI -->
- <instance component="spell.gui.SpellCheckerGui"/>
-</composite>
-
-<!-- Instantiates an instance of our composition -->
-<instance component="composition1"/>
-
-</ipojo>
-----
-
-First, a composite type is declared inside an iPOJO descriptor.
-A composite contain always a `name` attribute, which is the component type name.
-Inside the `<composite></composite>`, three instances are declared: the three instances used by our application.
-Remark that these instances are declared as 'regular' instances.
-The `component` attribute indicates the component type to use.
-Instances can be configured as regular iPOJO instances.
-Finally, an instance of our type is also declared.
-
-To execute our composition, go in the felix directory and launch the following command:
-
-[source,sh]
- java -jar bin/felix.jar
-
-This version of Felix starts with the iPOJO framework, the iPOJO Arch command and the composite support.
-So, we just need to install our component types and the composition.
-
-In the Felix prompt, launch the following commands:
-
-[source,sh]
- start file:../spell.services/output/spell.services.jar
- start file:../spell.english/output/spell.english.jar
- start file:../spell.checker/output/spell.checker.jar
- start file:../spell.checker.gui/output/spell.checker.gui.jar
-
-Those commands deploy the component types.
-Remark that no 'functional' (i.e.
-neither Check service, nor Dictionary service) services are provided.
-Deployed bundles provide only iPOJO Factory services:
-
-[source,sh]
- -> inspect s c
- System Bundle (0) provides:
- ---------------------------
- org.osgi.service.startlevel.StartLevel
- org.osgi.service.packageadmin.PackageAdmin
- Apache Felix Shell Service (1) provides:
- ----------------------------------------
- ...
- Apache Felix Bundle Repository (3) provides:
- --------------------------------------------
- org.osgi.service.obr.RepositoryAdmin
- iPOJO (4) provides:
- -------------------
- ...
- iPOJO Composite (6) provides:
- -----------------------------
- ...
- spell.english (8) provides:
- ---------------------------
- org.apache.felix.ipojo.Factory, org.osgi.service.cm.ManagedServiceFactory
- spell.checker (9) provides:
- ---------------------------
- org.apache.felix.ipojo.Factory, org.osgi.service.cm.ManagedServiceFactory
- spell.checker.gui (10) provides:
- -------------------------------
- org.apache.felix.ipojo.Factory, org.osgi.service.cm.ManagedServiceFactory
-
-Now, when can deploy our composition:
-
-[source,sh]
- start file:../example1/output/composition1.jar
-
-Once deployed and started, the fancy GUI appears:
-
-image::documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ss-comp.png[]
-
-Now, you can check that the functional services are not unavailable outside the composite:
-
-[source,sh]
- -> inspect s c
- System Bundle (0) provides:
- ---------------------------
- org.osgi.service.startlevel.StartLevel
- org.osgi.service.packageadmin.PackageAdmin
- Apache Felix Shell Service (1) provides:
- ----------------------------------------
- ...
- Apache Felix Bundle Repository (3) provides:
- --------------------------------------------
- org.osgi.service.obr.RepositoryAdmin
- iPOJO (4) provides:
- -------------------
- ...
- iPOJO Composite (6) provides:
- -----------------------------
- ...
- spell.english (8) provides:
- ---------------------------
- org.apache.felix.ipojo.Factory, org.osgi.service.cm.ManagedServiceFactory
- spell.checker (9) provides:
- ---------------------------
- org.apache.felix.ipojo.Factory, org.osgi.service.cm.ManagedServiceFactory
- spell.checker.gui (10) provides:
- -------------------------------
- org.apache.felix.ipojo.Factory, org.osgi.service.cm.ManagedServiceFactory
- Bundle 11 provides:
- -------------------
- org.apache.felix.ipojo.Factory, org.osgi.service.cm.ManagedServiceFactory
-
-Of course, if you stop a bundle providing a required service type, the application is stopped:
-
-[source,sh]
- -> stop 8
- -> start 8
-
-Then, the application also supports component type update.
-However the component type name must not change.
-We will see later how we can avoid this issue by abstracting implementations.
-
-== Importing a service inside a composite
-
-Let's imagine a second version of the checker service implementation (spell.checker-v2).
-This implementation removes the trace when wrong words are detected.
-Indeed, this implementation uses a log service to store such kind of errors.
-
-If we use this implementation, we need to make a log service available inside the composite.
-Else, the checker will not be valid.
-To achieve this, use the following composite:
-
-[source,xml]
-----
-<ipojo>
-
-<!-- Declares a composition -->
-<composite name="composition2">
- <!-- Instantiates an instance of the English dictionary -->
- <instance component="spell.english.EnglishDictionary"/>
-
- <!-- Instantiates an instance of the Checker -->
- <instance component="spell.checker.SpellCheck"/>
-
- <!-- Instantiates an instance of the GUI -->
- <instance component="spell.gui.SpellCheckerGui"/>
-
- <!-- Imports the log service -->
- <subservice action="import"
- specification="org.osgi.service.log.LogService"/>
-</composite>
-
-<!-- Instantiates an instance of our composition -->
-<instance component="composition2"/>
-
-</ipojo>
-----
-
-This composite just adds a `subservice` nested element.
-This subservice allows importing a service inside the composite.
-The `action` attribute specifies that we want to import the service from the parent scope (i.e.
-superior).
-The `specification` attribute indicates the required service.
-
-image::documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/app3.png[]
-
-Now, relaunch Felix and enter another profile name (`composition2` for example).
-Once started, executes the following commands:
-
-[source,sh]
- start file:../spell.services/output/spell.services.jar
- start file:../spell.english/output/spell.english.jar
- start file:../spell.checker-v2/output/spell.checker-v2.jar
- start file:../spell.checker.gui/output/spell.checker.gui.jar
- start file:../example2/output/composition2.jar
-
-Those commands deploy required component type (note that we deploy spell.checker-v2) and an implementation of the OSGi Log Service.
-When you execute the last command, the fancy interface re-appears.
-
-Try to enter a wrong word (as `composite`), and click on the check button.
-The trace does no more appear...
-the message is logged inside the log service.
-Of course, such composite support dynamism.
-Try the following scenario
-
-[source,sh]
- stop 9
- start 9
- stop 10
- start 10
-
-When the log service is stopped, the GUI disappears.
-In fact, the service can no more be imported, and so, the composition becomes invalid.
-When you stop a bundle containing a used component type, the same behavior occurs.
-
-Like in the previous example, you can check that only the log service is globally available.
-Other services are isolated inside the composite.
-In this case the parent scope is the OSGi service registry, but composite can also contain other composite.
-In such context, the import tracks services from the superior composite.
-An example of hierarchical composition is described later in this tutorial.
-
-*Service Resolution*
-
-== Abstracting implementation... Composing services
-
-We saw in the first composition that we depend on specific component types.
-This can be avoided by specifying the composition in term of services instead of component types.
-So, every available service implementation can be used.
-Moreover, if the used one disappears, another one can be immediately used to replace the missing service.
-Let's illustrate this.
-
-In the first composition, we create an instance of the English dictionary service implementation.
-We can remove this coupling to this specific implementation.
-To do this, we will target any implementation of the dictionary service regardless the language.
-
-[source,xml]
-----
-<ipojo>
-
-<!-- Declares a composition -->
-<composite name="composition3">
- <!-- Instantiates an instance of the English dictionary -->
- <subservice action="instantiate"
- specification="spell.services.DictionaryService"/>
-
- <!-- Instantiates an instance of the Checker -->
- <instance component="spell.checker.SpellCheck"/>
-
- <!-- Instantiates an instance of the GUI -->
- <instance component="spell.gui.SpellCheckerGui"/>
-</composite>
-
-<!-- Instantiates an instance of our composition -->
-<instance component="composition3"/>
-
-</ipojo>
-----
-
-The previous composition instantiates a dictionary service.
-This means that the composite looks for an implementation of the Dictionary service and creates an instance of this implementation (i.e.
-component type) inside the composition.
-If several implementations are available, the composite chooses one, and switches to another one if the used implementation becomes unavailable.
-
-image::documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/app4.png[]
-
-To execute this composition, launch Felix and execute the following command:
-
-[source,sh]
- start file:../spell.services/output/spell.services.jar
- start file:../spell.english/output/spell.english.jar
- start file:../spell.checker/output/spell.checker.jar
- start file:../spell.checker.gui/output/spell.checker.gui.jar
- start file:../example3/output/composition3.jar
-
-These commands deploy component types and the composition.
-Only one implementation of the dictionary service is available (English).
-You can check this by executing the `service 8` command.
-
-[source,sh]
- -> inspect s c 9
- spell.english (9) provides:
- ---------------------------
- component.class = spell.english.EnglishDictionary
- component.description = <unknown value type>
- component.properties = <unknown value type>
- component.providedServiceSpecifications = spell.services.DictionaryService
- factory.name = spell.english.EnglishDictionary
- factory.state = 1
- objectClass = org.apache.felix.ipojo.Factory,
- org.osgi.service.cm.ManagedServiceFactory
- service.id = 39
- service.pid = spell.english.EnglishDictionary
-
-Note the `component.providedServiceSpecifications` property indicating provided services.
-Now deploy another implementation of the dictionary service, such as the French dictionary service ☺
-
-[source,sh]
- start file:../spell.french/output/spell.french.jar
-
-Write `welcome` in the GUI and then check.
-The word is correctly spelled.
-Then, stop the bundle providing the English dictionary.
-
-[source,sh]
- stop 9
-
-Write `welcome` in the GUI, and check.
-The word is misspelled!
-Try to write `bienvenue` and check.
-The word is correctly spelled.
-This means that the composite has substitutes the previous English dictionary by the French one.
-This one will be use until it disappears.
-If you stop the bundle containing this implementation, the composite becomes invalid.
-
-== Publishing services
-
-A composition can also provide services.
-iPOJO composites support two methods to provide services :
-
-* The service export: re-export a service from the composite to the parent context
-* The service implementation: the composite computes a delegation scheme to delegate every method of the provided service on internal entities (services and instances)
-
-This section addresses the export.
-Exporting a service is the opposite of the service import.
-It tracks services from the composites to publish it in the parent (superior) context.
-So, let's imagine a fourth version of our application.
-In this application, the GUI is externalized and lives in the global context (i.e.
-OSGi).
-So, the composition exports the spell checker service.
-
-[source,xml]
-----
-<ipojo>
-
-<!-- Declares a composition -->
-<composite name="composition4">
- <!-- Instantiates an instance of the English dictionary -->
- <subservice action="instantiate"
- specification="spell.services.DictionaryService"/>
-
- <!-- Instantiates an instance of the Checker -->
- <instance component="spell.checker.SpellCheck"/>
-
- <!-- Export the SpellChecker service -->
- <provides action="export"
- specification="spell.services.SpellChecker"/>
-</composite>
-
-<!-- Instantiates an instance of our composition -->
-<instance component="composition4"/>
-
-<!-- Instantiates an instance of the GUI in the global context -->
-<instance component="spell.gui.SpellCheckerGui"/>
-
-</ipojo>
-----
-
-In the previous composition, the composite exports the spell checker service.
-Moreover, the GUI is also created but in the global context.
-At runtime, the result will be as following:
-
-image::documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/app5.png[]
-
-The composite published the spell checker service in the OSGi service registry.
-The GUI tracks this service in the OSGi service registry too.
-To execute this composition, launch Felix and execute following the commands:
-
-[source,sh]
- start file:../spell.services/output/spell.services.jar
- start file:../spell.english/output/spell.english.jar
- start file:../spell.checker/output/spell.checker.jar
- start file:../spell.checker.gui/output/spell.checker.gui.jar
- start file:../example4/output/composition4.jar
-
-You can check that the composition exports the service with the following command:
-
-[source,sh]
- -> services 12
- Bundle 12 provides:
- -------------------
- component.description = <unknown value type>
- component.properties = <unknown value type>
- component.providedServiceSpecifications = spell.services.SpellChecker
- factory.name = composition4
- factory.state = 1
- objectClass = org.apache.felix.ipojo.Factory,
- org.osgi.service.cm.ManagedServiceFactory
- service.id = 36
- service.pid = composition4
- ----
- factory.name = composition4
- instance.name = composition4-0
- objectClass = spell.services.SpellChecker
- service.id = 37
-
-So, now you can play with dynamism.
-Stop the bundle containing the Check service implementation.
-The GUI disappears.
-Restart it.
-The GUI reappears.
-Now, stop the bundle containing the GUI implementation.
-The checker service stills available.
-Indeed, the GUI is no more inside the composition, and so stills valid despite the unavailability of the GUI:
-
-[source,sh]
- -> stop 9
- -> start 9
- -> stop 11
- -> inspect s c 12
- Bundle 12 provides:
- -------------------
- component.description = <unknown value type>
- component.properties = <unknown value type>
- component.providedServiceSpecifications = spell.services.SpellChecker
- factory.name = composition4
- factory.state = 1
- objectClass = org.apache.felix.ipojo.Factory,
- org.osgi.service.cm.ManagedServiceFactory
- service.id = 36
- service.pid = composition4
- ----
- factory.name = composition4
- instance.name = composition4-0
- objectClass = spell.services.SpellChecker
- service.id = 41
- ->
-
-== Hierarchical composites
-
-A composition can also contain others compositions.
-Let's imagine a variation of the latest application.
-In this case, we define a composite containing the GUI and the previous composite.
-
-[source,xml]
-----
-<ipojo>
-
-<!-- Declares the same composition than the latest one -->
-<composite name="composition4">
- <!-- Instantiates an instance of the English dictionary -->
- <subservice action="instantiate"
- specification="spell.services.DictionaryService"/>
-
- <!-- Instantiates an instance of the Checker -->
- <instance component="spell.checker.SpellCheck"/>
-
- <!-- Exports the SpellChecker service -->
- <provides action="export"
- specification="spell.services.SpellChecker"/>
-</composite>
-
-<!-- Declares another composition containing an instance of the previous
- composition and an instance of the GUI
- -->
-<composite name="composition5">
- <!-- Instantiates the previous composition
- You can access to composition by following the
- same way as for other types
- -->
- <instance component="composition4"/>
-
- <!-- Instantiates an instance of the GUI in the composite -->
-<instance component="spell.gui.SpellCheckerGui"/>
-</composite>
-
-<!-- Instantiates an instance of our composition -->
-<instance component="composition5"/>
-
-</ipojo>
-----
-
-The `composition5` contains an instance of the `composition4` and of the GUI.
-So the spell checker service exported by the composition4 is published inside the service context of the `composite 5` (the parent context).
-The GUI instance lives in this service context, and so can access to the exported Spell checker service.
-
-image::documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/app6.png[]
-
-To execute this composition, restart Felix and launch the following commands:
-
-[source,sh]
- start file:../spell.services/output/spell.services.jar
- start file:../spell.english/output/spell.english.jar
- start file:../spell.checker/output/spell.checker.jar
- start file:../spell.checker.gui/output/spell.checker.gui.jar
- start file:../example5/output/composition5.jar
-
-You can check that the composite does no more publish the spell checker service in the OSGi service registry.
-
-== Conclusion
-
-This page has presented how to use iPOJO composition model.
-Several topics were not addressed and will be added shortly:
-
-* Dynamic service implementation
-* The dependency model
-* _Composable_ services and composition consistency
-* Context-awareness
-
-Subscribe to the Felix users mailing list by sending a message to link:mailto:users-subscribe@felix.apache.org[users-subscribe@felix.apache.org];
-after subscribing, email questions or feedback to link:mailto:users@felix.apache.org[users@felix.apache.org].
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-hello-word-maven-based-tutorial.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-hello-word-maven-based-tutorial.adoc
deleted file mode 100644
index 4cd8350..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-hello-word-maven-based-tutorial.adoc
+++ /dev/null
@@ -1,547 +0,0 @@
-= iPOJO Hello Word (Maven-Based) tutorial
-
-_This page presents how to use the iPOJO runtime and its associated service component model.
-The concepts of the service component model are introduced, followed by a simple example that demonstrates the features of iPOJO._
-
-== Introduction
-
-iPOJO aims to simplify service-oriented programming on OSGi frameworks;
-the name iPOJO is an abbreviation for _injected POJO_.
-iPOJO provides a new way to develop OSGi service components with the main goal being to simplify service component implementation by transparently managing the dynamics of the environment as well as other non-functional requirements.
-The iPOJO framework allows developers to more clearly separate functional code (i.e., the POJO) from the non-functional code (i.e., dependency management, service provision, configuration, etc.).
-iPOJO combines the functional and non-functional aspects at run time.
-To achieve this, iPOJO provides a simple and extensible service component model based on POJOs.
-
-== The POJO concept
-
-POJO is an acronym for Plain Old Java Object, but it embodies a concept that the simpler and less intrusive the design of a given framework, the better.
-The name is used to emphasize that a given object is not somehow special, but is an ordinary Java Object.
-Martin Fowler, Rebecca Parsons and Josh Mackenzie coined the term POJO in September 2000: "We wondered why people were so against using regular objects in their systems and concluded that it was because simple objects lacked a fancy name.
-So we gave them one, and it's caught on very nicely." From the developer's perspective, the iPOJO framework strives to only require POJOs in as much as it is possible.
-
-== iPOJO service component overview
-
-A service component is able to provide and/or require services, where a service is an object that implements a given service interface embodied as a Java interface.
-In addition, iPOJO introduces a callback concept to notify a component about various state changes.
-
-The component is the central concept in iPOJO.
-In the core iPOJO model, a component describes service dependencies, provided services, and callbacks;
-this information is recorded in the component's metadata.
-Then, the second important concept in iPOJO is component instances.
-A component instances is a special _version_ of the component.
-By merging component metadata and instance configuration, the iPOJO runtime is able to manage the component, i.e., manage its life cycle, inject required services, publish provided services, discover needed services.
-
-== A simple example
-
-The following is a simple example illustrating how to use the core iPOJO concepts.
-The example is comprised of two components, one providing a _Hello_ service and one requiring any number of _Hello_ services.
-The components are packaged into three different bundles using Maven.
-The _hello.service_ bundle contains the service interface.
-The _hello.impl_ bundle contains a component implementing the service.
-The _hello.client_ bundle contains the consumer component.
-
-Download the tutorial archive http://repo1.maven.org/maven2/org/apache/felix/org.apache.felix.ipojo.distribution.maventutorial/{{ipojo.release}}/org.apache.felix.ipojo.distribution.maventutorial-{{ipojo.release}}.zip[here].
-This archive contains a version of Felix (configured with iPOJO), and the projects explained below.
-
-=== Preparing Maven & Installing the tutorial
-
-The first step is to download and install Maven;
-the example was created using Maven 2.1.
-Once maven is installed on your machine, you can compile the tutorial by unzipping the archive, and by launching the `mvn clean install` command at the root of tutorial.
-
-_Be aware that Maven outputs a lot of information while it executes and often downloads a lot of required JAR files into its local repository._
-
-=== Hello Service
-
-The first project is the _hello.service_ project.
-This project contains only the _hello_ service interface.
-Look at the `src/main/java/ipojo/example/hello/Hello.java` file:
-
-[source,java]
-----
-/**
- * Hello Interface.
- * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
- */
-public interface Hello {
-
- /**
- * Returns a message like: "Hello $user_name".
- * @param name the name
- * @return the hello message
- */
- String sayHello(String name);
-}
-----
-
-In the project directory, the pom.xml file contains the instructions to build the bundle.
-The bundle uses the _maven-bundle-plugin_ (see here for more information on this plug-in).<div class="pom"><project>
-
-[source,xml]
-----
-<modelVersion>4.0.0</modelVersion>
-<packaging>bundle</packaging>
-<groupId>ipojo.example</groupId>
-<artifactId>hello.service</artifactId>
-<version>1.0.0</version>
-<name>Hello Service</name>
-
-<build>
-<plugins>
-
-<plugin>
-
-
-<groupId>org.apache.felix</groupId>
-
-
-<artifactId>maven-bundle-plugin</artifactId>
-
-
-<version>2.0.1</version>
-
-
-<extensions>true</extensions>
-
-
-<configuration>
-
-
-
-<instructions>
-
-
-
-
-<Bundle-SymbolicName>
-
-
-
-
-
-${pom.artifactId}
-
-
-
-
-</Bundle-SymbolicName>
-
-
-
-
-<Export-Package>
-
-
-
-
-
-
-ipojo.example.hello
-
-
-
-
-</Export-Package>
-
-
-
-</instructions>
-
-
-</configuration>
-
-</plugin>
-</plugins> </build>
-
-</project>
-----
-
-Then, the project is ready to be built issuing the following Maven command inside the project directory:
-
-[source,sh]
- mvn clean install
-
-Maven should report that the build was a success;
-if an error was reported then verify the previous steps.
-Upon success the _Hello_ service component JAR file is installed into the local Maven repository.
-A copy of the bundle JAR file will also be present in the "target" directory inside the project directory.
-
-=== Hello Service Provider
-
-The component implementation of the service is a simple Java class implementing the _Hello_ service interface.
-The implementation is in the _hello.impl_ project.
-The file `src/main/java/ipojo/example/hello/impl/HelloImpl.java` contains the following service implementation:
-
-[source,java]
-----
-/**
- * Component implementing the Hello service.
- * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
- */
-public class HelloImpl implements Hello {
-
- /**
- * Returns an 'Hello' message.
- * @param name : name
- * @return Hello message
- * @see ipojo.example.hello.Hello#sayHello(java.lang.String)
- */
- public String sayHello(String name) { return "hello " name; }
-}
-----
-
-To manage the component, iPOJO needs some metadata to understand that the component provides the _Hello_ service.
-iPOJO metadata file is at the root of the _hello.impl_ project ("metadata.xml").
-It contains the following metadata (Note: iPOJO also supports a JAR manifest-based syntax):
-[source,xml]
- <?xml version="1.0" encoding="UTF-8"?>
- <ipojo
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="org.apache.felix.ipojo http://felix.apache.org/ipojo/schemas/CURRENT/core.xsd"
- xmlns="org.apache.felix.ipojo">
-
- <component classname="ipojo.example.hello.impl.HelloImpl"
- name="HelloProvider">
- <provides />
- </component>
-
- <instance component="HelloProvider" name="HelloService" />
- </ipojo>
-
-In the above XML-based metadata, the _component_ element has a mandatory '__classname'__attribute.
-This attribute tells iPOJO the implementation class of the component.
-Since the component in this example provides a service, the component element also specifies a child '_provides_' element.
-The '_provides_' element informs iPOJO that it must manage the publishing of a service.
-When the '_provides_' element does not contain an interface attribute, as is the case in this example, iPOJO will expose all implemented interfaces of the component as a service;
-it is also possible to specify the precise service interface.
-The '_instance_' element asks iPOJO to create an instance of your component when the bundle is started.
-
-Finally, the `pom.xml` file contains instructions to build the bundle:
-
-[source,xml]
-----
-<project>
- <modelVersion>4.0.0</modelVersion>
-<packaging>bundle</packaging> <groupId>ipojo.example</groupId> <artifactId>hello.impl</artifactId> <version>1.0.0</version>
-
-<name>Hello Service Provider</name>
-
-
-<dependencies>
-<dependency> <!--Compilation (i.e.
-class) dependency on the service interface -->
-<groupId>ipojo.example</groupId>
-<artifactId>hello.service</artifactId>
-<version>1.0.0</version>
-</dependency>
-</dependencies>
-
-<build>
-<plugins>
-<plugin>
-<groupId>org.apache.felix</groupId>
-<artifactId>maven-bundle-plugin</artifactId>
-<version>2.0.1</version>
-<extensions>true</extensions>
-<configuration>
-<instructions>
-<Bundle-SymbolicName>${pom.artifactId}</Bundle-SymbolicName>
-<Private-Package>ipojo.example.hello.impl</Private-Package>
-</instructions>
-</configuration>
-</plugin>
-<plugin>
-<groupId>org.apache.felix</groupId>
-<artifactId>maven-ipojo-plugin</artifactId>
-
-
-
-<version>{{ipojo.release}}</version> <executions>
-<execution>
-<goals>
-<goal>ipojo-bundle</goal>
-</goals>
-</execution>
-</executions>
-</plugin>
-</plugins> </build> </project>
-----
-
-The text highlighted in red above indicates the important information related to the project.
-The first part of the POM file indicates that the packaging format is an iPOJO bundle and also includes some information about the project (name, groupId, and artifactId).
-This information is not used by iPOJO, but is used by Maven.
-The rest of the POM file contains the bundle configuration.
-In the _instructions_ element, you need to enter the bundle name, the bundle description, and the exported packages.
-The service provider bundle exports the package of _Hello_ interface.
-
-Then, the project is ready to be built issuing the following Maven command inside the project directory:
-
-[source,sh]
- mvn clean install
-
-Maven should report that the build was a success;
-if an error was reported then verify the previous steps.
-Upon success the _Hello_ service component JAR file is installed into the local Maven repository.
-A copy of the bundle JAR file will also be present in the "target" directory inside the project directory.
-
-=== Hello Service Client
-
-The Hello service consumer is inside the _hello.client_ project.
-The file `src/main/java/ipojo/example/hello/client/HelloClient.java` contains the following _Hello_ service client:
-
-[source,java]
-----
-package ipojo.example.hello.client;
-
-import ipojo.example.hello.Hello;
-
-/**
- * Hello Service simple client.
- * @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
- */
-public class HelloClient implements Runnable {
-
- /**
- * Delay between two invocations.
- */
- private static final int DELAY = 10000;
-
- /**
- * Hello services.
- * Injected by the container.
- * */
- private Hello[] m_hello;
-
- /**
- * End flag.
- * */
- private boolean m_end;
-
- /**
- * Run method.
- * @see java.lang.Runnable#run()
- */
- public void run() {
- while (!m_end) {
- try {
- invokeHelloServices();
- Thread.sleep(DELAY);
- } catch (InterruptedException ie) {
- /* will recheck end */
- }
- }
- }
-
- /**
- * Invoke hello services.
- */
- public void invokeHelloServices() {
- for (int i = 0; i < m_hello.length; i) {
- // Update with your name.
- System.out.println(m_hello[i]({{ refs.i.path }}).sayHello("world"));
- }
- }
-
- /**
- * Starting.
- */
- public void starting() {
- Thread thread = new Thread(this);
- m_end = false;
- thread.start();
- }
-
- /**
- * Stopping.
- */
- public void stopping() {
- m_end = true;
- }
-}
-----
-
-The _Hello_ service client creates a thread that periodically invokes the available _Hello_ services.
-The thread starts when at least one _Hello_ service provider is present using iPOJO's call back mechanism.
-In the client code, to use the _hello_ the component implementation simply declares a field of the type of the service and then simply uses it directly in its code.
-In this example, it is the m_hello field is declared as the service field;
-notice that the field is an array of _Hello_.
-In iPOJO an array of services represents an aggregate or multiple cardinality dependency, whereas if a scalar value represents a singular or unary cardinality dependency.
-In other words, for a singular dependency simply remove the array brackets from the example (e.g., HelloService m_hello[].
-After declaring a field for the service, the rest of the component code can simply assume that the service field will be initialized, e.g., m_hello[i].sayHello("world").
-
-Notice that iPOJO manages service synchronization too.
-So, the service invocations do not require synchronization blocks.
-This synchronization is maintained on a per thread basis, where each method that accesses a service is instrumented to attach the given service instance to the thread so that the thread will continue to see the same service instances even across nested method invocations.
-The thread will not see different service instances until it completely exits from the first method it entered which used a services.
-Thus, you would not want to access services in the {{run()}} method above, because the thread would always see the same service instance.
-
-The component provides two callback methods for its activation and deactivation, starting() and stopping(), respectively.
-Callbacks are used when the component needs to be informed about a component state change.
-In iPOJO, the component state is either _INVALID_ (i.e., not all of the component's constraints are satisfied) or _VALID_ (i.e., all of the component's constraints are satisfied).
-In this example, the starting callback method creates and starts a thread;
-the stopping callback method stops the thread.
-The component metadata will instruct iPOJO to invoke these methods when the component's state changes to _VALID_ or _INVALID_ respectively.
-
-The iPOJO metadata file describing the component is "metadata.xml" and contains the following metadata:
-
-[source,xml]
-----
-<?xml version="1.0" encoding="UTF-8"?>
-<ipojo
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="org.apache.felix.ipojo http://felix.apache.org/ipojo/schemas/CURRENT/core.xsd"
- xmlns="org.apache.felix.ipojo">
-
- <component classname="ipojo.example.hello.client.HelloClient">
- <requires field="m_hello" />
- <callback transition="validate" method="starting" />
- <callback transition="invalidate" method="stopping" />
- <properties>
- <property field="m_name" name="hello.name" />
- </properties>
- </component>
-
- <instance component="ipojo.example.hello.client.HelloClient">
- <property name="hello.name" value="clement" />
- </instance>
-</ipojo>
-----
-
-The component element again has the '_classname'_ attribute that refers to the component implementation class.
-The '_requires_' element describes the _Hello_ service dependency by simply specifying its associated component field.
-The '__callback'__elements describe which method to invoke when the component's state changes.
-Then the '_instance_' element asks iPOJO to create an instance of the component (notice that no instance name is provided here, iPOJO will give an instance name to the instance automatically).
-
-Finally, the `pom.xml` file contains instructions to build the bundle:
-
-[source,xml]
-----
-<project> <modelVersion>4.0.0</modelVersion> <packaging>bundle</packaging> <groupId>ipojo.example</groupId> <artifactId>hello.client</artifactId> <version>1.0.0</version> <name>Hello Client</name>
-
-<dependencies>
-<dependency> <!-- Compilation (i.e.
-class) dependency on the service interface -->
-<groupId>ipojo.example</groupId>
-<artifactId>hello.service</artifactId>
-<version>1.0.0</version>
-</dependency>
-</dependencies>
-
-
-<build>
-<plugins>
-<plugin>
-<groupId>org.apache.felix</groupId>
-<artifactId>maven-bundle-plugin</artifactId>
-<version>2.0.1</version>
-<extensions>true</extensions>
-<configuration>
-<instructions>
-<Bundle-SymbolicName>${pom.artifactId}</Bundle-SymbolicName>
-<Private-Package>ipojo.example.hello.client</Private-Package>
-</instructions>
-</configuration>
-</plugin>
-<plugin>
-<groupId>org.apache.felix</groupId>
-<artifactId>maven-ipojo-plugin</artifactId>
-
-
-<version>{{ipojo.release}}</version>
-<executions>
-<execution>
-<goals>
-<goal>ipojo-bundle</goal>
-</goals>
-
-
-
-
-</execution>
-
-
-
-</executions>
-</plugin> </plugins>
-</build> </project>
-----
-
-The text highlighted in red</code> above indicates the information related to the project.
-The _dependencies_ element tells Maven that the client bundle has a compilation dependency on the service provider bundle.
-In this case, the client bundle needs the _Hello_ service interface to compile.
-After building the service provider bundle JAR file, Maven installs it into a local repository on your machine.
-To resolve compilation dependencies, Maven looks in the local repository to find required JAR files.
-After the skeleton "pom.xml" file is modified, the project is ready to be built issuing the following Maven command inside the project directory:
-
-[source,sh]
- mvn clean install
-
-Maven should report that the build was a success;
-if an error was reported then verify the previous steps.
-Upon success the _Hello_ service component JAR file is installed into the local Maven repository.
-A copy of the bundle JAR file will also be present in the "target" directory inside the project directory.
-
-== Running the example
-
-To run the example, start Felix.
-A distribution of Felix is provided in the felix-1.0.3 directory.
-This version is configured to launch iPOJO automatically.
-From the Felix directory, launch the following command to start the framework
-
-[source,sh]
- java -jar bin/felix.jar
-
-You can check installed bundles by using the '_ps'_ command:
-
-[source,sh]
- -> ps
- START LEVEL 1
- ID State Level Name
- [ 0] [Active ] [ 0] System Bundle (2.0.5)
- [ 1] [Active ] [ 1] Apache Felix Bundle Repository (1.4.3)
- [ 2] [Active ] [ 1] Apache Felix iPOJO ({{ipojo.release}})
- [ 3] [Active ] [ 1] Apache Felix iPOJO Arch Command (1.6.0)
- [ 4] [Active ] [ 1] Apache Felix Shell Service (1.4.2)
- [ 5] [Active ] [ 1] Apache Felix Shell TUI (1.4.1)
- ->
-
-iPOJO runtime is the bundle 4.
-The bundle 5 is a Felix shell command allowing the introspection of iPOJO component instances (see herefor further information).
-
-Install the Hello service bundle, the _Hello_ service provider and the client that were created above:
-
-[source,sh]
- start file:../hello.service/target/hello.service-1.0.0.jar
- start file:../hello.impl/target/hello.impl-1.0.0.jar
- start file:../hello.client/target/hello.client-1.0.0.jar
-
-By starting the _Hello_ service provider bundle, the client component will automatically be activated.
-So, the _'hello world'_ messages are displayed.
-
-[source,sh]
- -> hello world
- hello world
-
-Stop the provider (with the '_stop 7_' command) and the client will automatically be deactivated since its dependency is no longer valid.
-If multiple Hello services are deployed, the client will connect to all of them.
-If you restart the bundle (with the _start 7_ command), the client becomes valid.
-
-During these operations, you can use the arch command to check the state of instances.
-
-[source,sh]
--> stop 7 -> arch Instance ArchCommand -> valid Instance ipojo.example.hello.client.HelloClient-0 -> invalid -> arch -instance ipojo.example.hello.client.HelloClient-0 instance name="ipojo.example.hello.client.HelloClient-0" component.type="ipojo.example.hello.client.HelloClient" state="invalid" bundle="8"
-object name="ipojo.example.hello.client.HelloClient@137c60d"
-handler name="org.apache.felix.ipojo.handlers.dependency.DependencyHandler" state="invalid" requires aggregate="true" optional="false" state="resolved" specification="ipojo.example.hello.Hello"
-handler name="org.apache.felix.ipojo.handlers.lifecycle.callback.LifecycleCallbackHandler" state="valid"
-handler name="org.apache.felix.ipojo.handlers.architecture.ArchitectureHandler" state="valid" -> start 7 hello world -> arch Instance ArchCommand -> valid Instance ipojo.example.hello.client.HelloClient-0 -> valid Instance HelloService -> valid -> arch -instance ipojo.example.hello.client.HelloClient-0 instance name="ipojo.example.hello.client.HelloClient-0" component.type="ipojo.example.hello.client.HelloClient"
-state="valid" bundle="8"
-object name="ipojo.example.hello.client.HelloClient@137c60d"
-handler name="org.apache.felix.ipojo.handlers.dependency.DependencyHandler" state="valid" requires aggregate="true" optional="false" state="resolved" specification="ipojo.example.hello.Hello" uses service.id="38" instance.name="HelloService"
-handler name="org.apache.felix.ipojo.handlers.lifecycle.callback.LifecycleCallbackHandler" state="valid"
-handler name="org.apache.felix.ipojo.handlers.architecture.ArchitectureHandler" state="valid"
-
-== Conclusion
-
-We saw how to use easily iPOJO to build service-oriented components.
-Subscribe to the Felix users mailing list by sending a message to link:mailto:users-subscribe@felix.apache.org[users-subscribe@felix.apache.org];
-after subscribing, email questions or feedback to link:mailto:users@felix.apache.org[users@felix.apache.org].
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-in-10-minutes.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-in-10-minutes.adoc
deleted file mode 100644
index 7d6aefc..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-in-10-minutes.adoc
+++ /dev/null
@@ -1,609 +0,0 @@
-= iPOJO in 10 minutes
-
-This page presents how to use the iPOJO runtime and its associated service component model.
-The concepts of the service component model are introduced, followed by a simple example that demonstrates the features of iPOJO.
-This tutorial uses annotations to describe components.
-However, you can also use XML or a programmatic API to create iPOJO applications.
-
-== Introduction
-
-iPOJO aims to simplify service-oriented programming on OSGi frameworks;
-the name iPOJO is an abbreviation for _injected POJO_.
-iPOJO provides a new way to develop OSGi service components, simplifying service component implementation by transparently managing the dynamics of the environment as well as other non-functional requirements.
-The iPOJO framework allows developers to more clearly separate functional code (i.e., POJOs) from the non-functional code (i.e., dependency management, service provision, configuration, etc.).
-At run time, iPOJO combines the functional and non-functional aspects.
-To achieve this, iPOJO provides a simple and extensible service component model based on POJOs.
-
-== The POJO concept
-
-"POJO" is just an acronym for Plain Old Java Object, but it embodies a concept that the simpler and less intrusive the design of a given framework, the better.
-The name is used to emphasize that a given object is not somehow special, but is an ordinary Java Object.
-Martin Fowler, Rebecca Parsons and Josh Mackenzie coined the term POJO in September 2000: "We wondered why people were so against using regular objects in their systems and concluded that it was because simple objects lacked a fancy name.
-So we gave them one, and it's caught on very nicely." From a developer's perspective, the iPOJO framework strives as much as possible to only require POJOs.
-
-== iPOJO service component overview
-
-A service component is able to provide and/or require services, where a service is an object that implements a given Java interface.
-In addition, iPOJO introduces a callback concept to notify a component about various state changes.
-
-The component is a central concept in iPOJO.
-In the core iPOJO model, a component describes service dependencies, provided services, and callbacks;
-this information is recorded in the component's metadata.
-After components, the next most important concept in iPOJO is the component instance.
-A component instance is a special _version_ of a component.
-By merging component metadata and instance configuration, the iPOJO runtime is able to discover and inject required services, publish provided services, and manage the component's life cycle.
-
-== A simple example
-
-In this tutorial we will present how to:
-
-* Publish an OSGi service
-* Require an OSGi service
-* Use lifecycle callbacks to activate and deactivate components
-
-=== Presentation of the _Spell_ application
-
-To illustrate iPOJO features, we will implement a very simple application.
-This application is composed by three components:
-
-* A component implementing a dictionary service
-* A component requiring the dictionary service and providing a spellchecker service
-* A component requiring the spellchecker and providing an user interface
-
-image::documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/spell.png[]
-
-=== Preparing the tutorial
-
-This tutorial is based on Ant.
-So, you need to have the Ant program accessible in your path (see http://ant.apache.org/[here] to download and install Ant).
-Download the tutorial archive available http://repo1.maven.org/maven2/org/apache/felix/org.apache.felix.ipojo.distribution.10mintutorial/{{ipojo.release}}/org.apache.felix.ipojo.distribution.10mintutorial-{{ipojo.release}}.zip[here] and then unzip it.
-The archive contains seven directories:
-
-* spell.services contains service interfaces used by the applications
-* spell.english contains an implementation of the Dictionary service (containing English words)
-* spell.checker contains an implementation of a Spell Checker.
-The spell checker requires a dictionary service and check if an input passage is correct (according to the words contained in the dictionary).
-* spell.gui contains a very simple user interface.
-This component uses a spell checker service.
-Then the user can interact with the spell checker with this user interface.
-* The task directory contains Ant tasks used to build the project
-* The solution directory contains an already developed version of the application.
-* Finally, the felix folder contains a configured version of the Felix runtime
-
-=== The spell.services project
-
-The spell.services project contains only service interfaces.
-It is not an iPOJO powered bundle.
-
-Go inside the spell.services directory and open the file "src/spell/services/DictionaryService.java".
-It's a very simple service interface with one method:
-
-[source,java]
- package spell.services;
- /**
- * A simple service interface that defines a dictionary service.
- * A dictionary service simply verifies the existence of a word.
- **/
- public interface DictionaryService {
- /**
- * Check for the existence of a word.
- * @param word the word to be checked.
- * @return true if the word is in the dictionary,
- * false otherwise.
- **/
- public boolean checkWord(String word);
- }
-
-Then, open the file `src/spell/services/SpellChecker.java`, and replace the `TODO` comment with for the following `check` method:
-
-[source,java]
- package spell.services;
- /**
- * A simple service interface that defines a spell checker service.
- * A spell checker service checks the spelling of all words in a
- * given passage. A passage is any number of words separated by
- * a space character and the following punctuation marks: comma,
- * period, exclamation mark, question mark, semi-colon, and colon.
- **/
- public interface SpellChecker {
- /**
- * Checks a given passage for spelling errors. A passage is any
- * number of words separated by a space and any of the following
- * punctuation marks: comma (,), period (.), exclamation mark (!),
- * question mark (?), semi-colon (;), and colon(:).
- * @param passage the passage to spell check.
- * @return An array of misspelled words or null if no
- * words are misspelled.
- **/
- public String[] check(String passage);
- }
-
-Once created, you can build the project by launching Ant from the project directory.
-
-[source,sh]
- $ ant
- Buildfile: build.xml
- clean:
- compile:
- [mkdir] Created dir: d:\clement\workspaces\sandbox\ipojo\examples\tutorial-ant\
- spell.services\output
- [mkdir] Created dir: d:\clement\workspaces\sandbox\ipojo\examples\tutorial-ant\
- spell.services\output\classes
- [javac] Compiling 2 source files to d:\clement\workspaces\sandbox\ipojo\examples\
- tutorial-ant\spell.services\output\classes
- package:
- [bnd] spell.services 2
- BUILD SUCCESSFUL
- Total time: 0 seconds
-
-The created bundle is inside the output directory (spell.services.jar).
-The build process uses http://bnd.bndtools.org/[BND].
-The bundle manifest is described in the spell.services.bnd file.
-
-Once this project is done, we are able to implement a Dictionary service.
-
-=== The spell.english project: Providing an OSGi service
-
-The spell.english project is a simple dictionary implementation of the Dictionary service.
-It contains few English words.
-This implementation is an iPOJO component.
-
-The first step is to implement the service.
-Go in the spell.english directory and open the "src/spell/english/EnglishDictionary.java" file.
-Replace its content with:
-
-[source,java]
-----
-package spell.english;
-
-import org.apache.felix.ipojo.annotations.Component;
-import org.apache.felix.ipojo.annotations.Instantiate;
-import org.apache.felix.ipojo.annotations.Provides;
-import spell.services.DictionaryService;
-
-/**
- * An implementation of the Dictionary service containing English words
- * see DictionaryService for details of the service.
- **/
-@Component // It's an iPOJO Component
-@Provides // We provide a service
-@Instantiate // We declare an instance of our component
-public class EnglishDictionary implements DictionaryService {
-
- // The set of words contained in the dictionary.
- String[] dictionary = { "welcome", "to", "the", "ipojo", "tutorial" };
-
- /**
- * Implements DictionaryService.checkWord(). Determines
- * if the passed in word is contained in the dictionary.
- * @param word the word to be checked.
- * @return true if the word is in the dictionary,
- * false otherwise.
- **/
- public boolean checkWord(String word) {
- word = word.toLowerCase();
-
- // This is very inefficient
- for (String dict : dictionary) {
- if (dict.equals(word)) {
- return true;
- }
- }
- return false;
- }
-}
-----
-
-Notice that this class does not contains neither OSGi nor iPOJO specific code except a few annotations.
-It is just an implementation of the Dictionary Service interface.
-
-The `@Component` annotation is used to declare an iPOJO component.
-The `@Provides` annotation indicates that the component provides a service.
-Provided service interfaces are computed by iPOJO, so it is not necessary to specify them.
-Finally, the `@Instantiate` annotation instructs iPOJO to create an instance of our component.
-The relation between components and instances is the same than between classes and objects in the object-oriented programming.
-
-Then, we are able to create the bundle.
-In the spell.english directory launch the ant command:
-
-
-[source,sh]
-----
-$ ant
-Buildfile: /Users/clement/Projects/felix-trunk/ipojo/distributions/ten-minutes-tutorial/target/test/spell.english/build.xml
-
-clean:
-
-buildclasspath:
- [copy] Copying 1 file to /Users/clement/Projects/felix-trunk/ipojo/distributions/ten-minutes-tutorial/target/test/spell.english/libs
- [copy] Copying 1 file to /Users/clement/Projects/felix-trunk/ipojo/distributions/ten-minutes-tutorial/target/test/spell.english/libs
-
-compile:
- [mkdir] Created dir: /Users/clement/Projects/felix-trunk/ipojo/distributions/ten-minutes-tutorial/target/test/spell.english/output
- [mkdir] Created dir: /Users/clement/Projects/felix-trunk/ipojo/distributions/ten-minutes-tutorial/target/test/spell.english/output/classes
- [javac] /Users/clement/Projects/felix-trunk/ipojo/distributions/ten-minutes-tutorial/target/test/spell.english/build.xml:57: warning: 'includeantruntime' was not set, defaulting to build.sysclasspath=last; set to false for repeatable builds
- [javac] Compiling 1 source file to /Users/clement/Projects/felix-trunk/ipojo/distributions/ten-minutes-tutorial/target/test/spell.english/output/classes
-
-package:
- [bnd] # addAll 'output/classes' with :,
- [bnd] # addAll 'spell.english.bnd' with ,
- [bnd] Updating classpath after classpathref setting
- [bnd] # spell.english (spell.english.jar) 1
- [ipojo] Input bundle file : /Users/clement/Projects/felix-trunk/ipojo/distributions/ten-minutes-tutorial/target/test/spell.english/output/spell.english.jar
- [ipojo] No metadata file found - trying to use only annotations
- [ipojo] Start manipulation
-Apache Felix iPOJO Manipulator - 1.9.0-SNAPSHOT
- [ipojo] Bundle manipulation - SUCCESS
- [ipojo] Output file : /Users/clement/Projects/felix-trunk/ipojo/distributions/ten-minutes-tutorial/target/test/spell.english/output/spell.english.jar
-
-BUILD SUCCESSFUL
-Total time: 0 seconds
-----
-
-The created bundle is inside the output directory (spell.english.jar).
-The build process is based on BND and on the iPOJO Ant task.
-The manifest of the bundle is described in the `spell.english.bnd` file.
-
-=== The spell.checker project: Requiring an OSGi service
-
-The spell.checker project aims to provide a _spell checker_ service.
-However, to serve this service, this implementation requires a _dictionary_ service.
-During this step, we will create an iPOJO component requiring a Dictionary service and providing the Spell Checker service.
-
-First, go the the spell.checker directory and open the file `src/spell/checker/SpellCheck.java`.
-Replace its content with:
-
-[source,java]
-----
-package spell.checker;
-
-import org.apache.felix.ipojo.annotations.Component;
-import org.apache.felix.ipojo.annotations.Instantiate;
-import org.apache.felix.ipojo.annotations.Provides;
-import org.apache.felix.ipojo.annotations.Requires;
-import spell.services.DictionaryService;
-import spell.services.SpellChecker;
-
-import java.util.ArrayList;
-import java.util.List;
-import java.util.StringTokenizer;
-
-@Component
-@Provides
-@Instantiate
-public class SpellCheck implements SpellChecker {
-
- @Requires // This is a service dependency.
- private DictionaryService dictionary;
-
- /**
- * Implements SpellChecker.check(). Checks the given passage for misspelled words.
- *
- * @param passage the passage to spell check.
- * @return An array of misspelled words or null if no words are misspelled.
- */
- public String[] check(String passage) {
- // No misspelled words for an empty string.
- if ((passage == null) || (passage.length() == 0)) {
- return null;
- }
-
- List<String> errorList = new ArrayList<String>();
-
- // Tokenize the passage using spaces and punctuation.
- StringTokenizer st = new StringTokenizer(passage, " ,.!?;:");
-
- // Loop through each word in the passage.
- while (st.hasMoreTokens()) {
- String word = st.nextToken();
-
- // Check the current word.
- if (!dictionary.checkWord(word)) {
- // If the word is not correct, then add it
- // to the incorrect word list.
- errorList.add(word);
- }
- }
-
- // Return null if no words are incorrect.
- if (errorList.size() == 0) {
- return null;
- }
-
- // Return the array of incorrect words.
- System.out.println("Wrong words:" + errorList);
- return errorList.toArray(new String[errorList.size()]);
- }
-}
-----
-
-This class implements the SpellChecker service interface as it provides it.
-Moreover, it has a _special_ field `dictionary`.
-This field represents the required service.
-iPOJO injects a Dictionary service when needed.
-So, the class can use it directly.
-Notice that this class as no OSGi specific code, both the service providing and the requiring are managed by iPOJO and described using annotations.
-When the used dictionary service leaves, iPOJO tries to find another provider.
-If no more providers are available, the instance is invalidated, and the provided service is withdrawn from the service registry.
-
-The @Component, @Instantiate and @Provides annotations were already presented.
-The `@Requires` annotation specifies a service dependency.
-This example shows field injection, but iPOJO also supports constructor injection and method injection (with `@Bind` and `@Unbind`).
-
-Finally, we are able to build the bundle.
-As for previous projects, launch Ant from the project directory.
-
-=== The spell.checker.gui project
-
-The spell.check.gui project contains a very simple user interface (in Swing) allowing a user to interact with a _spell checker_ service.
-
-Go to the spell.checker.gui directory.
-Open the `src\spell\gui\SpellCheckerGui.java`.
-Replace its content with:
-
-[source,java]
-----
-package spell.gui;
-
-import org.apache.felix.ipojo.annotations.*;
-import spell.services.SpellChecker;
-
-import javax.swing.*;
-
-/**
- * A very simple Gui interacting with the CheckSpeller service
- */
-@Component
-@Instantiate
-public class SpellCheckerGui extends JFrame {
-
- private static final long serialVersionUID = 1L;
-
- /**
- * Swing component where the user write the passage to check.
- */
- private JTextField passage = null;
-
- /**
- * Area where the result is displayed.
- */
- private JLabel result = null;
-
- /**
- * Service dependency on the SpellChecker.
- */
- @Requires
- private SpellChecker checker;
-
- /**
- * Constructor.
- * Initialize the GUI.
- */
- public SpellCheckerGui() {
- super();
- initComponents();
- this.setTitle("Spellchecker Gui");
- }
-
- /**
- * Initialize the Swing Gui.
- */
- private void initComponents() {
- java.awt.GridBagConstraints gridBagConstraints;
-
- // The check button
- JButton checkButton = new JButton();
- result = new JLabel();
- passage = new JTextField();
-
- setDefaultCloseOperation(javax.swing.WindowConstants.EXIT_ON_CLOSE); // Stop Felix...
- getContentPane().setLayout(new java.awt.GridBagLayout());
-
- checkButton.setText("Check");
- checkButton.addActionListener(new java.awt.event.ActionListener() {
- public void actionPerformed(java.awt.event.ActionEvent e) {
- check();
- }
- });
- gridBagConstraints = new java.awt.GridBagConstraints();
- gridBagConstraints.gridx = 0;
- gridBagConstraints.gridy = 1;
- gridBagConstraints.insets = new java.awt.Insets(2, 2, 2, 2);
- getContentPane().add(checkButton, gridBagConstraints);
-
- result.setPreferredSize(new java.awt.Dimension(175, 20));
- gridBagConstraints = new java.awt.GridBagConstraints();
- gridBagConstraints.gridx = 0;
- gridBagConstraints.gridy = 2;
- gridBagConstraints.fill = java.awt.GridBagConstraints.HORIZONTAL;
- gridBagConstraints.insets = new java.awt.Insets(2, 2, 2, 2);
- getContentPane().add(result, gridBagConstraints);
-
- passage.setPreferredSize(new java.awt.Dimension(175, 20));
- gridBagConstraints = new java.awt.GridBagConstraints();
- gridBagConstraints.gridx = 0;
- gridBagConstraints.gridy = 0;
- gridBagConstraints.fill = java.awt.GridBagConstraints.HORIZONTAL;
- gridBagConstraints.insets = new java.awt.Insets(2, 2, 2, 2);
- getContentPane().add(passage, gridBagConstraints);
-
- pack();
- }
-
- /**
- * Check Button action.
- * Collects the user input and checks it.
- */
- private void check() {
- String[] result = checker.check(passage.getText());
- if (result != null) {
- this.result.setText(result.length + " word(s) are misspelled");
- } else {
- this.result.setText("All words are correct");
- }
- }
-
- /**
- * Start callback.
- * This method will be called when the instance becomes valid.
- * It set the Gui visibility to true.
- */
- @Validate
- public void start() {
- this.setVisible(true);
- }
-
- /**
- * Stop callback.
- * This method will be called when the instance becomes invalid or stops.
- * It deletes the Gui.
- */
- @Invalidate
- public void stop() {
- this.dispose();
- }
-}
-----
-
-Look at the three last methods.
-The _check_ methods collects the user input and uses a _Check speller_ service to check this input.
-The speller is injected into the `checker` field thanks to the `@Requires` annotation.
-This method is called when the user presses the button.
-The _start_ and _stop_ methods are lifecycle callbacks.
-As we display the user interface when the instance is created and to dispose it when the instance stops, we need a way to be notified when we need to execute these actions.
-iPOJO provides an easy way to do this.
-The component provides two callback methods for its activation and deactivation.
-Callbacks are used when the component needs to be informed about a component state change.
-In iPOJO, the component state is either _INVALID_ (i.e., not all of the component's constraints are satisfied) or _VALID_ (i.e., all of the component's constraints are satisfied).
-In this example, the start callback method sets the GUI visibility to true;
-the stop callback method deletes the GUI.
-The `@Validate` and `@Invalidate` annotations are used to specify these callbacks.
-
-Once this file is created, you can compile the project by launching _ant_ in the spell.checker.gui directory.
-
-== Running the application
-
-We have all the bundles required to start playing with the application.
-
-To run the example, start Felix.
-A distribution of Felix is provided in the felix-framework-VERSION directory.
-This version is configured to launch iPOJO automatically.
-From the Felix directory, launch the following command to start the framework.
-Then enter a profile name.
-
-[source,sh]
- java -jar bin/felix.jar
-
-You can check installed bundles by using the '_lb_' command:
-
-[source,sh]
-----
-____________________________
-Welcome to Apache Felix Gogo
-
-g! lb
-START LEVEL 1
- ID|State |Level|Name
- 0|Active | 0|System Bundle (4.2.1)
- 1|Active | 1|Apache Felix Bundle Repository (1.6.6)
- 2|Active | 1|Apache Felix Gogo Command (0.12.0)
- 3|Active | 1|Apache Felix Gogo Runtime (0.10.0)
- 4|Active | 1|Apache Felix Gogo Shell (0.10.0)
- 5|Active | 1|Apache Felix iPOJO (1.9.0.SNAPSHOT)
- 6|Active | 1|Apache Felix iPOJO Gogo Command (1.0.1)
-g!
-----
-
-iPOJO runtime is the bundle 5.
-Once started, install the four created bundles as below:
-
-[source,sh]
-----
- start file:../spell.services/output/spell.services.jar
- start file:../spell.english/output/spell.english.jar
- start file:../spell.checker/output/spell.checker.jar
- start file:../spell.checker.gui/output/spell.checker.gui.jar
-----
-
-The new set of bundles is:
-
-[source,sh]
-----
- g! lb
- START LEVEL 1
- ID|State |Level|Name
- 0|Active | 0|System Bundle (4.2.1)
- 1|Active | 1|Apache Felix Bundle Repository (1.6.6)
- 2|Active | 1|Apache Felix Gogo Command (0.12.0)
- 3|Active | 1|Apache Felix Gogo Runtime (0.10.0)
- 4|Active | 1|Apache Felix Gogo Shell (0.10.0)
- 5|Active | 1|Apache Felix iPOJO (1.9.0.SNAPSHOT)
- 6|Active | 1|Apache Felix iPOJO Gogo Command (1.0.1)
- 7|Active | 1|spell.services (0.0.0)
- 8|Active | 1|spell.english (0.0.0)
- 9|Active | 1|spell.checker (0.0.0)
- 10|Active | 1|spell.checker.gui (0.0.0)
-----
-
-iPOJO provides a command to check created instances:
-
-[source,sh]
-----
- g! instances
- Instance org.apache.felix.ipojo.arch.gogo.Arch-0 -> valid
- Instance spell.checker.SpellCheck-0 -> valid
- Instance spell.gui.SpellCheckerGui-0 -> valid
- Instance spell.english.EnglishDictionary-0 -> valid
-----
-
-As you can see, all our instances are valid.
-
-In the gui (that should have appeared), you can interact with the spell service by entering a passage and clicking on the check button:
-
-image::documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ss.png[]
-
-Then, stop the _Dictionary_ service provider (with the _stop 8_) command.
-The GUI disappears.
-Indeed, Spell Checker service cannot be provided as it depends on the Dictionary service.
-
-image::documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/spell2.png[]
-
-You can check the validity of the instances and see that the SpellChecker and the Gui are invalid.
-
-[source,sh]
-----
- g! instances
- Instance org.apache.felix.ipojo.arch.gogo.Arch-0 -> valid
- Instance spell.checker.SpellCheck-0 -> invalid
- Instance spell.gui.SpellCheckerGui-0 -> invalid
-----
-
-Then, restart the Dictionary service provider with the _start 8_ command.
-The GUI reappears immediately.
-You can try to stop the _check speller_ service provider without stopping the _dictionary_ service provider with the _stop 9_ command.
-As for the last manipulation, the GUI disappears.
-
-image::documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/spell3.png[]
-
-This time, the Gui is invalid, but the English dictionary is valid:
-
-[source,sh]
-----
- g! instances
- Instance org.apache.felix.ipojo.arch.gogo.Arch-0 -> valid
- Instance spell.gui.SpellCheckerGui-0 -> invalid
- Instance spell.english.EnglishDictionary-0 -> valid
-----
-
-== Conclusion
-
-We saw how to use easily iPOJO to build service-oriented component.
-In this tutorial, we have demonstrated how to:
-
-* Publish OSGi services
-* Require OSGi services
-* Use lifecycle callbacks to activate and deactivate components
-
-iPOJO provides a lot of others features that you can try in the others available tutorials.
-Subscribe to the Felix users mailing list by sending a message to link:mailto:users-subscribe@felix.apache.org[users-subscribe@felix.apache.org];
-after subscribing, email questions or feedback to link:mailto:users@felix.apache.org[users@felix.apache.org].
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-junit4osgi.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-junit4osgi.adoc
deleted file mode 100644
index bbf197c..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-junit4osgi.adoc
+++ /dev/null
@@ -1,30 +0,0 @@
-= The JUnit4OSGi framework: a simple test framework for OSGi
-
-_JUnit4OSGi is a test framework executing JUnit tests on an OSGi runtime.
-JUnit4OSGi provides a JUnit{pp} environment specialized for OSGi, several runners and a maven plugin executing your tests during your build process_
-
-== Why JUnit4OSGi ?
-
-OSGi is a great technology to create modular and dynamic applications.
-However, creating modular applications raise the need of integration tests: How to be sure that all my modules/services...
-collaborate correctly.
-Unit test is great, but does not really check my whole system and the relation between my modules.
-Junit4OSGi is a framework allowing the execution of JUnit tests in an OSGi environment !
-It stems from the fact that testing applications on top on OSGi is quite complex compared to classic Java unitary tests.
-With junit4osgi you will be able to test all your bundles together and check that everything works correctly (integration tests).
-
-The goal of JUnit4OSGi is to provide the same mechanisms as unitary tests in an OSGi context.
-It allows using the JUnit concepts, although tests are run in an OSGi framework, using all of its distinctiveness.
-The JUnit4OSGi framework allows you to :
-
-* Perform OSGi services tests.
-* Test applications on different VMs, OSGi implementations.
-* Test dynamism impact.
-
-Interested by `junit4osgi`...
-start the adventure !
-
-* xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-junit4osgi/apache-felix-ipojo-junit4osgi-tutorial.adoc[Tutorial]
-* xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-junit4osgi/apache-felix-ipojo-junit4osgi-methods.adoc[OSGi and firends methods]
-* xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-junit4osgi/apache-felix-ipojo-junit4osgi-architecture.adoc[junit4osgi architecture]
-* xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-junit4osgi/apache-felix-ipojo-junit4osgi-maven.adoc[Running your test in Maven]
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-junit4osgi/apache-felix-ipojo-junit4osgi-architecture.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-junit4osgi/apache-felix-ipojo-junit4osgi-architecture.adoc
deleted file mode 100644
index 7c5b335..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-junit4osgi/apache-felix-ipojo-junit4osgi-architecture.adoc
+++ /dev/null
@@ -1,43 +0,0 @@
-= junit4osgi framework architecture
-
-_This page describes the architecture of the junit4osgi framework.
-This does not include the maven-junit4osgi-plugin._
-
-== Global architecture
-
-[cols=2*]
-|===
-| !junit4osgi-arch.png
-| align=center, width=50%, height=50%!
-|===
-
-A system tested with junit4OSGi is divide in three parts:
-
-. The tested system composed by bundles/services/...
-composing the system under tests.
-This can be the `true` application.
-. Tests bundles containing tests stressing/checking the system under tests.
-. The junit4OSGi framework composed by a runtime bundle (executing tests) and a runner bundle (launching test).
-
-junit4OSGi does not impacts anything on the system under test.
-Test bundles interact with the system under test via services/events ...
-Bundle containing tests declared contained test suites in there `manifest` such as:
-
- Test-Suite: org.apache.felix.ipojo.test.scenarios.ps.ProvidedServiceTestSuite, org.apache.felix.ipojo.scenarios.ps.StrategyTestSuite
-
-Thanks to this `manifest` header, the junit4OSGi runtime bundle collects tests.
-This bundle is the core of the test framework, and manage both collection and execution of tests.
-The runner bundle just launch tests.
-According to the runner implementation, test selection can also be done.
-Several runner have been developped:
-
-* `junit` Felix command: executing test from the Felix shell (only for Felix)
-* Swing runner: executing test from a Swing application (works for Felix, Equinox and Knopflerfish)
-* Immediate runner: executing test as soon the runner arrives in the framework (works for Felix, Equinox and Knopflerfish)
-* Maven runner: launching an embedded Felix with required bundle and launching test automatically during the Maven build process.
-
-== Why junit 3 ?
-
-The junit4OSGi framework use junit 3 because it was design and developed to test embedded systems.
-So, the junit4OSGi framework runs on a J2ME Foundation Profile 1.1 virtual machine (such as Mika).
-However, soon, junit4OSGi will evolve to support Junit4 and TestNG.
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-junit4osgi/apache-felix-ipojo-junit4osgi-maven.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-junit4osgi/apache-felix-ipojo-junit4osgi-maven.adoc
deleted file mode 100644
index 51b73a4..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-junit4osgi/apache-felix-ipojo-junit4osgi-maven.adoc
+++ /dev/null
@@ -1,225 +0,0 @@
-= The Maven-junit4OSGi-plugin
-
-_junit4OSGi tests can also be executed automatically during the `integration-test` phase of a maven build process.
-This page describes the maven-junit4osgi-plugin allowing a seamless maven integration._
-
-== What does the maven-junit4osgi-plugin provide?
-
-----
-* Allows testing OSGi applications
-* Integrated in a Maven-based build process
-* Provides the same output as Surefire
-* Supports Maven site generation
-----
-
-== Using the plug-in
-
-=== Download and building the plug-in
-
-The plug-in sources are available in the iPOJO trunk.
-However the junit4osgi and iPOJO runtime are also required.
-So, download the source of iPOJO: `+svn co http://svn.apache.org/repos/asf/felix/trunk/ipojo/+` To compile it, run the following commands:
-
- cd ipojo
- mvn clean install -Pexamples
-
-== Simple configuration
-
-So, first the project using the plug-in is not the project under test.
-It's another project containing either only integration-test packaged in a bundle, or is empty (and so depends on other bundles containing integration tests).
-Tests contained in the project are developed with junit4osgi, and are packaged in a bundle with the maven-bundle-plugin.
-In the pom file, add the following plugin configuration to use the maven-junit4osgi-plugin:
-
- <plugin>
- <groupid>org.apache.felix</groupid>
- <artifactid>maven-junit4osgi-plugin</artifactid>
- <executions>
- <execution>
- <goals>
- <goal>test</goal>
- </goals>
- <configuration>
- <deployprojectartifact>true</deployprojectartifact>
- </configuration>
- </execution>
- </executions>
- </plugin>
-
-== Plugin parameter
-
-The plug-in has only one parameter.
-The `deployProjectArtifact` parameter enables or disables the current artifact deployment.
-If the current project contains tests, the plug-in can deploy the built artifact (as illustrated in this pom).
-Otherwise, the current project artifact is not deployed.
-This can be useful if the project just depends on other test bundles and sets the test configuration (as this pom).
-
-=== Configuring the set of bundles to deploy
-
-There is two different ways to configure the plug-in to deploy other bundles.
-If the bundle to deploy is a maven artifact, just add this artifact as a maven project dependency.
-Here is an example:
-
- <dependency>
- <artifactid>tests.manipulation.metadata</artifactid>
- <groupid>ipojo.tests</groupid>
- <version>1.1.0-SNAPSHOT</version>
- </dependency>
-
-If your bundle is not a maven artifact, you can configure the plugin with the bundle URL (from where the bundle will be deployed)
-
- <configuration>
- <deployprojectartifact>true</deployprojectartifact>
- <bundles>
- <param>file:/Users/clement/bundles/test-metadata.jar</param>
- </bundles>
- </configuration>
-
-Set bundles are installed and started.
-You can depend on bundle that does not contain test as well as bundle containing tests.
-
-=== Configuring Felix
-
-It is also possible to set Felix properties in the configuration:
-
- <configuration>
- <configuration>
- <org.osgi.http.port>8083</org.osgi.http.port>
- </configuration>
- </configuration>
-
-=== Showing/hiding test trace
-
-The plugin collects System.out, System.err and logged messages to write them in the test report.
-Moreover, the plugin allows hiding traces when tests are executed.
-To achieve this just add the `hideOutputs` parameter.
-
- <configuration>
- <hideOutputs>true</hideOutputs>
- </configuration>
-
-=== Disabling/Enabling the Log Service
-
-The plugin exposed a LogService in the OSGi framework to collects logged messaged.
-This service enabled by default.
-You can diable it by launching the plugin with the `logService` property set to `false`
-
- mvn clean integration-test -DlogService=false
-
-=== Skipping integration-test
-
-Sometimes you want to skip tests :-(.
-The plugin uses the `maven.test.skip` property to skip tests such as
-
- mvn clean install -Dmaven.test.skip=true
-
-=== Ignoring failures
-
-If tests throws errors or have failures, the plugin breaks the Maven build.
-You can by-pass this behavior by ignoring errors and failures.
-This is useful during test generation.
-
- mvn clean install -Dmaven.test.failure.ignore=true
-
-== Executing the plug-in
-
-To execute test, just launch the `mvn clean integration-test` command.
-
-----
-[INFO] Scanning for projects...
-[INFO] ------------------------------------------------------------------------
-[INFO] Building iPOJO Primitive Manipulation Test Suite
-[INFO] task-segment: [integration-test]
-[INFO] ------------------------------------------------------------------------
-[INFO] [resources:resources]
-[INFO] Using default encoding to copy filtered resources.
-[INFO] [compiler:compile]
-[INFO] Nothing to compile - all classes are up to date
-[INFO] [resources:testResources]
-[INFO] Using default encoding to copy filtered resources.
-[INFO] [compiler:testCompile]
-[INFO] No sources to compile
-[INFO] [surefire:test]
-[INFO] No tests to run.
-[INFO] [bundle:bundle]
-[INFO] [ipojo:ipojo-bundle {execution: default}]
-[INFO] Start bundle manipulation
-[INFO] Metadata file : /Users/clement/Documents/workspaces/felix-trunk/ipojo/tests/manipulator/primitives/target/classes/metadata.xml
-[INFO] Input Bundle File : /Users/clement/Documents/workspaces/felix-trunk/ipojo/tests/manipulator/primitives/target/tests.manipulation.primitives-1.1.0-SNAPSHOT.jar
-[INFO] Bundle manipulation - SUCCESS
-[INFO] [junit4osgi:test {execution: default}]
-Analyzing org.apache.felix.ipojo - compile
-Analyzing org.apache.felix.ipojo.metadata - compile
-Analyzing org.osgi.core - compile
-Analyzing junit - compile
-Analyzing org.apache.felix.ipojo.junit4osgi - compile
-Analyzing tests.manipulation.metadata - test
-
--------------------------------------------------------
-T E S T S
--------------------------------------------------------
-Deploy : /Users/clement/Documents/workspaces/felix-trunk/ipojo/tests/manipulator/primitives/target/tests.manipulation.primitives-1.1.0-SNAPSHOT.jar
-Loading org.apache.felix.ipojo.test.scenarios.manipulation.ManipulationTestSuite
-Loading org.apache.felix.ipojo.test.scenarios.manipulation.ManipulationTestSuite
-Junit Extender starting ...
-Running Manipulation Metadata Test Suite
-Tests run: 16, Failures: 0, Errors: 0, Time elapsed: 0 sec
-Running Primitive Manipulation Test Suite
-Tests run: 17, Failures: 0, Errors: 0, Time elapsed: 0 sec
-
-Results :
-
-Tests run: 33, Failures: 0, Errors:0
-
-Unload test suites [class org.apache.felix.ipojo.test.scenarios.manipulation.ManipulationTestSuite]
-Unload test suites [class org.apache.felix.ipojo.test.scenarios.manipulation.ManipulationTestSuite]
-Cleaning test suites ...
-[INFO] ------------------------------------------------------------------------
-[INFO] BUILD SUCCESSFUL
-[INFO] ------------------------------------------------------------------------
-[INFO] Total time: 6 seconds
-[INFO] Finished at: Mon Nov 10 21:30:21 CET 2008
-[INFO] Final Memory: 9M/18M
-[INFO] ------------------------------------------------------------------------
-----
-
-Failures and errors are reported in the plugin output.
-
-== Generating the report web page
-
-When test are executed, the plug-in generates XML reports (int the target/junit4osgi-reports directory) using the same convention as Surefire.
-So, it is possible to configure Surefire to generate the web page with test results.
-To do this, add the following report configuration to the project executing tests:
-
- <reporting>
- <plugins>
- <plugin>
- <groupid>org.apache.maven.plugins</groupid>
- <artifactid>maven-surefire-report-plugin</artifactid>
- <version>2.4.3</version>
- <configuration>
- <showsuccess>true</showsuccess>
- </configuration>
- </plugin>
- </plugins>
- </reporting>
-
-This snippet configures the maven-surefire-report-plugin to collect results from the 'target/surefire-reports' directory.
-Then execute the plugin with the following command: {code:none} mvn org.apache.maven.plugins:maven-surefire-report-plugin:2.4.3:report
-
-----
-This command generates the web page with test results in 'target/site'. This page shows an example of page generated with this command.
-
-h2. Plug-in design
-The plug-in is quiet simple, it just starts an embedded Felix with a special activator installing and starting the junit4osgi framework and specified bundles.
-Then, before executing test, the plug-in waits for "stability". Indeed, as bundle activation can be asynchronous, the plug-in need to wait that the configuration is stable. Stability is obtained when all bundles are activated, and no new services appear or disappear on a 500 ms period. If after several second the stability cannot be reached, the plug-in stops.
-Once the stability is reached, the junit4ogsi runner service is used to execute tests. Then results are collected and reports are generated.
-
-h2. Conclusion
-This page has presented a front-end automating the execution of junit4osgi tests. Now it is possible to integrate OSGi application tests in a build process. The presented maven plugin provides following features:
- * An easy integration in a Maven-based build process
- * A good flexibility allowing reproducing production execution environments to test the application
- * Test result output is the same as surefire
- * Is able to generate Surefire-like reports
-\\
-\\
-----
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-junit4osgi/apache-felix-ipojo-junit4osgi-methods.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-junit4osgi/apache-felix-ipojo-junit4osgi-methods.adoc
deleted file mode 100644
index f9d2401..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-junit4osgi/apache-felix-ipojo-junit4osgi-methods.adoc
+++ /dev/null
@@ -1,84 +0,0 @@
-= OSGi and friends methods
-
-_Developing OSGi tests can be definitely boring.
-First, testing is generally not a very exciting experience, but imagine if you have to handle all the OSGi issues in your tests...
-Don't worry junit4osgi provides methods allowing to interact easily with OSGi!_
-
-== OSGi methods
-
-junit4osgi test case extends the `OSGiTestCase` class.
-This class provides useful methods allowing to find services, get them, get the `PackageAdmin` service...
-The description of these methods can be found afterward.
-
-The most part of the methods are available statically and non-statically.
-Static methods require a `Bundle`.
-Non static methods use the current bundle context, and track get services to release them when the test is done.
-So, we advise you to use the non-static methods.
-Static methods just allow you to check that a specific bundle can access to services / resources.
-
-=== Service interaction
-
-* `boolean isServiceAvailable(String svc)` : returns `true` if the service `svc` is available.
-* `boolean isServiceAvailableByPID(String itf, String pid)` : return `true` if the service `svc` is available and exposed with `pid` as `service.pid`.
-* `ServiceReference getServiceReference(String itf)`: returns a service reference exposing the `itf` service specification, or `null` if not available.
-* `ServiceReference getServiceReference(String itf, String filter)`: returns a service reference matching with the <service interface, filter> request, or `null` is not available.
-* `ServiceReference getServiceReferenceByPID(String itf, String pid)`: returns a service reference exposing the service `itf` and exposed with a `service.pid` equals to `pid`, or `null` if not available.
-* `ServiceReference[]({{ refs..path }}) getServiceReferences(String itf, String filter)`: returns all the service references matching with the <service interface, filter> request, or an empty array is not available.
-* `Object getServiceObject(String itf, String filter)`: returns a service object matching with the <service interface, filter> request or `null` is not available.
-* `Object getServiceObject(ServiceReference ref)`: returns the service object associated with the given `service reference` or `null` if not available.
-* `Object[]({{ refs..path }}) getServiceObjects(String itf, String filter)`: gets all the service objects matching with the <service interface, filter> request or an empty array is no providers are available.
-* `void waitForService(String itf, String filter, long timeout)`: waits for a service arrival matching with the <service interface, filter> request.
-If the timeout expires, this method fails.
-
-=== Get the bundle context
-
-* `BundleContext getContext()` : gives access to the OSGiTestCase bundle context.
-
-=== Install/Start/Uninstall bundles
-
-* `Bundle installBundle(String url)`: installs a bundle from the given url.
-This method fails if the bundle cannot be installed.
-* `Bundle installBundle(String url, InputStream stream)`: installs a bundle from the given input stream.
-This methods fails if the bundle cannot be installed.
-* `Bundle installAndStart(String url)`: installs a bundle from the given url and starts it.
-This methods fails if the bundle cannot be installed and started correctly.
-* `Bundle installAndStart(String url, InputStream stream)`: installs a bundle from the given input stream and starts it.
-This methods fails if the bundle cannot be installed and started correctly.
-* `Bundle getBundle(long bundleId)`: gets an installed bundle by its bundle id, or `null` if not found.
-* `Bundle getBundle(String name)`: gets an installed bundle by its symbolic name.
-Fails if not found.
-
-=== PackageAdmin
-
-* `PackageAdmin getPackageAdmin()`: gives access to the `Package Admin` service exposed by the framework.
-* `refresh()`: refresh package wires.
-
-== Extensibility: Helper objects
-
-junit4osgi provides an extensibility mechanism to reduce the pain of testing.
-So, if you're interacting with specific services or environment, you can use `Helper` objects.
-Those object have to be created in the `setUp` method and `disposed` in the `tearDown` method.
-
-So, for example, if you write iPOJO tests, you can use the iPOJO helper providing a lot of utility functions simplifying the development of tests.
-{code:java} public class MyTest extends OSGiTestCase { ComponentInstance fooProvider1, fooProvider2;
-
-----
-IPOJOHelper helper; // Helper object
-
-public void setUp() {
- helper = new IPOJOHelper(this); // Create the object.
-String type2 = "PS-FooProviderType";
-
-fooProvider1 = helper.createComponentInstance(type2, p3);
- fooProvider2 = helper.createComponentInstance(type2, "FooProvider-4");
-}
-
-public void tearDown() {
-helper.dispose(); // Dispose it, instances will be disposed too.
-}
-
-
-You can also implements your own helper (for specific purpose) by just implementing the {{Helper}} interface.
-\\
-\\
-----
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-junit4osgi/apache-felix-ipojo-junit4osgi-tutorial.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-junit4osgi/apache-felix-ipojo-junit4osgi-tutorial.adoc
deleted file mode 100644
index 19af386..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-junit4osgi/apache-felix-ipojo-junit4osgi-tutorial.adoc
+++ /dev/null
@@ -1,345 +0,0 @@
-= junit4osgi quick start
-
-_This page describes how using the junit4osgi framework.
-With the archive tutorial, a pre-configured version of Felix (with the test framework already installed) is also provided._
-
-== Getting JUnit4OSGi
-
-[cols=2*]
-|===
-| The JUnit4OSGi framework is available from the http://felix.apache.org/site/downloads.cgi[Felix downloads].
-Source code is also available in the iPOJO sub-project ([sources
-| Download]).
-The JUnit4OSGi framework and the different launchers are built when you compile Felix.
-|===
-
-== How to run test?
-
-Firs of all to execute test you must deploy in your OSGi container:
-
-. Your tests
-. The junit4osgi runtime (executing tests)
-. A runner launching tests
-
-Several runner are available:
-
-* You can use the JUnit4OSGi immediate-runner, which run tests contained in all the test-bundles.
-The results are displayed in the framework console output.
-* The JUnit4OSGi Felix Command (available only for the Apache Felix OSGi framework), allows you to run tests contained in a specific bundle.
-Test results are also displayed in the framework console output.
-The syntax of the command is very simple : ** To run tests contained in the bundle with the given id :``+{noformat}junit <bundle id>{noformat+``} ** To run tests contained in all the test-bundles installed in the framework :``junit all``
-* The JUnit4OSGi Swing GUI lets you select the test cases and test suites to execute and shows you graphically the result of the tests.
-You can double-click on a test case result to show its details.
-
-!http://felix.apache.org/site/apache-felix-ipojo-junit4osgi.data/screenshot-junit4ogsi-swing-runner.PNG!
-
-== TestCase, TestSuite
-
-A test case is an environment (made of conditions and variables) under which a tester will check that a requirement is satisfied.
-For JUnit, test cases are classes that define several test methods ; each test method tests an aspect of the targeted requirement.
-Test cases are often collected into test suites.
-A test suite aggregates several test cases (and even other test suites), including the notion of test hierarchy.
-Tests can be organized according to the different requirements they try to validate.
-The skeleton of a JUnit `TestCase` and `TestSuite` is shown just above :
-
-----
-/**
- * The skeleton of a JUnit test case
- */
-public class MyTestCase extends junit.framework.TestCase {
- ...
-
- public void setUp() {
- // Performs actions BEFORE running any test case.
- }
-
- public void testSomething() throws AnyException {
- // A test method
- ...
- assertTrue(myTest);
- assertEquals(myValue, expectedValue);
- ...
- }
-
- public void testAnotherThing() {
- // Another test method
- ...
- }
-
-
- public void tearDown() {
- // Performs actions AFTER running all test cases.
- }
-}
-
-
-
-/**
- * The skeleton of a JUnit test suite
- */
-public class MyTestSuite extends junit.framework.TestSuite {
- /**
- * The skeleton of a JUnit test suite
- */
- public static Test suite() {
- TestSuite suite = new TestSuite("The name of the test suite");
- suite.addTestSuite(MyTestCase.class);
- suite.addTestSuite(AnotherTestCase.class);
- ...
- return suite;
- }
-}
-----
-
-First, tests methods are declared in the test case.
-Their name must begin with "test", so JUnit will execute them on demand.
-The test are expressed in terms of JUnit assertions ; the `assert*()` methods causes JUnit test failure if the given assertion is false.
-The setUp() and tearDown() methods perform specific actions before and after test cases are run.
-Then, the test suite collect various test cases.
-It must implement the `suite()` method that returns the global (and organized) test suite to JUnit.
-
-== OSGiTestCase and OSGiTestSuite
-
-An OSGi test case, is a test case that runs in an OSGi context.
-`OSGiTestCase` is the class that all the OSGi test cases you write must extend.
-This class is a kind of bridge between the JUnit TestCase class and the OSGi environment.
-The only thing the `OSGiTestCase` class adds is the access to the bundle context of the bundle containing tests, and some utility methods, giving an easy access to other bundles and services registered in the OSGi framework.
-
-The structure of an `OSGiTestCase` is exactly the same as a classic JUnit `TestCase` :
-
-----
- /**
- * The structure of an OSGiTestCase
- */
- public class MyOSGiTestCase extends OSGiTestCase {
- public void setUp() {...}
- public void testSomething() {
- // You can access here the bundle context through
- // the 'getContext()' method
- getContext().getServiceReference(...);
-
- ...
- }
- public void testAnotherThing() {...}
- ...
- public void tearDown() {...}
- }
-----
-
-By extension, OSGi test suites are collections of OSGi test cases.
-But you can also add classic JUnit test cases inside your `OSGiTestSuite`.
-The skeleton of an OSGiTestSuite is globally the same as a TestSuite, except the fact that a reference to the bundle context is passed :
-
- public class MyOSGiTestSuite {
- /**
- * This method returns the suite of tests to run.
- */
- public static Test suite(BundleContext bc) {
- OSGiTestSuite suite = new OSGiTestSuite("My OSGi test suite", bc);
- suite.addTestSuite(MyFirstTest.class);
- suite.addTestSuite(MySecondTest.class);
- ...
- // Here, we add a sub test suite in this test suite.
- suite.addTest(AnotherTestSuite.suite(bc));
- ...
- return suite;
- }
- }
-
-== How to declare test suites
-
-This section explains how to declare your test suites in order to expose them to the JUnit4OSGi bundle.
-
-The written OSGi test suites must be declared by the bundle containing them.
-To do so, you define add the Test-Suite property in your bundle's header.
-The following snippets show you how to configure your bundle generation tool to add this property in the header.
-You can even declare test cases in it.
-The Junit4OSGi bundle will detect such an header in installed bundle (using the extender pattern) and execute contained tests on demand.
-
-With the maven-bundle-plugin, add the following lines in your project's pom :
-
- <plugin>
- <groupId>org.apache.felix</groupId>
- <artifactId>maven-bundle-plugin</artifactId>
- ...
- <extensions>true</extensions>
- <configuration>
- <instructions>
- ...
- <!-- Declare here the test cases and test suites of your bundle -->
- <Test-Suite>
- a.package.MyFirstTestSuite,
- yet.another.package.MySingleTestCase
- ...
- </Test-Suite>
- </instructions>
- </configuration>
- </plugin>
-
-With the aQute Bnd Ant task, add the following lines in your project bnd file:
-
- Test-Suite: a.package.MyFirstTestSuite, yet.another.package.MySingleTestCase, ...
-
-== Quick examples
-
-The following examples show you how to perform unitary tests on your OSGi platform.
-The first example recovers the example given in the JUnit Cookbook, "bundlizes" it so tests can be run in an OSGi environment.
-None of the JUnit4OSGi specific features is used, but it shows how to adapt classic JUnit tests.
-The second example is more OSGi-oriented, and shows how a unitary test can access to the framework via its bundle context.
-
-These examples can be downloaded http://people.apache.org/~clement/ipojo/tutorials/junit4osgi/junit4osgi-tutorial.zip[here].
-
-=== Bundles to deploy to use junit4osgi
-
-If you don't use the archive, you can deploy the junit4osgi framework manually.
-Here is the list of the bundles to deploy and start:
-
-* org.apache.felix.ipojo-1.6.0.jar: iPOJO Core bundle
-* org.apache.felix.ipojo.handler.extender-1.6.0.jar: iPOJO Extender pattern handler
-* org.apache.felix.ipojo.junit4osgi-1.1.0-SNAPSHOT.jar: the JUnit4OSGi framework
-* org.apache.felix.ipojo.junit4osgi.felix-command-1.1.0-SNAPSHOT.jar: the command line junit4osgi runner
-
-=== The remixed JUnit example
-
-This example is a simple conversion of a classic JUnit example derived from the JUnit Cookbook.
-The test case and the test suite are shown to remind you JUnit principles.
-
-----
-package junit.example;
-import junit.framework.TestCase;
-import junit.money.Money;
-
-public class SimpleTestCase extends TestCase {
- private Money f12CHF;
- private Money f14CHF;
- public void setUp() {
- f12CHF= new Money(12, "CHF");
- f14CHF= new Money(14, "CHF");
- }
- public void testEquals() {
- assertTrue(!f12CHF.equals(null));
- assertEquals(f12CHF, f12CHF);
- assertEquals(f12CHF, new Money(12, "CHF"));
- assertTrue(!f12CHF.equals(f14CHF));
- }
- public void testSimpleAdd() {
- Money expected= new Money(26, "CHF");
- Money result= f12CHF.add(f14CHF);
- assertTrue(expected.equals(result));
- }
-}
-
-
-
-package junit.example;
-import junit.framework.Test;
-import junit.framework.TestSuite;
-public class SimpleTestSuite {
- public static Test suite() {
- TestSuite suite = new TestSuite("Money Simple Test Suite");
- suite.addTestSuite(SimpleTestCase.class);
- return suite;
- }
-}
-----
-
-The following bnd file declares the test suite in the target bundle's header :
-
- Private-Package: junit.money, junit.example
- Test-Suite: junit.example.SimpleTestSuite
-
-Once built, the bundle must be deployed in the provided Felix framework, and tests can be performed using the `'junit'` command :
-
- -> ps
- START LEVEL 1
- ID State Level Name
- ...
- [ 12] [Active ] [ 1] Junit-Example (0)
- ...
- -> junit 12
- Executing [Money Simple Test Suite]
- ..
- Time: 0
- OK (2 tests)
- ->
-
-As you can see above, all tests have been correctly executed !
-
-== An OSGi-based JUnit example
-
-This example shows you how to interact with the OSGi framework within your tests.
-The test bundle provide a service (HelloService) and tests its work normally.
-To get the service reference of the HelloService, it uses the bundle context field of the OSGiTestCase class (named `'context'`) and interacts with it like any other OSGi bundle does.
-
-----
-package junit.example;
-
-import junit.service.hello.HelloService;
-
-import org.apache.felix.ipojo.junit4osgi.OSGiTestCase;
-import org.osgi.framework.ServiceReference;
-
-public class SimpleTestCase extends OSGiTestCase {
-
- public void testHelloAvailability() {
- ServiceReference ref = getServiceReference(HelloService.class.getName());
- assertNotNull("Assert Availability", ref);
- }
-
- public void testHelloAvailability2() {
- ServiceReference ref = getServiceReference(HelloService.class.getName(), null);
- assertNotNull("Assert Availability", ref);
- }
-
- public void testHelloMessage() {
- ServiceReference ref = getServiceReference(HelloService.class.getName());
- assertNotNull("Assert Availability", ref);
- HelloService hs = (HelloService) getContext().getService(ref);
- String message = hs.getHelloMessage();
- assertNotNull("Check the message existence", message);
- assertEquals("Check the message", "hello", message);
- // Don't need to unget references, they are unget by junit4osgi
- }
-
- public void testHelloMessage2() {
- assertTrue("Check availability of the service",
- isServiceAvailable(HelloService.class.getName()));
- HelloService hs = (HelloService) getServiceObject(HelloService.class.getName(), null);
- String message = hs.getHelloMessage();
- assertNotNull("Check the message existence", message);
- assertEquals("Check the message", "hello", message);
- }
-}
-----
-
-The performed tests give out the following results :
-
- -> ps
- START LEVEL 1
- ID State Level Name
- ...
- [ 17] [Active ] [ 1] Junit-OSGi-Example (0)
- ...
- -> services 17
- Junit-OSGi-Example (17) provides:
- ---------------------------------
- objectClass = junit.service.hello.HelloService
- service.id = 36
- -> junit 17
- Executing [Hello Service Test Suite]
- ..
- Time: 0,015
- OK (4 tests)
- ->
-
-== Simple right?
-
-[cols=2*]
-|===
-| So now you know everything required to run test inside OSGi.
-You can start developing your own test.
-To help you a little bit, junit4osgi provides xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-junit4osgi/apache-felix-ipojo-junit4osgi-methods.adoc[utilities methods] greatly reducing the amount of code to write in your tests.
-Moreover, if you're a Maven user, the [maven-junit4osgi-plugin
-| apache-felix-ipojo-junit4osgi-maven] is made for you.
-It just runs your test directly during the maven build process.
-|===
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-keypoints.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-keypoints.adoc
deleted file mode 100644
index 9f75804..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-keypoints.adoc
+++ /dev/null
@@ -1,70 +0,0 @@
-= iPOJO Key Points
-
-_iPOJO is a service-oriented component model.
-What_'_s made iPOJO different?
-Just read this page._
-
-== Used
-
-iPOJO is used a several and really heterogeneous domain.
-iPOJO is today used in mobile phone, in home gateway as well as in JEE servers!
-Module Fusion also proposes to use iPOJO for enterprise applications.
-
-== Philosophy
-
-iPOJO aims to be simple.
-The proposed development model is definitely simple.
-Do worry about all the obscured technical service and bindings details, just focus on your code.
-iPOJO manages the everything for you.
-Moreover, it was designed for the OSGi environment.
-It places the service concept as a top-level concept providing a better reusability, allowing implementation substitution and managing the dynamism.
-
-== Supported
-
-iPOJO is now supported by different companies and research center such as akquinet, Grenoble University, Bull...
-
-== Easy to use
-
-Based on the POJO concept and thanks to its different injection mechanisms, iPOJO allows you to reuse he high majority of your existing code!
-The business code does not depend on the OSGi environment or on specific technical services.
-The container manages everything for you.
-
-with iPOJO you're free!
-To describe your component, you have the choice among XML, Annotations or an API.
-
-== Reliable and Efficient
-
-iPOJO relies on:
-
-* An OSGi R4.1 framework
-* A J2ME Foundation 1.1 java virtual machine
-
-So, you can use iPOJO on Apache Felix, Eclipse Equinox or any OSGi implementation compliant with the OSGi R4.1 specification.
-Moreover, iPOJO just relies on J2ME Foundation 1.1 profile.
-So, you can easily embed it...
-However, this does not limit iPOJO in term of performance.
-iPOJO is one of the most efficient component models for OSGi.
-
-== Embeddable
-
-As told in the previous section, iPOJO does not required advanced Java Virtual Machine.
-Moreover its footprint is quite small.
-iPOJO Core size is only 200Kb !
-No more is required to use iPOJO...
-
-== Adaptable
-
-iPOJO provides a very simple extensibility mechanism.
-So, you can extend iPOJO for your own requirement.
-Just look to the list of available handler (i.e.
-extension).
-Almost everything is possible...
-
-== Going further
-
-* Want to go further;
-read the xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-why-choose-ipojo.adoc[Why choose iPOJO page].
-* Want to try;
-look at the xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-in-10-minutes.adoc[iPOJO in 10 minutes tutorial]
-* Want more information;
-feel free to send an email on link:mailto:users@felix.apache.org[users@felix.apache.org]
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-successstories.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-successstories.adoc
deleted file mode 100644
index 3df1c81..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-successstories.adoc
+++ /dev/null
@@ -1,69 +0,0 @@
-= iPOJO Success Stories
-
-_On this page, you will find comments from industrial users of iPOJO.
-They come from different domains such as home gateways, mobile phones, or enterprise applications._
-
-[#schneider]
-[quote,'Sylvain Marie, Software Architect, Schneider Electric']
-____
-Over 90% of processors are now used for embedded applications.
-At Schneider Electric we believe that java is a fantastic opportunity to develop some of our applications faster and better.
-OSGi is an excellent way to ensure that developed java software comes with built-in best practices such as reusability, high cohesion, loose coupling, high flexibility and dynamism.But we definitely don't want our anticipation teams to spend more time on OSGi mechanisms than on Energy Management, our core business!
-iPOJO helps us to develop quickly, by making developing modules as simple as writing plain old java.
-We also use it for our open source OSGi DPWS Base Driver ('SOA for devices' forge, on http://forge.soa4d.org/).
-And it's not just about us: partners of the SOA4D forge are using it, too.
-____
-
-
-'''
-
-[#ugasp]
-[quote,'Romain Pellerin, Ubidreams CEO']
-____
-Ubiquitous Multi-player games are one of next trends of mobile games.
-This type of games offers new experience: users interact with the real world and with the virtual world at the same time!
-So, player actions such as moves, interactions with smart objects or others players impact the virtual part of the game.
-The state of the virtual games also impacts the possibilities in the physical part of the games.
-Creating this kind of games requires managing several types of technologies such as embedded devices (mobile phones, PDA, sensors\...), smart objects (RFID, environmental sensors\...) and network connectivity (GSM, Edge, 3G, Wifi, Bluetooth\...).
-uGasp (Ubiquitous Gaming Services Platform) is a middleware used to execute ubiquitous multi-player games.
-It provides an abstraction layer hiding the inherent complexity of such games.
-uGasp is a major evolution of the Gasp framework using a monolithic stack not suitable to embedded devices.
-To tackle this issue, we adopted a dynamic, modular, extensible and configurable architecture.
-But in order to speed up the development, uGasp is based on a service -oriented component model offering all the features "for free" and simplifying the development of dynamic applications.
-uGasp is based on Apache Felix and iPOJO.
-We chose iPOJO for several reasons:
-
-* iPOJO drastically simplifies the development of OSGi-based applications.
-The intuitive XML description is really simple to use even for a novice developer.
-* iPOJO allows reusing a lot of object-oriented code thanks to the field injection.
-So, migrating GASP to uGASP takes only three weeks!
-* The factory principles offered by iPOJO allows creating several games instance at the same time.
-* Finally, the isolation characteristic was a critical requirement in the uGasp middleware.
-Moreover, for the developer point of view, this is completely hidden.
-
-To get more info about uGasp, visit our http://gasp.objectweb.org/ubiquitous-osgi-middleware.html[web site] or contact http://www.ubidreams.com[Ubidreams].
-____
-
-
-'''
-
-[#jonas]
-[quote,'Guillaume Sauthier, JOnAS Application Server Developer']
-____
-JOnAS is a Java EE server developed inside the OW2 consortium.
-It embraces the new trend of modular and dynamic application servers and aims at implementing the entire Java EE specification by re-using third-part components.
-JOnAS also focuses on providing a great flexibility for the developer, for the administrator and for clustering.
-To enable this flexibility and dynamism in the application server components' integration, the JOnAS team chose to rely on an OSGi runtime.
-However, it quickly appeared that any manual management of the dynamism would be too expensive: not only very few programmers understand the complexity of the dynamism, but also manual maintaining is extremely difficult and error-prone.
-That's why JOnAS uses a service-oriented component model.
-We first chose iPOJO because this technology sounded really promising.
-Moreover, iPOJO is able to evolve against new requirements, thanks to the handler-based extensibility model it promotes.
-In the JOnAS application server all the technical services are implemented by iPOJO components.
-Thanks to this framework, they are pluggable and upgradeable on-demand.
-As iPOJO reduces drastically the impact on the code, we have reused the high majority of our code and the migration from the former JOnAS to this one has been surprisingly quick.
-The JOnAS team is very happy with iPOJO, and will go on using, promoting and improving it.
-If you want more info on JOnAS visit our http://wiki.jonas.objectweb.org/xwiki/bin/view/Main/WebHome[website].
-____
-
-*Are you also using iPOJO ?* + You are using iPOJO, and you want to be listed there to tell how you are using iPOJO.
-Feel free to send us link:mailto:clement@apache.org[a mail] with your story.
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-supportedosgi.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-supportedosgi.adoc
deleted file mode 100644
index ec73332..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-supportedosgi.adoc
+++ /dev/null
@@ -1,53 +0,0 @@
-= Supported OSGi Implementations
-
-_Despite iPOJO is an Apache Felix subproject, it relies only on *OSGi R4_ features.
-So, it is possible to use it on others OSGi implementations.*
-
-|===
-| Features | Apache Felix | Eclipse Equinox | Knowplerfish
-
-| Core features
-| __
-| __
-| __
-
-| Composites features
-| __
-| __
-| __
-
-| Configuration Admin
-| __
-| __
-| __
-
-| Temporal service dependencies
-| __
-| __
-| __
-
-| Whiteboard and Extender pattern handler
-| __
-| __
-| __
-
-| Event admin handler
-| __
-| __
-| __
-
-| JMX handler
-| __
-| __
-| __
-|===
-
-Feel free to send a mail on the Felix mailing list, if an implementation is not listed here.
-
-'''
-
-ALERT: Old version of Knopflerfish does not allow getting a service during its unregistration.
-To enable this feature, launch the Knopflerfish framework with the `-Dorg.knopflerfish.servicereference.valid.during.unregistering=true` property.
-You can add this property in the `props.xargs` file.
-
-Recent version of KF does no more require this property.
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-supportedvms.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-supportedvms.adoc
deleted file mode 100644
index 26fbf7f..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-supportedvms.adoc
+++ /dev/null
@@ -1,74 +0,0 @@
-= Supported Java Virtual Machines
-
-|===
-| Features | Sun JVM (1.4, 5, 6) | Oracle JVM and OpenJDK | Harmony | JamVM | Mika | JRockit | Dalvik (Android)
-
-| Core features
-| __
-| __
-| __
-| __
-| __
-| __
-| __
-
-| Composites features
-| __
-| __
-| __
-| __
-| __
-| __
-| __
-
-| Configuration Admin
-| __
-| __
-| __
-| __
-| __
-| __
-| __
-
-| Temporal service dependencies
-| __
-| __
-| __
-| __
-| __
-| __
-| __
-
-| Whiteboard and Extender pattern handler
-| __
-| __
-| __
-| __
-| __
-| __
-| __
-
-| Event admin handler
-| __
-| __
-| __
-| __
-| __
-| __
-| __
-|===
-
-Feel free to send a mail on the Felix mailing list if a JVM is not listed here.
-
-'''
-
-INFO: *Note about Android* iPOJO is supported on Android except for two features:
-
-* Nullable are not supported (Default-Implementations are supported)
-* Composites cannot provide services (but they can export services)
-
-These two limitations comes from the Android VM (Dalvik) that does not support the definition of new classes at runtime (i.e.
-dynamically generated classes).
-
-INFO: *Note about Android* iPOJO 1.6+ uses smart proxy by default.
-On Android this is not supported, however, you can disable the proxies with: `proxy="false"` in the service requirements.
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-testing-components.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-testing-components.adoc
deleted file mode 100644
index 1403c9f..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-testing-components.adoc
+++ /dev/null
@@ -1,104 +0,0 @@
-= How to test iPOJO Components
-
-Testing components is a required step in the application development process.
-This page explains strategies to test iPOJO-based components and applications.
-
-== Introduction
-
-Basically, we can distinguish 2 types of tests:
-
-* Unitary tests
-* Integration tests
-
-[cols=2*]
-|===
-| Unitary tests are famous and were popularized with the proliferation of frameworks like http://junit.org[Junit] and [TestNG
-| http://testng.org/doc/].
-These tests check the behavior of classes.
-More specially, these tests check the method results according to different parameter values.
-These test are executed outside the execution environment, can use mock object (link) to replace/simulate missing dependencies...
-|===
-
-Integration tests focus on the execution of the application inside the execution environment.
-It checks the global behavior of a service or an application.
-In the case of iPOJO, those tests are executed on OSGi.
-Some dependencies can be also replaced by mock services/objects.
-
-== Executing unitary tests on iPOJO components
-
-Unitary tests allow checking the internal behavior of an iPOJO component.
-Those tests ignore the injected dependencies and focus only on the business code of the component.
-
-To test components, you can use Junit.
-A special constructor setting fields can do the dependency injection.
-These tests are executed before the bundlelization.
-
-Let's imagine a maven project.
-Unitary tests are placed in the src/test/java folder.
-You can use mock object as illustrated in the example.
-When you launch the `mvn clean install` command, maven compiles your classes and executes the tests.
-If the tests are executed successfully, the build process continues and creates the bundle as follows:
-
-----
-[INFO] Scanning for projects...
-[INFO] ------------------------------------------------------------------------
-[INFO] Building Dummy Component
-[INFO] task-segment: [clean, install]
-[INFO] ------------------------------------------------------------------------
-[INFO] [clean:clean]
-[INFO] Deleting directory /Users/clement/Documents/workspaces/ipojo-dev/UnitaryTest/target
-[INFO] [resources:resources]
-[INFO] Using default encoding to copy filtered resources.
-[INFO] [compiler:compile]
-[INFO] Compiling 1 source file to /Users/clement/Documents/
- workspaces/ipojo-dev/UnitaryTest/target/classes
-[INFO] [resources:testResources]
-[INFO] Using default encoding to copy filtered resources.
-[INFO] [compiler:testCompile]
-[INFO] Compiling 1 source file to /Users/clement/Documents/
- workspaces/ipojo-dev/UnitaryTest/target/test-classes
-[INFO] [surefire:test]
-[INFO] Surefire report directory: /Users/clement/Documents/
- workspaces/ipojo-dev/UnitaryTest/target/surefire-reports
-
--------------------------------------------------------
- T E S T S
--------------------------------------------------------
-Running org.apache.felix.ipojo.ut.component.test.MyTestCase
-Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.076 sec
-
-Results :
-
-Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
-
-[INFO] [bundle:bundle]
-[INFO] [ipojo:ipojo-bundle {execution: default}]
-[INFO] Start bundle manipulation
-[INFO] Metadata file : /Users/clement/Documents/
- workspaces/ipojo-dev/UnitaryTest/target/classes/metadata.xml
-[INFO] Input Bundle File : /Users/clement/Documents/workspaces/
- ipojo-dev/UnitaryTest/target/org.apache.felix.ipojo.test.dummy.component-1.1.0-SNAPSHOT.jar
-[INFO] Bundle manipulation - SUCCESS
-[INFO] [install:install]
-[INFO] Installing /Users/clement/Documents/workspaces/
- ipojo-dev/UnitaryTest/target/org.apache.felix.ipojo.test.dummy.component-1.1.0-SNAPSHOT.jar
- to /Users/clement/.m2/repository/ipojo/tests/org.apache.felix.ipojo.test.dummy.component/1.1.0-SNAPSHOT
- /org.apache.felix.ipojo.test.dummy.component-1.1.0-SNAPSHOT.jar
-[INFO] [bundle:install]
-[INFO] Parsing file:/Users/clement/.m2/repository/repository.xml
-[INFO] Installing ipojo/tests/org.apache.felix.ipojo.test.dummy.component/
- 1.1.0-SNAPSHOT/org.apache.felix.ipojo.test.dummy.component-1.1.0-SNAPSHOT.jar
-[INFO] Writing OBR metadata
-[INFO] ------------------------------------------------------------------------
-[INFO] BUILD SUCCESSFUL
-[INFO] ------------------------------------------------------------------------
-[INFO] Total time: 6 seconds
-[INFO] Finished at: Tue Oct 21 14:03:03 CEST 2008
-[INFO] Final Memory: 11M/25M
-[INFO] ------------------------------------------------------------------------
-----
-
-== Executing integration tests
-
-We recommend to use Pax Exam 3 to test iPOJO components.
-More details about pax exam 3 are available https://ops4j1.jira.com/wiki/display/PAXEXAM3/Pax+Exam[here].
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/apache-felix-ipojo-online-manipulator.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/apache-felix-ipojo-online-manipulator.adoc
deleted file mode 100644
index bf56c76..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/apache-felix-ipojo-online-manipulator.adoc
+++ /dev/null
@@ -1,61 +0,0 @@
-= Apache Felix iPOJO Online Manipulator
-
-_iPOJO generally requires an additional packaging step to prepare the bundle to be managed by iPOJO.
-Despite this step doesn't change the class semantic, it can be a little annoying.
-The online manipulator avoids this offline step!_
-
-
-
-== Features
-
-iPOJO is based on a bytecode manipulation.
-This manipulate is _safe_ and does not change the class semantics.
-Classes can still used after the manipulation without iPOJO.
-However this manipulation is required for iPOJO management.
-Generally, this manipulation occurs offline during the packaging time.
-The online manipulator allows to do this manipulation at install time.
-
-The online manipulator:
-
-* avoids offline manipulation
-* supports annotations
-* supports XSD schema
-
-This is quite useful if you don't want to add an extra packaging step, and provides the same capabilities as the "regular" way.
-
-== Usage
-
-The online-manipulator is in fact an URL Handler.
-So, it will process every bundle using a special URL prefix.
-To use it, just follows the below instructions:
-
-=== Install and Start the URL Handler
-
-Download and install the iPOJO online manipulator.
-You can download it from the http://felix.apache.org/downloads.cgi[Felix download page]
-
-=== Install a bundle using the _ipojo:_ URL prefix
-
-Using the handler is quite easy.
-When you want to deploy a non-manipulated iPOJO bundle just use an url like
-
-[source,sh]
- install ipojo:file:/.../bundle.jar
-
-The complete URL syntax is
-
-[source,sh]
- install ipojo:bundle_url[!metadata_url]
-
-When using the `ipojo:` prefix, the OSGi platform delegates the loading to the url handler manipulating the bundle before its installation.
-This manipulation is exactly the same as the offline manipulation.
-
-== Dealing with metadata
-
-If the installed bundle contains a `metadata.xml` file either in its root or in the `META-INF` directory, the online manipulator will use it.
-However, you can also provide an external `metadata.xml` file by indicating the url of the file like in
-
-[source,sh]
- install ipojo:bundle_url!metadata_url
-
-If you provide such url, it will override the contained `metadata.xml` file.
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-ant-task.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-ant-task.adoc
deleted file mode 100644
index 1924e3e..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-ant-task.adoc
+++ /dev/null
@@ -1,129 +0,0 @@
-= iPOJO Ant Task
-
-_iPOJO Ant Task allows automating the iPOJO manipulation process within an Ant build process.
-This page explains how to use the iPOJO Ant Task and how to combine them with the BND Tasks._
-
-
-
-== Downloading the iPOJO Ant Task
-
-The iPOJO Ant Task can ben downloaded from http://felix.apache.org/downloads.cgi[here].
-
-== How to use the Ant Task
-
-The iPOJO Ant task take an input bundle and a metadata file and create the final (i.e.
-manipulated) bundle.
-To use the task declare a target in your build.xml as:
-[source,xml]
- <target name="main">
- <!-- Change the path to point on the iPOJO Ant task jar-->
- <taskdef name="ipojo"
- classname="org.apache.felix.ipojo.task.IPojoTask"
- classpath="org.apache.felix.ipojo.ant-{{ipojo.release}}.jar"/>
- <ipojo
- input="foo.jar"
- metadata = "meta.xml"
- />
- </target>
-
-First, define the new task.
-Then simply use it.
-The input argument describe the input bundle (must exists) and the metadata argument describes the metadata file (must exist too).
-The input bundle must be a well-formed bundle.
-
-== Ant Task Arguments
-
-The iPOJO Ant Task as three different arguments:
-
-* Input: describes the input bundle.
-This argument is mandatory.
-* Output: describes the output bundle.
-This argument is optional.
-If not present, the output file will be input file.
-* Metadata: describes the metadata file.
-This argument is optional.
-By default, it tries with a metadata.xml file (in the same directory as the build.xml file).
-If the default file is not present, it tries to use only iPOJO annotations.
-* IgnoreAnnotations: if set to `true`, the manipulator skips annotations processing (can reduce significantly the processing time on huge bundle).
-* IgnoreEmbeddedSchemas: if set to `true`, the manipulator doesn't use embedded XML-Schemas
-
-== Combining the iPOJO Ant Task and BND
-
-The iPOJO Ant Task requires an input bundle.
-BND is a tools simplifying bundle creation.
-So, it is possible to combine the two tools to create your bundle automatically.
-The following build.xml shows you an example of combination.
-[source,xml]
- <project default="main" basedir=".">
- <target name="bnd">
- <!-- Change to use the latest BND version -->
- <taskdef resource="aQute/bnd/ant/taskdef.properties"
- classpath="bnd-0.0.178.jar"/>
- <bnd
- classpath="src"
- eclipse="true"
- failok="false"
- exceptions="true"
- files="foo.bnd"/>
- </target>
- <target name="main" depends="bnd">
- <echo message="Call main"/>
- <!-- Change the path to point on the iPOJO Ant task jar -->
- <taskdef name="ipojo"
- classname="org.apache.felix.ipojo.task.IPojoTask"
- classpath="org.apache.felix.ipojo.ant-{{ipojo.release}}.jar" />
- <!-- the input attribute must fit the .bnd file name -->
- <ipojo
- input="foo.jar"
- metadata = "meta.xml"
- />
- </target>
- </project>
-
-The first target creates the bundle with BND.
-More details on the BND Ant Task are available here.
-To combine the BND output and the iPOJO input, the iPOJO input need to be the same as the BND file but with the ".jar" extension.
-For instance, the BND file is foo.bnd, so the input jar must be foo.jar.
-To be sure that the BND bundle is already created, you can add the "_depends_" clause in the target using the iPOJO task to the target creating the bundle.
-
-However, it is possible to create only one target doing the two operations as:
-[source,xml]
- <target name="main">
- <!-- Change to use the latest BND version -->
- <taskdef
- resource="aQute/bnd/ant/taskdef.properties"
- classpath="bnd-0.0.178.jar"/>
- <!-- Change the path to point on the iPOJO Ant task jar -->
- <taskdef name="ipojo"
- classname="org.apache.felix.ipojo.task.IPojoTask"
- classpath="org.apache.felix.ipojo.ant-{{ipojo.release}}.jar"/>
- <bnd
- classpath="src"
- eclipse="true"
- failok="false"
- exceptions="true"
- files="foo.bnd"/>
- <ipojo
- input="foo.jar"
- metadata = "meta.xml"/>
- </target>
-
-== Directory manipulation
-
-The manipulator can take a directory in input.
-In this case, classes from this folder is manipulated.
-You can also set the manifest file location too.
-Here in an example of configuration using this mode:
-[source,xml]
- <target name="manipulate">
- <!-- Set the manipulated directory and manifest location -->
- <ipojo
- dir="${output..}"
- metadata="metadata.xml"
- manifest="META-INF/MANIFEST.MF"
- />
- </target>
-
-=== ALERT Manifest location
-
-If not set, the manifest is searched in the given `directory/META-INF` folder (_i.e._ `$dir/META-INF/MANIFEST.MF`).
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-arch-command.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-arch-command.adoc
deleted file mode 100644
index 1b13867..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-arch-command.adoc
+++ /dev/null
@@ -1,179 +0,0 @@
-= iPOJO architecture commands
-
-_Architecture introspection is required when the system doesn't work as expected.
-In this case, having a quick access to instances states and interconnection is a stringent requirement.
-The architecture commands allows getting these data from the Felix Shell, from the Equinox shell and Gogo._
-
-
-
-== Installation
-
-According to your shell, download the adequate bundles from http://felix.apache.org/downloads.cgi[the Felix download page]
-
-== Gogo
-
-The Gogo commands are the following:
-
-* `ipojo:instances` (or just `instances`) lists the instances and state
-* `ipojo:instance $instance_name` (or just `instance $instance_name`) displays the complete information about the specified $instance_name
-* `ipojo:factories` (or just `factories`) lists the available public factories
-* `ipojo:factory $factory_name` (or just `factory $factory_name`) displays complete information about the factory $factory_name
-* `ipojo:handlers` (or just `handlers` lists available handlers
-
-For example:
-
-[source,sh]
-----
-$ instances
-Instance ArchCommand -> valid
-Instance spell.english.EnglishDictionary-0 -> valid
-Instance spell.checker.SpellCheck-0 -> valid
-Instance spell.gui.SpellCheckerGui-0 -> valid
-
-$ instance spell.checker.SpellCheck-0
-instance component.type="spell.checker.SpellCheck" state="valid" bundle="8" name="spell.checker.SpellCheck-0"
- handler state="valid" name="org.apache.felix.ipojo.handlers.dependency.DependencyHandler"
- requires optional="false" aggregate="false" state="resolved" binding-policy="dynamic" specification="spell.services.DictionaryService"
- handler state="valid" name="org.apache.felix.ipojo.handlers.providedservice.ProvidedServiceHandler"
- provides service.id="36" state="registered" specifications="[spell.services.SpellChecker]"
- property value="spell.checker.SpellCheck" name="factory.name"
- property value="spell.checker.SpellCheck-0" name="instance.name"
- handler state="valid" name="org.apache.felix.ipojo.handlers.architecture.ArchitectureHandler"
-----
-
-== Equinox and Felix Shells
-
-On Equinox and Felix (old) shell, the command is named _arch_:
-
-* arch \=> displays instances name & state (equivalent to arch -instances)
-* arch -instance $instance__name \=> displays complete information about the instance $instance__name
-* arch -factories \=> display the list of available factories
-* arch -factory $factory__name \=> display complete information about the factory $factory__name
-* arch -handlers \=> list available handlers
-
-=== Examples
-
-[source,sh]
-----
--> arch
-Instance ArchCommand -> valid
-Instance spell.english.EnglishDictionary-0 -> valid
-Instance spell.checker.SpellCheck-0 -> valid
-Instance spell.gui.SpellCheckerGui-0 -> valid
-
--> arch -instance spell.checker.SpellCheck-0
-instance component.type="spell.checker.SpellCheck" state="valid" bundle="8" name="spell.checker.SpellCheck-0"
- handler state="valid" name="org.apache.felix.ipojo.handlers.dependency.DependencyHandler"
- requires optional="false" aggregate="false" state="resolved" binding-policy="dynamic" specification="spell.services.DictionaryService"
- handler state="valid" name="org.apache.felix.ipojo.handlers.providedservice.ProvidedServiceHandler"
- provides service.id="36" state="registered" specifications="[spell.services.SpellChecker]"
- property value="spell.checker.SpellCheck" name="factory.name"
- property value="spell.checker.SpellCheck-0" name="instance.name"
- handler state="valid" name="org.apache.felix.ipojo.handlers.architecture.ArchitectureHandler"
-----
-
-== Reading instance architecture:
-
-Instance architecture is organized as follows:
-
-* On the first line, are displayed the component type (i.e.
-factory), the instance state (`valid` or `invalid`), the bundle from which the instance is created, and the instance name.
-* Then, the information is organized handler by handler (a piece of container).
-For each handler plugged on the instance can participate to the instance architecture.
-For each handler its name (such as ` org.apache.felix.ipojo.handlers.dependency.DependencyHandler`` for iPOJO service dependencies, `` org.apache.felix.ipojo.handlers.providedservice.ProvidedServiceHandler``+ for iPOJO service providing...) and the state (either +``valid`` or ``invalid` are displayed.
-Remember that an instance is valid only and only if all plugged handlers are valid.
-* The `org.apache.felix.ipojo.handlers.dependency.DependencyHandler` provides data on service dependencies and more precisely on the state of service dependencies.
-In the previous example, the dependency on ` spell.services.DictionaryService` was resolved.
-On the following example, the same dependency is no more resolved.
-
-As an example, the following snippet dumps the architecture of an instance:
-
-[source,sh]
- instance component.type="spell.checker.SpellCheck" state="invalid" bundle="8" name="spell.checker.SpellCheck-0"
- handler state="invalid" name="org.apache.felix.ipojo.handlers.dependency.DependencyHandler"
- requires optional="false" aggregate="false" state="unresolved" binding-policy="dynamic" specification="spell.services.DictionaryService"
- handler state="valid" name="org.apache.felix.ipojo.handlers.providedservice.ProvidedServiceHandler"
- provides state="unregistered" specifications="[spell.services.SpellChecker]"
- property value="spell.checker.SpellCheck" name="factory.name"
- property value="spell.checker.SpellCheck-0" name="instance.name"
- handler state="valid" name="org.apache.felix.ipojo.handlers.architecture.ArchitectureHandler"
-
-Notes that, the instance also becomes invalid and that the provided service is unregistered.
-If the provider comes back, the dependency becomes `resolved` and the instance becomes `valid` If an instance begins to use a service, the bound providers are described in the instance architecture:
-
-[source,sh]
- instance component.type="spell.checker.SpellCheck" state="valid" bundle="8" name="spell.checker.SpellCheck-0"
- object name="spell.checker.SpellCheck@e222eb"
- handler state="valid" name="org.apache.felix.ipojo.handlers.dependency.DependencyHandler"
- requires optional="false" aggregate="false" state="resolved" binding-policy="dynamic" specification="spell.services.DictionaryService"
- uses service.id="41" instance.name="spell.english.EnglishDictionary-0"
- handler state="valid" name="org.apache.felix.ipojo.handlers.providedservice.ProvidedServiceHandler"
- provides service.id="42" state="registered" specifications="[spell.services.SpellChecker]"
- property value="spell.checker.SpellCheck" name="factory.name"
- property value="spell.checker.SpellCheck-0" name="instance.name"
- handler state="valid" name="org.apache.felix.ipojo.handlers.architecture.ArchitectureHandler"
-
-In the previous case, the dependency on ` spell.services.DictionaryService`` use the service 41 from the iPOJO instance named `` spell.english.EnglishDictionary-0`` You can also check created POJO objects (implementation class objet).
-Here, only one object was created (``spell.checker.SpellCheck@e222eb`).
-
-== List available factories
-
-You can access factory list using the `factories` gogo command or the `arch -factories` on Felix's shell.
-For every available (public) factories,the name and the state are displayed.
-A factory is valid if and only if all required handlers are available.
-
-[source,sh]
- -> arch -factories
- Factory spell.checker.SpellCheck (VALID)
- Factory spell.gui.SpellCheckerGui (VALID)
- Factory spell.english.EnglishDictionary (VALID)
- -> arch -factory spell.english.EnglishDictionary
- factory implementation-class="spell.english.EnglishDictionary" state="valid" bundle="7" name="spell.english.EnglishDictionary"
- provides specification="spell.services.DictionaryService"
- missinghandlers list="[]"
- requiredhandlers list="[org.apache.felix.ipojo:provides, org.apache.felix.ipojo:architecture]"
-
-On Gogo:
-
-[source,sh]
- $factories
- Factory spell.checker.SpellCheck (VALID)
- Factory spell.gui.SpellCheckerGui (VALID)
- Factory spell.english.EnglishDictionary (VALID)
- $factory spell.english.EnglishDictionary
- factory implementation-class="spell.english.EnglishDictionary" state="valid" bundle="7" name="spell.english.EnglishDictionary"
- provides specification="spell.services.DictionaryService"
- missinghandlers list="[]"
- requiredhandlers list="[org.apache.felix.ipojo:provides, org.apache.felix.ipojo:architecture]"
-
-On the first line, you get the implementation class of the type, the state of the factory, the bundle declaring the type and the name of the type.
-You also get the list of required and missing handlers.
-
-== List available handlers
-
-Like listing factories, you can get the list of handlers.
-
-[source,sh]
- -> arch -handlers
- Handler org.apache.felix.ipojo:controller (VALID)
- Handler org.apache.felix.ipojo:callback (VALID)
- Handler org.apache.felix.ipojo:requires (VALID)
- Handler org.apache.felix.ipojo:provides (VALID)
- Handler org.apache.felix.ipojo:properties (VALID)
- Handler org.apache.felix.ipojo:architecture (VALID)
- Handler org.apache.felix.ipojo.handler.whiteboard:wbp (VALID)
-
-On Gogo:
-
-[source,sh]
- $handlers
- Handler org.apache.felix.ipojo:controller (VALID)
- Handler org.apache.felix.ipojo:callback (VALID)
- Handler org.apache.felix.ipojo:requires (VALID)
- Handler org.apache.felix.ipojo:provides (VALID)
- Handler org.apache.felix.ipojo:properties (VALID)
- Handler org.apache.felix.ipojo:architecture (VALID)
- Handler org.apache.felix.ipojo.handler.whiteboard:wbp (VALID)
-
-Handlers with the `org.apache.felix.ipojo` namespace (section before `:`) are core handlers (provided by the iPOJO core bundles).
-Others are external handlers (provided by others bundles).
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-karaf-feature.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-karaf-feature.adoc
deleted file mode 100644
index ae3282b..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-karaf-feature.adoc
+++ /dev/null
@@ -1,24 +0,0 @@
-= iPOJO Karaf Features
-
-If you are using http://karaf.apache.org[Apache Karaf], there is a set of _features_ easing the deployment of iPOJO bundles and related tools on Karaf.
-
-== Add the features file
-
-First, launch Karaf and add the http://repo1.maven.org/maven2/org/apache/felix/org.apache.felix.ipojo.features/{{ipojo.release}}/org.apache.felix.ipojo.features-{{ipojo.release}}.xml[iPOJO Feature] file:
-
-[source,sh]
- features:addurl http://repo1.maven.org/maven2/org/apache/felix/org.apache.felix.ipojo.features/{{ipojo.release}}/org.apache.felix.ipojo.features-{{ipojo.release}}.xml
-
-== Installing features:
-
-Several features are available:
-
-* `ipojo`: contains the iPOJO Core Runtime
-* `ipojo-command`: extends the `ipojo` feature with the iPOJO Shell Commands
-* `ipojo-all`: contains the iPOJO Core Runtime, Shell Commands, Composition Model, and API
-* `ipojo-webconsole`: install the Apache Felix WebConsole, iPOJO Core Runtime and the iPOJO Plugin for the Web Console.
-
-Installing a feature is quite simple:
-
-[source,sh]
- features:install ipojo-command
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-maven-plug-in.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-maven-plug-in.adoc
deleted file mode 100644
index 78b6036..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-maven-plug-in.adoc
+++ /dev/null
@@ -1,241 +0,0 @@
-= How to use the iPOJO Maven Plug-in
-
-== Basic configuration
-
-To use the iPOJO Maven plug-in, edit the following pom.xml (replace all $XXX elements):
-[source,xml]
- <project>
- <modelVersion>4.0.0</modelVersion>
- <groupId>$YOUR_GROUP_ID</groupId>
- <artifactId>$YOUR_ARTIFACT_ID</artifactId>
- <version>$YOUR_ARTIFACT_VERSION</version>
- <name>$YOUR_PROJECT_NAME</name>
- <!-- Use the bundle packaging type -->
- <packaging>bundle</packaging>
- <dependencies>
- $YOUR_MAVEN_DEPENDENCIES
- </dependencies>
- <build>
- <plugins>
- <!-- BND Maven Plugin Configuration -->
- <plugin>
- <groupId>org.apache.felix</groupId>
- <artifactId>maven-bundle-plugin</artifactId>
- <extensions>true</extensions>
- <configuration>
- <instructions>
- <Bundle-SymbolicName>${pom.artifactId}</Bundle-SymbolicName>
- <Private-Package>$YOUR_PRIVATE_PACKAGE</Private-Package>
- <Export-Package>$YOUR_EXPORTED_PACKAGE</Export-Package>
- </instructions>
- </configuration>
- </plugin>
- <plugin>
- <groupId>org.apache.felix</groupId>
- <artifactId>maven-ipojo-plugin</artifactId>
- <version>{{ipojo.release}}</version>
- <executions>
- <execution>
- <goals>
- <goal>ipojo-bundle</goal>
- </goals>
- </execution>
- </executions>
- </plugin>
- </plugins>
- </build>
- </project>
-
-The iPOJO Maven Plug-in is generally used with the BND Maven Plug-in (more details here).
-However the two configurations are completely separated.
-So, you can use all BND Maven plug-in features.
-The iPOJO configuration section can be used as previously written without any changes.
-However it requires that your metadata file is either inside `src/main/ipojo` or inside the `src/main/resources` folder and named "metadata.xml".
-
-== Execution
-
-To manipulate your project, use the "_mvn clean install_" command.
-The output should be like:
-
-[source,sh]
- [INFO] Scanning for projects...
- [INFO] ----------------------------------------------------------------------------
- [INFO] Building Hello Client
- [INFO] task-segment: [clean, install]
- [INFO] ----------------------------------------------------------------------------
- [INFO] [clean:clean]
- [INFO] Deleting directory ...hello.client\target
- [INFO] Deleting directory ...hello.client\target\classes
- [INFO] Deleting directory ...hello.client\target\test-classes
- [INFO] Deleting directory ...hello.client\target\site
- [INFO] [resources:resources]
- [INFO] Using default encoding to copy filtered resources.
- [INFO] Copying 1 resource
- [INFO] [compiler:compile]
- [INFO] Compiling 1 source file to ...hello.client\target\classes
- [INFO] [resources:testResources]
- [INFO] Using default encoding to copy filtered resources.
- [INFO] Resource directory does not exist: ...hello.client\src\test\resources
- [INFO] [compiler:testCompile]
- [INFO] No sources to compile
- [INFO] [surefire:test]
- [INFO] No tests to run.
- [INFO] [bundle:bundle]
- [INFO] [org.apache.felix.ipojo.:ipojo-bundle {execution: default}]
- [INFO] Start bundle manipulation
- [INFO] Metadata File : ...hello.client\target\classes\metadata.xml
- [INFO] Input Bundle File : ...hello.client\target\hello.client-0.0.1.jar
- [INFO] Bundle manipulation - SUCCESS
- [INFO] [install:install]
- [INFO] Installing ...hello.client\target\hello.client-0.0.1.jar to D:\Dev\maven-repo\ipojo\example\hello.client\0.0.1\hello.client-0.0.1.jar
- [INFO] ------------------------------------------------------------------------
- [INFO] BUILD SUCCESSFUL
- [INFO] ------------------------------------------------------------------------
- [INFO] Total time: 9 seconds
- [INFO] Finished at: Mon Aug 13 14:04:55 CEST 2007
- [INFO] Final Memory: 6M/13M
- [INFO] ------------------------------------------------------------------------
-
-== Configuration Options
-
-You can configure the localization of the iPOJO metadata file as following:
-[source,xml]
- <plugin>
- <groupId>org.apache.felix</groupId>
- <artifactId>maven-ipojo-plugin</artifactId>
- <version>{{ipojo.release}}</version>
- <executions>
- <execution>
- <goals>
- <goal>ipojo-bundle</goal>
- </goals>
- <configuration>
- <metadata>ipojo/meta.xml</metadata>
- </configuration>
- </execution>
- </executions>
- </plugin>
-
-In the metadata element, you can specify your metadata file or directory.
-The given file path is relative to the root directory ("./ipojo/meta.xml").
-If the specified location is a directory, all contained XML files will be used.
-By default, the plugin searches metadata files into the `src/main/ipojo` folder.
-If not found then it searches for `target/classes/metadata.xml` and `./metadata.xml`.
-
-The directory support was introduced in the `1.7.0` version.
-Previously only one metadata file was found.
-Before the `1.7.0`, the set location was searched in all resource folders.
-This is no more supported because it's an anti-pattern.
-
-The second option allows skipping annotations processing, by using the `ignoreAnnotations` element:
-[source,xml]
- <plugin>
- <groupId>org.apache.felix</groupId>
- <artifactId>maven-ipojo-plugin</artifactId>
- <version>{{ipojo.release}}</version>
- <executions>
- <execution>
- <goals>
- <goal>ipojo-bundle</goal>
- </goals>
- <configuration>
- <ignoreAnnotations>true</ignoreAnnotations>
- </configuration>
- </execution>
- </executions>
- </plugin>
-
-You can also ignore embedded XML-Schemas to use external ones.
-To do so, add the `ignoreEmbeddedSchemas`.
-If set to `true`, the manipulator doesn't use embedded XML-Schemas:
-[source,xml]
- <plugin>
- <groupId>org.apache.felix</groupId>
- <artifactId>maven-ipojo-plugin</artifactId>
- <version>{{ipojo.release}}</version>
- <executions>
- <execution>
- <goals>
- <goal>ipojo-bundle</goal>
- </goals>
- <configuration>
- <ignoreEmbeddedSchemas>true</ignoreEmbeddedSchemas>
- </configuration>
- </execution>
- </executions>
- </plugin>
-
-== Generate the skeleton of your iPOJO bundle
-
-The maven-ipojo-plugin provides a way to generate the skeleton of your project.
-To generate this structure, just launch the following command:
-
-[source,sh]
- mvn org.apache.maven.plugins:maven-archetype-plugin:generate \
- -DarchetypeArtifactId=maven-ipojo-plugin \
- -DarchetypeGroupId=org.apache.felix \
- -DartifactId=ARTIFACT_NAME_OF_YOUR_PROJECT \
- -DgroupId=GROUP_ID_OF_YOUR_PROJECT \
- -DarchetypeVersion=VERSION_OF_YOUR_PROJECT \
- -DpackageName=PACKAGE_NAME
-
-This command generates :
-
-* a pom file (to update),
-* the src/main/java and src/main/resources folders,
-* the structure of your package name.
-
-The generated project uses iPOJO annotation and is ready to be deployed.
-
-INFO: [discrete]
-==== Maven Archetype
-
-The maven-ipojo-plugin archetype generates a pom file using the latest released version of the maven-ipojo-plugin.
-
-== Describing iPOJO configuration in the pom file
-
-It is also possible to describe iPOJO components and instances inside the pom file (avoiding using a externalized file).
-The configuration can be described in the `metadata` attribute inside a CDATA block.
-[source,xml]
- <plugin>
- <groupId>org.apache.felix</groupId>
- <artifactId>maven-ipojo-plugin</artifactId>
- <version>{{ipojo.release}}</version>
- <executions>
- <execution>
- <goals>
- <goal>ipojo-bundle</goal>
- </goals>
- <configuration>
- <ignoreAnnotations>true</ignoreAnnotations>
- <metadata>
- <![CDATA[
- <ipojo
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="org.apache.felix.ipojo http://felix.apache.org/ipojo/schemas/CURRENT/core.xsd"
- xmlns="org.apache.felix.ipojo">
- <component
- classname="org.apache.felix.ipojo.test.scenarios.component.LifecycleControllerTest"
- name="LFC-Test">
- <provides />
- <controller field="m_state" />
- <properties>
- <property name="conf" field="m_conf" method="setConf" />
- </properties>
- </component>
- <component
- classname="org.apache.felix.ipojo.test.scenarios.component.LifecycleControllerTest"
- name="LFC-Test-Immediate" immediate="true" architecture="true">
- <provides />
- <controller field="m_state" />
- <properties>
- <property name="conf" field="m_conf" method="setConf" />
- </properties>
- </component>
- </ipojo>
- ]]>
- </metadata>
- </configuration>
- </execution>
- </executions>
- </plugin>
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-webconsole-plugin.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-webconsole-plugin.adoc
deleted file mode 100644
index 049a7ef..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-webconsole-plugin.adoc
+++ /dev/null
@@ -1,73 +0,0 @@
-= iPOJO Webconsole Plugin
-
-_If you like the Apache Felix Web Console, you will be interested by the iPOJO plugin.
-This plugin gives you all the information about iPOJO instances, factories and handlers deployed on the framework._
-
-
-
-== Features
-
-* Lists created instances
-* Gives details about instances (state, factory, required services, provided services, used instances, and raw architecture)
-* Lists available factories
-* Gives details about factories (state, created instances, required handlers, missing handlers, raw architecture, properties...)
-* List available handlers
-* Instance and Factories are `navigable`, so you can easily understand the system architecture
-
-== Using the plugin
-
-To use the plugin you need an OSGi platform with:
-
-* a HTTP Service
-* The Apache Felix Webconsole
-* iPOJO
-* The iPOJO Web console plugin
-
-You can download link:{attachmentsdir}/ipojo/ipojo-webconsole-quicktart-distribution.zip[this Felix distribution] as a deployment example.
-Unzip the archive and go to the Felix directory to launch Felix:
-
-[source,sh]
- cd ipojo-webconsole-quicktart-1.9.0-SNAPSHOT/felix-framework-4.2.1/
- java -jar bin/felix.jar
-
-Once launched, you can check the deployed bundles:
-
-[source,sh]
-----
-[INFO] Started jetty 6.1.x at port(s) HTTP:8080
-____________________________
-Welcome to Apache Felix Gogo
-
-g! INFO : org.apache.felix.webconsole.plugins.memoryusage (17): Storing Memory Dumps in /Users/clement/Projects/felix-trunk/ipojo/distributions/ipojo-webconsole-quicktart/target/ipojo-webconsole-quicktart-1.9.0-SNAPSHOT/felix-framework-4.2.1/./felix-cache/bundle17/data/dumps
-INFO : org.apache.felix.webconsole.plugins.memoryusage (17): Setting Automatic Memory Dump Threshold to 0% for pools [CMS Old Gen, CMS Perm Gen, Code Cache]
-INFO : org.apache.felix.webconsole.plugins.memoryusage (17): Automatic Memory Dump cannot be set for pools [Par Eden Space, Par Survivor Space]
-INFO : org.apache.felix.webconsole.plugins.memoryusage (17): Setting Automatic Memory Dump Interval to 21600 seconds
-
-g! lb
-START LEVEL 1
- ID|State |Level|Name
- 0|Active | 0|System Bundle (4.2.1)
- 1|Active | 1|Java Servlet API (2.4.0)
- 2|Active | 1|Commons FileUpload (1.2.2)
- 3|Active | 1|Commons IO (2.4.0)
- 4|Active | 1|Apache Felix Bundle Repository (1.6.6)
- 5|Active | 1|Apache Felix Gogo Command (0.12.0)
- 6|Active | 1|Apache Felix Gogo Runtime (0.10.0)
- 7|Active | 1|Apache Felix Gogo Shell (0.10.0)
- 8|Active | 1|Apache Felix Http Api (2.2.0)
- 9|Active | 1|Apache Felix Http Base (2.2.0)
- 10|Active | 1|Apache Felix Http Jetty (2.2.0)
- 11|Active | 1|Apache Felix iPOJO (1.8.6)
- 12|Active | 1|Apache Felix iPOJO Annotations (1.8.6)
- 13|Active | 1|Apache Felix iPOJO Gogo Command (1.0.1)
- 15|Active | 1|Apache Felix iPOJO WebConsole Plugins (1.7.0.SNAPSHOT)
- 16|Active | 1|Apache Felix Web Management Console (4.0.0)
- 17|Active | 1|Apache Felix Web Console Memory Usage Plugin (1.0.2)
- 18|Active | 1|Apache Felix Web Console Package Admin Service Plugin (1.0.0)
- 19|Active | 1|osgi.cmpn (4.2.0.200908310645)
- 20|Active | 1|OW2 Chameleon - JSON Bundle (from org.json) (20090911.0.0.0002)
-----
-
-You access the web console at: http://localhost:8080/system/console/.
-The login/password are _admin_/_admin_.
-The iPOJO tabs gives you all the iPOJO information of the system.
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/junit4osgi.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/junit4osgi.adoc
deleted file mode 100644
index a272753..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/junit4osgi.adoc
+++ /dev/null
@@ -1,219 +0,0 @@
-= JUnit4OSGi : Executing Unitary and Integration Test on OSGi
-
-This page is _deprecated_
-
-'''
-
-== Goals
-
-Executing tests on OSGi became a stringent requirement as several aspects need to be tested.
-Indeed, modularity, services (and the inherent dynamism) and the business logic need to be tested.
-The goal of JUnit4OSGi is to provide an execution gateway in order to test bundles and services.
-Instead of injecting mock objects, as provided by regular test frameworks to hide the underlying Executing environment, tests are directly executed on OSGi and so have access to all the features provided by the OSGi framework.
-This allows developers checking modularity aspect and service dynamism in addition to the business logic.
-
-== Principles
-
-Junit4OSGi is split in several pieces.
-First the core bundle (Junit4OSGi) contains an extended version of Junit (3.8.1).
-On the top of this framework, several runners are implemented:
-
-* Immediate runner : launch every available test suite
-* Command line runner : Felix command line allowing to choose the test suite(s) to launch
-* Swing Runner : a very simple Swing runner
-* Maven runner: a maven plug-in allowing to automate tests during the project build process
-
-The different runners give a great flexibility to the framework that can be used during the build process or to test an application in a special environment (such as J2ME).
-Test suites and test cases are package inside bundles.
-Junit4OSGi extend Junit to support OSGi test suite and OSGi test case.
-These two kinds of test classes are able to use the bundle context of the bundle and so are able to deal with the underlying OSGi framework.
-
-== Installing the framework
-
-Except if you use the maven front end (automating the launch a an OSGi framework (Felix) and deploying required bundles), to launch the Junit framework you need to deploy and start
-
-* http://people.apache.org/~clement/ipojo/binaries/org.apache.felix.ipojo-0.8.0-SNAPSHOT.jar[iPOJO 0.8.0-SNASPHOT]
-* http://people.apache.org/~clement/ipojo/binaries/org.apache.felix.ipojo.handler.extender.pattern-0.8.0-SNAPSHOT.jar[iPOJO Extender Pattern Handler 0.8.0-SNAPSHOT]
-* http://people.apache.org/~clement/ipojo/junit4osgi/org.apache.felix.ipojo.junit4osgi-0.8.0-SNAPSHOT.jar[The Junit4OSGi bundle]
-* One runner such as the http://people.apache.org/~clement/ipojo/junit4osgi/org.apache.felix.ipojo.junit4osgi.felix-command-0.8.0-SNAPSHOT.jar[Felix command] one
-
-The archive available http://people.apache.org/~clement/ipojo/junit4osgi/junit4osgi.tutorial.zip[here] contains a pre-configured version of Felix with the previously mentionned bundles.
-
-== Writing Junit Test Case and Test Suite
-
-This section describes briefly how to write test cases and test suites and how they are used by the Junit4OSGi framework.
-More details are available on the Junit web site http://www.junit.org/.
-
-The Money class was introduced in the Junit tutorial and was implemented as the following:
-
-----
-package junit.money;
-
-public class Money {
- private int fAmount;
- private String fCurrency;
-
- public Money(int amount, String currency) {
- fAmount= amount;
- fCurrency= currency;
- }
-
- public int amount() {
- return fAmount;
- }
-
- public String currency() {
- return fCurrency;
- }
-
- public Money add(Money m) {
- return new Money(amount()+m.amount(), currency());
- }
-
- public boolean equals(Object anObject) {
- if (anObject instanceof Money) {
- Money aMoney= (Money)anObject;
- return aMoney.currency().equals(currency())
- && amount() == aMoney.amount();
- }
- return false;
- }
-----
-
-So, to test this implementation, we decide to write a simple class testing the equals and add methods.
-This class can be implemented as the following:
-
- public class SimpleTestCase extends TestCase {
- private Money f12CHF;
- private Money f14CHF;
- public void setUp() {
- f12CHF= new Money(12, "CHF");
- f14CHF= new Money(14, "CHF");
- }
- public void testEquals() {
- assertTrue(!f12CHF.equals(null));
- assertEquals(f12CHF, f12CHF);
- assertEquals(f12CHF, new Money(12, "CHF"));
- assertTrue(!f12CHF.equals(f14CHF));
- }
- public void testSimpleAdd() {
- Money expected= new Money(26, "CHF");
- Money result= f12CHF.add(f14CHF);
- assertTrue(expected.equals(result));
- }
- }
-
-Moreover, in order to launch these tests, we create a test suite (declaring the list of test to execute):
-
- public class SimpleTestSuite {
-
- public static Test suite() {
- TestSuite suite = new TestSuite("Money Simple Test Suite");
- suite.addTestSuite(SimpleTestCase.class);
- return suite;
- }
- }
-
-Now, we have to package our tests and the Money class inside a bundle.
-Of course, it should be packaged in two different bundles but to keep simple we choose to create just one.
-To create the bundle, launch "ant" at the root of the junit-example directory.
-The resulting bundle contains our three classes.
-These tests are connected to the junit4osgi framework by specifying a special header in the manifest:
-
- Test-Suite: junit.example.SimpleTestSuite
-
-This header lists the test suite contained in the bundle.
-Once packaged, we can launch our tests.
-Start the pre-configured Felix with the following command launched from the Felix directory:
-
- java -jar bin/felix.jar
-
-Then deploy the created bundle:
-
- start file:../junit-example/output/junit-example.jar
-
-Finally, run the test with the junit command
-
- junit 8
-
-The argument indicates the bundle containing the test suite to execute.
-The "all" special argument runs every available test suites.
-
-----
--> junit 8
-Executing [Money Simple Test Suite]
-..
-Time: 0,001
-
-OK (2 tests)
-----
-
-== Writing Junit Test Case and Test Suite specialized for OSGi
-
-The previous example has illustrated how creating thest cases and test suites by using the regular Junit framework.
-However, junit4osgi has the particularity to support specialized test for OSGi.
-For example, imagine the very simple Hello Service implemented by the following class:
-
-----
-public class HelloProvider implements HelloService {
-
- public String getHelloMessage() {
- return "hello";
- }
-}
-----
-
-The bundle containing this implementation should register it.
-So you can decide to check this and to check the returned hello message.
-Instead of extending TestCase, this test case will extend OSGiTestCase (provided by the Junit4OSGi framework):
-
-----
-public class SimpleTestCase extends OSGiTestCase {
-
- public void testHelloAvailability() {
- ServiceReference ref = context.getServiceReference(HelloService.class.getName());
- assertNotNull("Assert Availability", ref);
- }
-
- public void testHelloMessage() {
- ServiceReference ref =
- context.getServiceReference(HelloService.class.getName());
- assertNotNull("Assert Availability", ref);
- HelloService hs = (HelloService) context.getService(ref);
- String message = hs.getHelloMessage();
- assertNotNull("Check the message existence", message);
- assertEquals("Check the message", "hello", message);
- }
-
-}
-----
-
-First, note that this class follows the same rules than regular test cases.
-All methods with a name starting with _test_ will be executed.
-However, this class can access to the bundle context of its bundle by using the _context_ field.
-By using this field, the class can check the availability of services ...
-OSGi test cases are gathered in OSGi test suite such as:
-
- public class SimpleTestSuite {
-
- public static Test suite(BundleContext context) {
- OSGiTestSuite suite = new OSGiTestSuite(
- "Hello Service Test Suite",
- context
- );
- suite.addTestSuite(SimpleTestCase.class);
- return suite;
- }
- }
-
-Note that the suite method receives the bundle context allowing the creation of an OSGi Test Suite object.
-The execution of these tests follows the same steps than the previous example:
-
-* Compile the tests and create the bundle by launching ant from the junit-osgi-example directory
-* Start Felix
-* Deploy the bundle with the following command: `start file:../junit-osgi-example/output/junit-osgi-example.jar`
-* Execute the test by using the junit command
-
-== Maven front end: automating tests in your build process
-
-_Coming soon_
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/apache-felix-ipojo-api.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/apache-felix-ipojo-api.adoc
deleted file mode 100644
index 49cba77..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/apache-felix-ipojo-api.adoc
+++ /dev/null
@@ -1,375 +0,0 @@
-= iPOJO API
-
-_The iPOJO API provides a third way to describe iPOJO components and instances.
-With the API, you can dynamically create new components types and create instances from them.
-Your component types are described with a Java API.
-To use the API, deploy and start the iPOJO-API bundle and the iPOJO core bundle._
-
-
-
-== A simple example
-
-Let's imagine a simple component providing a service Foo.
-The following code is the implementation class of our component:
-
-[source,java]
-----
-package org.example.service.impl;
-
-import org.example.service.Foo;
-
-public class FooImpl implements Foo {
-
- public void doSomething() {
- // Do something...
- }
-
-}
-----
-
-To create the component type and an instance of the component type just create a class, get the bundle context (either from a Bundle-Activator, or from an iPOJO component), and write the following code:
-
-[source,java]
- new PrimitiveComponentType()
- .setBundleContext(context)
- .setClassName(FooImpl.class.getName())
- .addService(new Service()) // Provide the Foo service
- .createInstance(); // Create the instance
-
-So, now let's imagine another component using this service.
-The following code is the implementation class of this component type:
-
-[source,java]
-----
-package org.example.service.impl;
-
-import org.example.service.Foo;
-
-public class MyComponentImpl {
- private Foo myFoo;
-
- public void start() {
- myFoo.doSomething();
- }
-
-}
-----
-
-It is a regular iPOJO component expecting to get a Foo service in the `myFoo` field.
-It also has a method executed when the instance is valid using the Foo service.
-To describe this component, just write the following lines:
-
-[source,java]
- new PrimitiveComponentType()
- .setBundleContext(context)
- .setClassName(MyComponentImpl.class.getName())
- .addDependency(new Dependency().setField("myFoo"))
- .setValidateMethod("start")
- .createInstance();
-
-== Deploying the API
-
-Before being able to create component types at runtime, you need to deploy 3 bundles:
-
-* iPOJO (core)
-* iPOJO Composite
-* iPOJO API
-
-== Primitive Component Type basics
-
-When you create a new Primitive component type (so, using a Java class as implementation), you must set the bundle context and the class name.
-Everything else is optional.
-
-Note about inner classes: iPOJO is based on a bytecode manipulation.
-The API embeds the manipulator.
-So, when you initialize the component type, the specified class name is manipulated (if not already manipulated).
-So, as this force using a customized classloader, inner classes cannot be manipulated.
-So, inner class injection is not supported with the API.
-
-== Immediate Component, Validate and Invalidate Method
-
-To set the component type as immediate, just call the `setImmediate(immediate)` method on the primitive component type object.
-To set validate and invalidate methods, just call the `setValidate(method)` and `setInvalidate(method)`.
-Specify the method name that you want to call in argument.
-
-== Declaring services
-
-To declare that a component provides a service, add a new service to your primitive component type.
-The Service object can be configured.
-By default, it exposed every implemented interface (regular iPOJO behavior).
-So, you can:
-
-* Add service property
-* Set the creation strategy
-* Set the exposed service specifications
-+
-[source,java]
- new PrimitiveComponentType()
- .setBundleContext(context)
- .setClassName(org.example.service.impl.MyComponentImpl.class.getName())
- .addService(new Service()
- .addProperty(new ServiceProperty()
- .setField("myServiceProperty")
- .setName("sample.myProperty"))
- .setCreationStrategy(Service.INSTANCE_STRATEGY))
- .createInstance();
-
-== Service Dependencies
-
-To declare a service dependency, create and add a Dependency object.
-The dependency object offers all the iPOJO service dependency features.
-You can set the injected field and/or bind/unbind methods.
-Here is an example:
-
-[source,java]
- new PrimitiveComponentType()
- .setBundleContext(context)
- .setClassName(org.example.service.impl.MyComponentImpl.class.getName())
- .addDependency(
- new Dependency().setField("myFoo")
- .setOptional(true)
- .setDefaultImplementation("org.sample.FooDefaultImplementation")
- )
- .createInstance();
-
-== Properties
-
-Thanks to the `addProperty` method, you can create component properties.
-Here is some example of properties:
-
-[source,java]
- new PrimitiveComponentType()
- .setBundleContext(context)
- .setClassName(MyComponentImpl.class.getName())
- .addProperty(new Property()
- .setField("myProperty")
- .setValue("default-value")
- )
- .addProperty(new Property()
- .setMethod("setMethod")
- .setName("prop")
- )
- .createInstance();
-
-== Temporal Dependencies
-
-Temporal dependencies are also supported:
-
-[source,java]
- new PrimitiveComponentType()
- .setBundleContext(context)
- .setClassName(MyComponentImpl.class.getName())
- .addDependency(
- new TemporalDependency().setField("myFoo")
- .setOnTimeoutPolicy(TemporalDependency.NULLABLE)
- .setTimeout(3000)
- .setProxy(true)
- )
- .createInstance();
-
-== Instance creation
-
-The API allows you to create instances from the component type you described.
-Three differents methods.
-The `createInstance()` method just creates an instance.
-The `createInstance(String name)` method allows to set the instance name.
-Finally, the `createInstance(Dictionary configuration)` allows setting the instance configuration.
-All those methods returns the ComponentInstance object allowing to manage the instance (stop, start, dispose).
-
-== Managed Service and Propagation
-
-You can enable/disable the property propagation thanks to the `setPropagation` method on the PrimitiveComponentType object.
-You can also set the the managed service PID with the `setManagedServicePID` method.
-This method should be only use to give a default value of for singleton component.
-In all other case, the managed service pid has to be provided inside the instance configuration.
-
-== Managing iPOJO Factory
-
-Beyond the PrimitiveComponentType, an iPOJO factory is hidden.
-You can configure this factory to be public or private with the `setPublic` method.
-You can also set the name of the factory with the `setName` method.
-
-Then, you can access to the Factory object by calling the `getFactory` method.
-
-== Access to the introspection API
-
-The API provides bridge to get access to the iPOJO introspection API.
-The introspection API allows reconfiguring at runtime an instance (properties, service dependencies...).
-From Service and Dependency, Property and ServiceProperty objects, call the `getXXXDescription` method.
-You must give the instance that you want to introspect in argument.
-If the lookup success, you get an object allowing reconfiguring the service, dependency or property.
-
-== Singleton Component Type
-
-If you are sure to create only one instance of your component type, you can use the singleton component type class.
-This is a kind of primitive component type, but when you start it (with the `create` method), it will automatically create an instance.
-
-[source,java]
- PrimitiveComponentType type = new SingletonComponentType()
- .setBundleContext(context)
- .setClassName(org.example.service.impl.MyComponentImpl.class.getName())
- .addDependency(new Dependency().setField("myFoo"))
- .setValidateMethod("start");
-
- ((SingletonComponentType) type)
- .setObject(new MyComponentImpl(5)) // Inject a pojo object
- .create();// Create an instance
-
-The type created with the singleton component type are set to `private` by default.
-Instead of calling the `start` method, you have to call one of the `create` methods to start the type and create the instance.
-
-You can also set the contained POJO object by using the `setObject` method.
-The given object MUST be compatible with the component implementation class.
-
-== Using external handlers
-
-iPOJO is extensible...
-So, it makes sense that the API is also extensible.
-So component type provides a method allowing to add external handler configuration:
-
-[source,java]
- return new PrimitiveComponentType()
- .setBundleContext(context)
- .setClassName(HostImpl.class.getName())
- .addHandler(new Whiteboard()
- .onArrival("arrival")
- .onDeparture("departure")
- .setFilter("(foo=foo)")
- );
-
-The `addHandler` method allows you to add any handler description.
-A handler description is an object of a class implementing `org.apache.felix.ipojo.api.HandlerConfiguration`.
-Handler provider willing to support the API have to provide this class.
-For example, the example above uses `Whiteboard` that is the Whiteboard pattern handler description.
-This class is very simple, and is shown below:
-
-[source,java]
-----
-public class Whiteboard implements HandlerConfiguration {
-
- public static final String NAME = "wbp";
-
- public static final String NAMESPACE = "org.apache.felix.ipojo.whiteboard";
-
- private String arrival;
-
- private String departure;
-
- private String modification;
-
- private String filter;
-
- public Whiteboard onArrival(String method) {
- arrival = method;
- return this;
- }
-
- public Whiteboard onDeparture(String method) {
- departure = method;
- return this;
- }
-
- public Whiteboard onModification(String method) {
- modification = method;
- return this;
- }
-
- public Whiteboard setFilter(String fil) {
- filter = fil;
- return this;
- }
-
- public Element getElement() {
- ensureValidity();
- // Create the root element.
- Element element = new Element(NAME, NAMESPACE);
- // Mandatory attributes
- element.addAttribute(new Attribute("onArrival", arrival));
- element.addAttribute(new Attribute("onDeparture", departure));
- element.addAttribute(new Attribute("filter", filter));
-
- // Optional attribute
- if (modification != null) {
- element.addAttribute(new Attribute("onModification", modification));
- }
-
- return element;
- }
-
- private void ensureValidity() {
- if (arrival == null) {
- throw new IllegalStateException("The whiteboard pattern configuration must have a onArrival method");
- }
- if (departure == null) {
- throw new IllegalStateException("The whiteboard pattern configuration must have a onDeparture method");
- }
- if (filter == null) {
- throw new IllegalStateException("The whiteboard pattern configuration must have a filter");
- }
-
- }
-----
-
-The only required method is `getElement` returning the `Element-Attribute` structure representing the handler configuration (this uses the internal iPOJO data format).
-If the metadata cannot be generated, the class throws IllegalStateExceptions.
-
-== Creating compositions with the API
-
-The API also allows you to create iPOJO compositions in a pretty simple way.
-So you can create compositions:
-
-* containing internal instances
-* importing services
-* instantiating sub-services
-* exporting services
-* providing services (by delegation)
-
-Here are some examples:
-
-[discrete]
-==== Creating instances inside a composite:
-
-[source,java]
- PrimitiveComponentType prov = createAProvider(); // Create a primitive type
- PrimitiveComponentType cons = createAConsumer(); // Create another primitive type
-
- CompositeComponentType type = new CompositeComponentType()
- .setBundleContext(context)
- .setComponentTypeName("comp1")
- .addInstance(new Instance(prov.getFactory().getName())) // Create an instance in the composite
- .addInstance(new Instance(cons.getFactory().getName()));
-
- ComponentInstance ci = type.createInstance();
-
-[discrete]
-==== Importing a service
-
-[source,java]
- CompositeComponentType type = new CompositeComponentType()
- .setBundleContext(context)
- .setComponentTypeName("comp3")
- .addSubService(new ImportedService() // Importation
- .setSpecification(Foo.class.getName())
- .setOptional(true));
-
-[discrete]
-==== Instantiating a service
-
-[source,java]
- CompositeComponentType type = new CompositeComponentType()
- .setBundleContext(context)
- .setComponentTypeName("comp2")
- .addSubService(new InstantiatedService() // Instantiated service
- .setSpecification(Foo.class.getName()))
- .addInstance(new Instance(cons.getFactory().getName()));
-
-[discrete]
-==== Exporting a service
-
-[source,java]
- CompositeComponentType type = new CompositeComponentType()
- .setBundleContext(context)
- .setComponentTypeName("compExport")
- .addSubService(new InstantiatedService().setSpecification(Foo.class.getName()))
- .addService(new ExportedService()
- .setSpecification(Foo.class.getName())); // Exports a service
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/apache-felix-ipojo-instances.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/apache-felix-ipojo-instances.adoc
deleted file mode 100644
index f348941..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/apache-felix-ipojo-instances.adoc
+++ /dev/null
@@ -1,427 +0,0 @@
-= Creating instances
-
-== Component types and instances
-
-iPOJO is a component model enforcing strictly the distinction between component types and instances.
-The relationship between types and instances is the same as the one between classes and objects in OOP.
-You can _instantiate_ as many instances as you want from a component type.
-These instances can be configured with different properties.
-As a consequence, just using @Component or <component> declares a component type, not an instance.
-So, at runtime, nothing will happen until you actually declare or create an instance.
-
-iPOJO provides several ways to create instances, this page presents these possibilities:
-
-* @Instantiate to create an instance directly from the a class annotated with @Component
-* @Configuration to declare a set of instances
-* using <instance>in the XML metadata
-* using the iPOJO Factory service
-* using the OSGi Configuration Admin
-* using the `DeclarationBuilderService`
-
-== @Instantiate
-
-The @Instantiate annotation is the simplest way to declare an instance.
-In a class annotated with @Component, you just add the @Instantiate annotation.
-It instructs iPOJO to declare an instance of the component type described by the current class.
-
-[source,java]
-----
-import org.apache.felix.ipojo.annotations.Component;
-import org.apache.felix.ipojo.annotations.Instantiate;
-
-@Component
-@Instantiate
-public class MyComponent {
- //...
-}
-----
-
-Optionally, you can set the instance name, using the `name` attribute.
-
-[source,java]
-----
-import org.apache.felix.ipojo.annotations.Component;
-import org.apache.felix.ipojo.annotations.Instantiate;
-
-@Component
-@Instantiate(name="myInstance")
-public class MyComponent {
- //...
-}
-----
-
-The @Instantiate annotation is easy to use but, has a couple of limitations:
-
-* it must be used in the @Component class
-* you can't provide a configuration to the instance
-* you can declare only one instance
-
-=== Declaring a singleton instance
-
-The @Instance annotation is particularly useful to declare singleton instances, i.e.
-a component type with only one instance.
-To create a singleton instance, combine the @Instantiate annotation and the `publicFactory` attribute of the @Component annotation:
-
-[source,java]
-----
-import org.apache.felix.ipojo.annotations.Component;
-import org.apache.felix.ipojo.annotations.Instantiate;
-
-@Component(publicFactory=false)
-@Instantiate
-public class MySingleton {
- //...
-}
-----
-
-The `publicFactory=false` attribute makes the component type _private_, so invisible from other bundles.
-No one else would be able to create another instance of the component type.
-
-== @Configuration
-
-This second annotation is used on classes to create one or several instances using a fluent API.
-
-[source,java]
- import org.apache.felix.ipojo.configuration.Configuration;
- import org.apache.felix.ipojo.configuration.Instance;
- import static org.apache.felix.ipojo.configuration.Instance.instance;
- @Configuration
- public class ConfigureOneInstance {
- Instance myInstance = instance().of(MyComponent.class)
- .with("property").setto("value");
- }
-
-The class is annotated with @Configuration.
-All fields of type Instance (`org.apache.felix.ipojo.configuration.Instance`) are read and declares an instance.
-In the previous example, an instance of the `MyComponent` component type is declared with a property `property` set to `value`.
-The instance is named `myInstance` (the field name).
-
-You can declare several instances in the same @Configuration class:
-
-[source,java]
-----
- @Configuration
-public class ConfigureTwoInstances {
-
- // Declare an instance of MyComponent named myInstance
- Instance myInstance1 = instance().of(MyComponent.class)
- .with("property").setto("value");
-
- // Declare an instance of MyComponent
- Instance myInstance2 = instance().of(MyComponent.class)
- .with("property").setto("value2");
-
- // Declare an instance of AnotherComponent
- Instance myInstance2 = instance().of(AnotherComponent.class);
- }
-----
-
-By default, the instance name is set to the field name.
-However, you can also set the instance name:
-
-[source,java]
- // Declare an instance of MyComponent named hello
- Instance myInstance2 = instance().of(MyComponent.class)
- .named("hello")
- .with("property").setto("value");
-
-Using this configuration DSL allows creating a set of instances that you can configure easily.
-
-=== Configuration including lists and maps
-
-The `setto` method accepts any object.
-To ease creating collections, the API proposed two methods to handle lists and maps:
-
-[source,java]
- instance()
- .of(Mycomponent.class)
- // Lists
- .with("list").setto(list(1, 2, 3))
- .with("list2").setto(list().with(1).with(2).with(3))
- // Maps
- .with("map").setto(map().with(pair("entry", "value")))
- .with("map2")
- .setto(map()
- .with(entry("key", 1), entry("key2", 2)));
-
-=== Methods returning Instance objects
-
-The class annotated with @Configuration does not only handle fields, but also handles methods returning Instance object.
-These methods can have either no arguments or the BundleContext as unique argument.
-
-[source,java]
-----
-Instance instance1() {
- return instance().of(MyComponent.class);
-}
-
-Instance instance2(BundleContext bc) {
- return instance().of(MyComponent.class);
-}
-----
-
-As for fields, the method name is used as instance name except if the instance already received a name.
-
-NOTE: the injected BundleContext is the BundleContext of the bundle containing the annotated class.
-
-== Declaring instances in XML
-
-You can declare instances using the iPOJO XML descriptor.
-If you use XML to describe you component type, you probably want to use this way to create your instances.
-[source,xml]
- <instance component="factory.name">
- <property name="property" value="value"/>
- <property name="another property" value="another value"/>
- </instance>
-
-The _component_ attribute specifies the targeted component type.
-Generally it's the qualified classname of the component class, but can also be the name of the factory if one is specified.
-
-The _property_ elements have a mandatory `name` attribute to set the property name, and a `value` attribute to specify the String form of the property's value.
-
-You can declare as many as you want instances in the XML descriptor.
-They can targets component types declared within the same bundles or not.
-
-=== Setting the instance name
-
-To set the instance name you can use the _name_ attribute of the _instance_ element or the _instance.name_ property:
-[source,xml]
- <instance component="…MyComponent" name="my-instance"/>
- <instance component="…MyComponent">
- <property name="instance.name" value="my-instance-2"/>
- </instance>
-
-=== Describing complex properties in XML
-
-The _property_ element can be used to configure complex types such as arrays, lists and maps.
-[source,xml]
- <!--Creates a string array-->
- <property name="array" type="array">
- <property value="a"/>
- <property value="b"/>
- </property>
- <!--Creates a list containing string-->
- <property name="list" type="list">
- <property value="a"/>
- <property value="b"/>
- </property>
- <!--Creates a dictionary containing string-->
- <property name="dict" type="dictionary">
- <property name="a" value="a"/>
- <property name="b" value="b"/>
- </property>
- <!--Creates a map containing string-->
- <property name="map" type="map">
- <property name="a" value="a"/>
- <property name="b" value="b"/>
- </property>
- <!--A complex type can contain other complex objects:-->
- <property name="complex-array" type="array">
- <property type="list">
- <property value="a"/>
- <property value="b"/>
- </property>
- <property type="list">
- <property value="c"/>
- <property value="d"/>
- </property>
- </property>
- <!--Empty structures will create empty objects-->
- <property name="empty-array" type="array"/>
- <property name="empty-list" type="list"/>
- <property name="empty-map" type="map"/>
-
-== Creating instances using the Factory service
-
-In previous technics to create instances were declarative.
-You declare an instance.
-This instance is going to be created as soon as the component type becomes available, and disappears as soon as the component type leaves.
-The technic presented here is a programatic way.
-
-Each (non private) component types are exposed as an OSGi service.
-You can use this OSGi service to create, reconfigure and dispose instances from your code.
-
-=== The Factory service
-
-The published service interface is `[org.apache.felix.ipojo.Factory](http://felix.apache.org/ipojo/api/{{ipojo.release}}/org/apache/felix/ipojo/Factory.html)` and provides the following methods:
-
-[source,java]
-----
-/**
- * Creates an instance manager (i.e. component type instance).
- * @param configuration the configuration properties for this component.
- * @return the created instance manager.
- * @throws UnacceptableConfiguration if the given configuration is not valid.
- * @throws MissingHandlerException if an handler is missing.
- * @throws ConfigurationException if the instance configuration failed.
- */
-ComponentInstance createComponentInstance(Dictionary configuration) throws UnacceptableConfiguration, MissingHandlerException, ConfigurationException;
-
-/**
- * Reconfigures an instance already created. This configuration needs to
- * have the name property to identify the instance.
- * @param conf the configuration to reconfigure the instance. The instance.name property must be set to identify the instance to reconfigure.
- * @throws UnacceptableConfiguration if the given configuration is not consistent for the targeted instance.
- * @throws MissingHandlerException if an handler is missing.
- */
-void reconfigure(Dictionary conf) throws UnacceptableConfiguration, MissingHandlerException;
-----
-
-You can identify the factory using the _factory.name_.
-So target a specific component type, use the following filter:
-
-[source,sh]
- (factory.name=...MyComponent)
-
-If you grab all factories, you can check their names using the `getName()` method.
-
-=== Creating instances
-
-Once you have the right Factory service, you can create instances using `createComponentInstance` method.
-This method returns a reference on the created instance.
-This method receives an optional configuration containing key-value pairs.
-Values are either objects (of the adequate type) or Strings used to create objects.
-This configuration can be 'null' if no properties have to be pushed.
-
-You can set the instance name using the 'instance.name' property can be used to specify the instance name.
-
-Instances are automatically started when created.
-However, the instance can be invalid, if at least one handler is not valid.
-
-The instance creation process can fail.
-Three exceptions can be thrown during the creation:
-
-* `UnacceptableConfiguration` means that mandatory properties are missing in the instance configuration
-* `MissingHandlerException` means that the factory is not valid (i.e.
-an external handler is missing)
-* `ConfigurationException` means that the instance configuration has failed.
-The cause can be either an issue in the component type description or an invalid property type.
-
-If an error occurs, a comprehensive message is reported in order to solve the issue.
-
-The next snippet shows an example of instance creation:
-
-[source,java]
- // Assume we get a Factory in the `fact` field
- Properties props = new Properties();
- props.put("instance.name","instance-name");
- props.put("foo", "blablabla");
- try {
- instance = fact.createComponentInstance(props);
- } catch(Exception e) {
- fail("Cannot create the instance : " e.getMessage());
- }
-
-=== Disposing created instance
-
-You can only disposed instances that you created.
-To dispose an instance, just call the `dispose` method on the ComponentInstance object (returned by the createComponentInstance method).
-
-[source,java]
- instance.dispose();
-
-=== Reconfiguring instance
-
-To reconfigure an instance, call the 'reconfigure' method on the ComponentInstance object.
-This method receives the new set of properties.
-Be aware that the 'instance.name' property cannot be changed.
-
-[source,java]
- Properties props2 = new Properties();
- props2.put("foo", "abc");
- instance.reconfigure(props2);
-
-=== Following the factory state
-
-Factories can becomes invalid if one of the handler they require is not available.
-Basically, handlers are pieces of iPOJO containers.
-
-You can check the factory state using the `Factory.getState()` method.
-This method returns `1` if the factory is valid, `0` if not.
-
-You can also register a `org.apache.felix.ipojo.FactoryStateListener` object on the factory to be notified of the changes.
-
-== Creating instances using the OSGi Configuration Admin
-
-The configuration admin service is a standard service specified by the OSGi Alliance to handle configurations.
-It allows an operator to configured the deployed bundles, and so iPOJO instances.
-
-iPOJO supports the configuration admin and you can create, reconfigure and dispose instanced using this service.
-
-=== Creating instances
-
-Creating an instance is done by creating a _factory_ configuration:
-
-[source,java]
-----
-ConfigurationAdmin admin = ...// Let's assume with have the configuration admin
-Configuration conf = admin.createFactoryConfiguration("...MyComponent", "?");
-
-// Build the instance configuration
-Dictionary dict = new Hashtable();
-//...
-
-// Push the configuration to the configuration admin
-conf.update(dict);
-----
-
-To create the _factory_ configuration, use the `createFactoryConfiguration` method on the Configuration Admin object.
-The first argument is the factory name.
-The second is the location binding.
-Using "?" is a wildcard, for more details, check the configuration admin specification.
-
-You populate this configuration with a dictionary.
-The configuration is actually created using the `update` method.
-
-=== Reconfiguring instances
-
-If the instance was created using the Configuration Admin and you own the Configuration object used for the creation, the reconfiguration is done by calling the `update` method with the new properties.
-
-If the instance was already created, you can configure it using a _regular_ configuration.
-The pid given to this configuration is the instance name.
-
-=== Disposing instances
-
-To dispose an instance, just call the `delete` method on the configuration object you used to configure the instance.
-
-== Creating instances with declarations
-
-Declarations offer a nice way to declares instances in a programmatic way.
-If not retracted by hand, they're bound to the declaring bundle lifecycle (i.e.
-are unregistered when the bundle is not `ACTIVE` anymore).
-
-Declarations can be build using the `DeclarationBuilderService` (see interface below).
-Instances (of components), types (components) and iPOJO extensions can also be build using this service.
-
-[source,java]
- public interface DeclarationBuilderService {
- InstanceBuilder newInstance(String type);
- InstanceBuilder newInstance(String type, String name);
- InstanceBuilder newInstance(String type, String name, String version);
- DeclarationHandle newExtension(String name, FactoryBuilder builder);
- DeclarationHandle newType(Element description);
- }
-
-Instances created through declaration can indeed be configured.
-
-[source,java]
-----
-// Obtain the service through the service registry
-DeclarationBuilderService service = ...
-
-// Get a fresh instance builder
-InstanceBuilder builder = service.newInstance("my-factory");
-
-DeclarationHandle handle = builder.name("a-unique-name") // Make sure name is unique for the expected type
- .configure()
- .property("a-property", "a-value")
- .property("another-property", "another-value")
- .build();
-
-// Push the InstanceDeclaration service in the registry
-handle.publish();
-----
-
-The builder ultimately produces handles to declarations.
-Handles are the live link to the underlying declarations: service publication and un-registration are done through the `handle.publish()` and `handle.retract()` methods.
-Declaration status (is it bound or not) is also accessible with `handle.getStatus()`.
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components.adoc
deleted file mode 100644
index cb66331..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components.adoc
+++ /dev/null
@@ -1,34 +0,0 @@
-= Describing your iPOJO components
-
-_This section describes the different features supported by iPOJO.
-This page aims to answer to the following question: "What can I write in my iPOJO component descriptor?"_
-
-== Core features
-
-Core features are provided with the iPOJO runtime bundles.
-You can use it directly, as soon as the iPOJO runtime is deployed.
-
-* xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/service-requirement-handler.adoc[How to require a service]
-* xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/providing-osgi-services.adoc[How to publish and provide a service]
-* xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/lifecycle-callback-handler.adoc[How to react to lifecycle state changes]
-* xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/configuration-handler.adoc[How to description component configuration]
-* xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/architecture-handler.adoc[How to enable/disable instance introspection]
-* xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/controller-lifecycle-handler.adoc[How to act on the instance state from the implementation]
-
-== Extensions
-
-Extensions _extend_ the iPOJO model to add a specific functionality.
-This is made thanks to the external handler mechanism.
-So before using one of these features, deploy the attached external handler.
-
-* xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/event-admin-handlers.adoc[How to receive and send events with the Event Admin]
-* xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/ipojo-jmx-handler.adoc[How to reconfigure instances with JMX]
-* xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/extender-pattern-handler.adoc[How to implement an extender pattern]
-* xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/white-board-pattern-handler.adoc[How to implement a whiteboard pattern]
-* xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/temporal-service-dependency.adoc[How to wait for services and inject proxies]
-
-== A missing functionality ?
-
-iPOJO component model is extensible.
-So, you can implement your own handler managing you specific requirement.
-Refer the handler development guide (xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/how-to-write-your-own-handler.adoc[How to write your own handler]) for more details.
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/Callback.jpeg b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/Callback.jpeg
deleted file mode 100644
index 13873dc..0000000
Binary files a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/Callback.jpeg and /dev/null differ
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/architecture-handler.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/architecture-handler.adoc
deleted file mode 100644
index bf9d371..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/architecture-handler.adoc
+++ /dev/null
@@ -1,65 +0,0 @@
-= Introspection and Architecture
-
-_The architecture feature allows obtaining an architectural / component view of your systems.
-It exposes a snapshot of the present instances & factories, the state of these instances...
-Moreover;
-iPOJO defines an 'arch' command displaying this architecture in Felix.
-You need to install xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-arch-command.adoc[the arch command]._
-
-
-
-== Reflection on component instances
-
-The architecture feature does "reflection" on the iPOJO containers.
-It gathers information about the component (state, class name ...), requirement (state, multiple, optional ...), provided services (state, properties) ...
-Each handler can participate to the architecture.
-This information allows you to know why an instance does not start, or why the component does not publish / provide a service.
-
-== Metadata
-
-The architecture (i.e.
-instance introspection) is activated by default.
-To disable it, you need to add an attribute `architecture="false"` to the component element:
-[source,xml]
- <component classname="org.apache.felix.ipojo.hello.impl.HelloServiceImpl" architecture="false">
-
-By default, the architecture feature is enabled.
-
-== The "arch" command
-
-The Gogo commands are the following:
-
-* `ipojo:instances` (or just `instances`) lists the instances and state
-* `ipojo:instance $instance_name` (or just `instance $instance_name`) displays the complete information about the specified $instance_name
-* `ipojo:factories` (or just `factories`) lists the available public factories
-* `ipojo:factory $factory_name` (or just `factory $factory_name`) displays complete information about the factory $factory_name
-* `ipojo:handlers` (or just `handlers` lists available handlers
-
-For example:
-
-[source,sh]
-----
-$ instances
-Instance ArchCommand -> valid
-Instance spell.english.EnglishDictionary-0 -> valid
-Instance spell.checker.SpellCheck-0 -> valid
-Instance spell.gui.SpellCheckerGui-0 -> valid
-
-$ instance spell.checker.SpellCheck-0
-instance component.type="spell.checker.SpellCheck" state="valid" bundle="8" name="spell.checker.SpellCheck-0"
- handler state="valid" name="org.apache.felix.ipojo.handlers.dependency.DependencyHandler"
- requires optional="false" aggregate="false" state="resolved" binding-policy="dynamic" specification="spell.services.DictionaryService"
- handler state="valid" name="org.apache.felix.ipojo.handlers.providedservice.ProvidedServiceHandler"
- provides service.id="36" state="registered" specifications="[spell.services.SpellChecker]"
- property value="spell.checker.SpellCheck" name="factory.name"
- property value="spell.checker.SpellCheck-0" name="instance.name"
- handler state="valid" name="org.apache.felix.ipojo.handlers.architecture.ArchitectureHandler"
-----
-
-More info on the `arch` command are available xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-arch-command.adoc[here].
-
-== Technical information
-
-In fact, when a component enables the architecture introspection, its container exposes an `Architecture` service.
-Any architecture requester can obtain information about the instance.
-For example, the arch command requests all the architecture services and prints the information.
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/configuration-handler.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/configuration-handler.adoc
deleted file mode 100644
index 93dca4c..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/configuration-handler.adoc
+++ /dev/null
@@ -1,181 +0,0 @@
-= Configuration Handler
-
-_This page presents how to configure component instances.
-This is managed by the configuration handler.
-This handler allows the configuration and dynamic reconfiguration of instances.
-A configuration is basically a set of couple (name, value).
-The name can be a field name or a property name associated to a field or/and a method.
-iPOJO also supports complex properties composed by maps, dictionaries, lists and arrays._
-
-
-
-== Configurable Properties
-
-To support configuration, the component type needs to declare which properties are configurable.
-These properties are not necessarily service properties but can be internal component properties.
-
-== Examples
-
-The following code depicts a simple configurable component.
-The 'm_foo' field will be injected using the 'foo' property, and will also be exposed as a service property.
-The `updateArray` method is a 'setter' method where the 'array' property will be injected.
-Properties injected into field are available in the constructor, setter method are available only after the constructor.
-
-[source,java]
-----
-@Component
-@Provides
-public class MyComponent implements MyService {
- @Property(name=".foo")
- private String m_foo;
-
- public MyComponent(@Property String message) {
- //...
- }
-
- @Property(name="array")
- public void updateArray(String[] array) {
- //...
- }
-}
-----
-
-The previous component can also be described using XML:
-[source,xml]
- <component classname="...MyComponent">
- <properties propagation="false"/>
- <property name=".foo" field="m_foo"/>
- <property name="array" method="updateArray"/>
- <property name="message" constructor-index="1"/>
- </properties>
- </component>
-
-The instance contains the configuration:
-[source,xml]
- <instance component="...MyComponent">
- <property name="foo" value="bar"/>
- <property name="array" value="{1, 2, 3}"/>
- <property name="message" value="hello"/>
- </instance>
-
-In the previous snippet, you can see three configurable properties.
-The first is a configurable property attached to the field 'foo' that is a service property too.
-The second is an array property attached to a method (updatArray).
-These three properties are configured by the instance configuration.
-
-By default all properties that do not start with the `.` (such as `.foo`) are _propagated_.
-Thus, properties are propagated to the service registration.
-It means that at each time that the configuration of the instance is updated;
-all properties contained in the configuration are propagated to the service registrations.
-For example, in the previous example, not only `foo` will be published but `array` are also published.
-To disable propagation use:
-
-[source,java]
- @Component(propagation=false)
-
-If a property has a method, this method is invoked each time that the property value changes (the method is called to push the initial value just after the constructor).
-The method receives one argument of the type of the property (an integer array in the example).
-
-When an instance is reconfigured, an updated callback can also be called:
-
-[source,java]
-----
-@Updated
-public void updated() {
- // The instance was reconfigured
-}
-
-// OR
-@Updated
-public void updated(Dictionary conf) {
- // The instance was reconfigured, conf is the new configuration.
-}
-----
-
-== Exposing a Managed Service
-
-The ManagedService is a service specified in the OSGi Compendium.
-It allows reconfiguring an instance with the Configuration Admin.
-There is two way for an iPOJO instance to expose a Managed Service.
-
-* In the `@Component` annotation the `managedservice` attribute defines the managed service PID.
-In XML this is done using the `pid` attribute in the properties element (XML)
-* In the instance configuration by configuring the `managed.service.pid` property
-
-So, using annotation, you should use the `managedservice` attribute as follow:
-
-[source,java]
-----
-@Component(managedservice="my.pid")
-public class MyComponent {
-
-}
-----
-
-In XML, the `pid` attribute of the `properties` element does the same job.
-[source,xml]
- <component classname="...MyComponent">
- <!-- ... -->
- <properties pid="my.pid"/>
- <!-- ... -->
- </properties>
- </component>
-
-Finally, instance may configure the managed service using the `managed.service.pid` configuration property:
-[source,xml]
- <instance component="...MyComponent">
- <property name="managed.service.pid" value="my.pid.2"/>
- </instance>
-
-=== ALERT SUCCESS Type vs. Instance configuration
-
-If the managed service pid is specified both in the component type and in the instance configuration, the instance configuration is used.
-
-The managed service pid is the identifier used by the Configuration Admin to attach configuration to Managed Services.
-First this pid must be unique (as any pid in OSGi).
-Moreover, this pid cannot be the same one that the pid used in the Managed Service Factory to create the instance (if you use this way to create your instance).
-
-When an instance is reconfigured with the Managed Service, the configuration is propagated if the propagation is enabled.
-
-== Dynamic Reconfiguration using Factories or ManagedServiceFactories
-
-iPOJO instances support dynamic reconfiguration.
-To reconfigure an instance you can use both iPOJO `Factory` and the `ManagedServiceFactory` services exposed by the factory of the targeted instance.
-By calling the method _reconfigure_ or _update_ (according of the service you use), the handler receive the new configuration and apply it.
-If the propagation is activated, the service registrations are updated too.
-If there is an `updated` callback, the callback is invoked.
-
-== Being notified when a reconfiguration is completed
-
-Sometimes you need to be notified when a reconfiguration is done (all setter method called).
-This can be done thanks to the `updated` attribute.
-This attribute specifies a method claeed when a configuration/reconfiguration is completed.
-This method receives a `Dictionary` containing the properties (pair <key,value>).
-Properties with no value are not in the received configuration.
-
-Updated callback are declared as follow using annotations:
-
-[source,java]
-----
-@Updated
-public void updated() {
- // The instance was reconfigured
-}
-
-// OR
-@Updated
-public void updated(Dictionary conf) {
- // The instance was reconfigured, conf is the new configuration.
-}
-----
-
-In XML, the method name is given as an attribute of the {\{properties}} element.
-[source,xml]
- <component className="...MyComponent">
- <!-- ... -->
- <properties updated="updated"/>
- <!-- ... -->
- </properties>
- </Component>
-
-The callback is called _AFTER_ the successful application of the reconfiguration.
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/controller-lifecycle-handler.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/controller-lifecycle-handler.adoc
deleted file mode 100644
index 41446bc..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/controller-lifecycle-handler.adoc
+++ /dev/null
@@ -1,61 +0,0 @@
-= Lifecycle Controller Handler
-
-_The lifecycle controller allows a component implementation to participate to the instance lifecycle.
-So, you can immediately decide to stop an instance if the configuration is incorrect (correct properties, accessible resources...).
-The licecyel controller impacts the instance lifecycle, if you want to impact only the registered service, have a look to the service controller (xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/providing-osgi-services.adoc[service providing]._
-
-
-
-== iPOJO instance lifecycle & Lifecycle controller
-
-Once started, iPOJO instances can be either valid or invalid.
-The decision comes from handlers.
-An instance is valid if every plugged handler are valid.
-Basically it means that all required services are available.
-As soon as one handler becomes invalid, the instance becomes invalid.
-
-The lifecycle controller just monitors a field inside the POJO class.
-When this field becomes `false`, the handler becomes invalid, and so the instance becomes invalid.
-When the field get the `true` value, the handler becomes valid, and if all handlers are valid, the instance becomes valid.
-
-== An example
-
-Imagine the following component :
-
-[source,java]
-----
-@Component
-public class LifecycleControllerTest {
-
- @Controller
- private boolean m_state;
-
- @Property
- public void setConf(String newConf) {
- System.out.println("setConf : " + newConf);
- if (newConf.equals("a correct value")) {
- m_state = true; // update controller value.
- } else {
- m_state = false; // update control value
- }
- }
-}
-----
-
-If you don't want to use annotations, the following snippet does the same job using XML:
-[source,xml]
- <component
- classname="org.apache.felix.ipojo.test.scenarios.component.LifecycleControllerTest">
- <controller field="m_state"/>
- <properties>
- <property name="conf" method="setConf"/>
- </properties>
- </component>
-
-The component requires the `conf` property.
-iPOJO checks if this property is inside the pushed configuration, but cannot checks if the configuration is correct according to the component semantic.
-When the instance is created, the `setConf` method is called with the given value.
-If the given `conf` property is "valid" the `m_state` field (i.e.
-the controller) is set to `true`.
-Else, the `m_state` is set to `false`.
-It means that the lifecycle controller handler becomes invalid and as a consequence, the instance becomes invalid.
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/event-admin-handlers.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/event-admin-handlers.adoc
deleted file mode 100644
index 9426e07..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/event-admin-handlers.adoc
+++ /dev/null
@@ -1,345 +0,0 @@
-= Event Admin Handlers
-
-_The goal of the Event Admin Handlers is to allow event communications between iPOJO component instances.
-The implementation of these handlers relies on an event admin services.
-It enables the iPOJO component to listen to a list of topics and to receive all related events.
-It also allows components to send events in an easy way._
-
-ALERT:: The 1.2.0 version use the namespace : `org.apache.felix.ipojo.handlers.event` instead of `org.apache.felix.ipojo.handlers.event.EventAdminHandler`.
-
-WARNING: *change in the 1.7.0*
-
-The `@Publisher` annotation is now deprecated and replaced by `@Publishes`.
-
-== An example
-
-Hereafter is presented a small example :
-
-[source,java]
-----
-@Component
-@Instantiate
-public class MyComponent {
-
- @Publishes( // or @Publisher before the 1.7.0
- name="myPublisher",
- topics="bar,nuts")
- private Publisher m_publisher;
-
- @Subscriber(
- name="mySubscriber",
- topics="foo")
- public void receive(Event e) {
- // Event received
- // Do something with the event
- }
-}
-----
-
-This component can also be described using the XML formalism:
-[source,xml]
- <ipojo
- xmlns:ev="org.apache.felix.ipojo.handlers.event">
- <component className="...MyComponent">
- <ev:subscriber
- name="mySubscriber"
- callback="receive"
- topics="foo"/>
- <ev:publisher
- name="myPublisher"
- field="m_publisher"
- topics="bar,nuts"/>
- </component>
- <instance component="...MyComponent"/>
- </ipojo>
-
-In XML, you need to specify the namespace of the Handler.
-You can find here one event subscriber (named mySubscriber) and one event publisher (named myPublisher).
-In these handler configurations, the name parameter is mandatory.
-The topics parameter is optional as it can be specified in the instance configuration.
-The callback parameter of the mySubscriber element is mandatory and indicates the method that handles received events.
-In this case, this method must have a single argument of type org.osgi.service.event.Event.
-The field parameter of the myPublisher element indicates the field (of type org.apache.felix.ipojo.handlers.event.publisher.Publisher) that is used by the POJO to send events on the specified topics.
-All type compliance will be checked by the handler at component instantiation time.
-
-== Download
-
-The event admin handlers (to send and receive events) are available in the Felix trunk in the iPOJO project.
-See the link:{{ refs.download.path }}[Download] page to download and compile these sources.
-
-== How does it work?
-
-The handler will parse the description provided in the metadata, and register for you the EventHandler in the OSGi Registry.
-On one hand, your POJO will receive each event through the handler.
-With this handler you can specify different callback methods for different topics.
-On the other side, the handler instantiates and injects configured Publisher references in your POJO, so you can send events transparently through these publishers.
-
-== EventHandler Specification
-
-Here you can find all configuration options of the EventAdmin handler.
-As seen before, the handler contains two components : the event subscriber and the event publisher.
-These components can be configured, using several attributes, as described below.
-Some of these attributes can be (re)defined in the instance configuration.
-
-_Handler namespace :_ _org.apache.felix.ipojo.handlers.event_
-
-=== Event subscriber attributes
-
-|===
-| Attribute name | Required | Description
-
-| name
-| yes
-| The name of the event subscriber, acting as a unique identifier.
-
-| callback
-| yes
-| The name of the POJO's method that will be called each time an event is received.
-This method takes only one parameter, of type `org.osgi.service.event.Event` by default, but this type can be overridden by defining the data-key and/or the data-type attributes.
-
-| topics
-| yes
-| The comma-separated-list of the topics that the handler will listen to.
-Each event sent on a topic present in this list will be sent to the specified callback method.
-The topics can be set in the instance configuration.
-
-| filter
-| no
-| The event filter is used to filter incoming events before sending them to the callback.
-The syntax of this field is described in the OSGi Event Admin Specification.
-If you don't specify a filter, all events sent on the listened topics will be considered.
-The filter can be set in the instance configuration.
-
-| data-key
-| no
-| The data key is used when you want to receive data events.
-This attribute's value is the key corresponding to the received data in the event's dictionary.
-If you use this attribute, the parameter passed to the callback method is the the value associated to this key, not the whole event.
-This attribute is generally used with the **data-type** attribute to specify the received object type.
-If an event is received and it does not contain such a key, it is ignored (with a warning message).
-
-| data-type
-| no
-| This attribute is associated to the data-key attribute.
-It specifies the type of objects (`java.lang.Object` by default) that the callback expects.
-It is used to determine the unique callback method (in case of multiple methods with the same name) and to check type compliance at event reception.
-Data events that are not corresponding to the specified type will be ignored (with a warning message).
-|===
-
-=== Event publisher attributes
-
-|===
-| Attribute name | Required | Description
-
-| name
-| yes
-| The name of the event publisher, acting as a unique identifier.
-
-| field
-| yes
-| The name of the POJO's field that will be used to send events.
-The field is initialized at component instantiation time.
-The type of the field must be : `org.apache.felix.ipojo.handlers.event.publisher.Publisher`.
-Despite it creates a dependency between the component code and the handler, this system allows hiding the whole complexity of event sending.
-
-| topics
-| yes
-| The comma-separated-list of the topics on which events will be sent.
-Topics can be set in the instance configuration
-
-| data-key
-| no
-| The data key is used when you want to send data events.
-This attribute's value is the key, in the event's dictionary, in which sent data are stored.
-When you use the `sendData` method of the Publisher, the given object is placed in the event dictionary, associated with the specified data-key.
-The default value of this attribute is `user.data`.
-
-| synchronous
-| no
-| Determines if event sending is synchronous or not.
-By default, events are sent asynchronously, but you can specify there the desired behaviour of the Publisher.
-|===
-
-=== Instance configuration
-
-Some of the described attributes can be (re)defined in the instance configuration section of your metadata file.
-Its permits to configure event management instance by instance.
-The following properties are used by the handler :
-
-* _event.topics_ : overrides _topics_ attribute, available for both subscribers and publishers configuration
-* _event.filter_ : overrides _filter_ attribute, available for subscribers configuration only.
-
-=== Publisher interface
-
-The Publisher interface is the link between the component code and the handler.
-It permits to publish events on the topics specified in the component's description (or instance configuration).
-The implemented methods are :
-
-* `public void send(Dictionary content)` : This method is used to send a standard event, with the specified content.
-Some specific properties may be added in the content to satisfy EventAdmin specification (e.g., event.topic).
-* `public void sendData(Object o)` : This method is the easier way to send data.
-The given object is placed in the event dictionary according to the _data-key_ attribute (or its default value).
-Then, this dictionary is sent as a regular event.
-
-== Handler Architecture
-
-Here is shown the global architecture of the EventHandler : the interactions between the user components (i.e., POJO), the handler and the OSGi runtime environment.
-
-image::documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/handler-arch.png[]
-
-== EventHandler Features
-
-In this section, you will find some examples of the handler's features.
-
-=== Instance customization
-
-As described in the 'Instance configuration' section, you can (re)define some of the subscribers or publishers attributes.
-You can notice that required attributes that are not defined in the component description must be defined in the instance configuration section.
-Hereafter is an example of an instance configuration of this handler :
-[source,xml]
- <ipojo>
- <instance component="...MyComponent">
- <property name="event.topics">
- <property name="mySubscriber" value="foo"/>
- <property name="myPublisher" value="bar,nuts"/>
- </property>
- <property name="event.filter">
- <property name="mySubscriber"
- value="|((arg=Minibar)(arg=Coconuts))"/>
- </property>
- </instance>
- </ipojo>
-
-=== Data events
-
-One of the most important features of the EventHandler is the capability of sending and receiving data events.
-You may know that the OSGi EventAdmin Service allows bundles to send custom objects in events, inserting them in the event's dictionary.
-The EventHandler hides the dictionary manipulation and allows iPOJO components to receive custom objects at any time.
-
-First, you have define the _data-key_ attribute in the publisher configuration (`dataKey` in annotations).
-Sent objects will be contained in the event dictionary and are accessible with the "user.data" key.
-[source,xml]
- <ipojo
- xmlns:ev="org.apache.felix.ipojo.handlers.event">
- <component className="...DataPublisher">
- <ev:publisher
- name="myPublisher"
- field="m_publisher"
- topics="myTopic"
- data-key="my.data"/>
- </component>
- <instance component="...DataPublisher"/>
- </ipojo>
-
-Then you can use the _sendData_ method of your configured publisher.
-
-[source,java]
-----
-import org.apache.felix.ipojo.handlers.event.publisher.Publisher;
-//...
-public class DataPublisher ... {
- private Publisher m_publisher;
-
- public void doSomething() {
- // MyFavoriteType extends MyFavoriteInterface
- MyFavoriteType data = new MyFavoriteType(...);
- //...
- // Send a data event
- m_publisher.sendData(data);
- }
-}
-----
-
-The second step is to configure an event subscriber to receive such events.
-The _data-key_ attribute's value of the subscriber must be the same than the publisher's one.
-The _data-type_ describes the type of received data events, and thus, must be compatible with the sent object's type (i.e., super-class or inherited interface).
-Then you can finally receive the sent object in the callback method.
-The parameter type of the callback must be the same than the data-type attribute value.
-[source,xml]
- <ipojo
- xmlns:ev="org.apache.felix.ipojo.handlers.event">
- <component className="...DataEventSubscriber">
- <ev:subscriber
- name="mySubscriber"
- callback="handleData"
- topics="myTopic"
- data-key="my.data"
- data-type="my.package.MyFavoriteInterface"/>
- </component>
- <instance component="...DataEventSubscriber"/>
- </ipojo>
-
-
-
-[source,java]
- import my.package.MyFavoriteInterface;
- //...
- public class DataEventSubscriber ... {
- public void handleData(MyFavoriteInterface o) {
- // Object received
- //...
- }
- }
-
-Annotations use a different set of attributes:
-
-* data-key is replaced by `dataKey`
-* data-type is replaced by `dataType`
-
-=== Note on synchronous event sending
-
-By default, events are sent using asynchronous sending (a.k.a._post_ in OSGi EventAdmin).
-You can use synchronous sending by defining the _synchronous_ attribute of your publisher to true.
-
-The behavior of synchronous event sending is particular when you specify several topics in the publisher description.
-The event is synchronously sent to each topic, one by one.
-So when you return from this function, you can be sure that the event has been delivered to each topic.
-
-=== Publisher instance information
-
-All events sent by a publisher contains the name of the component instance that sent them.
-Its enables to filter received events depending the sender instance.
-The instance name is accessible in the event dictionary by the key _publisher.instance.name_.
-Despite it goes against MOM principles, this property is useful to trace events and especially event sources.
-
-=== Configuring the handler with annotations
-
-It is possible to configure the handler with a simple annotations available in the annotation pack ('annotation' project in the iPOJO trunk).
-Here is an example of usage:
-
-[source,java]
-----
-import org.apache.felix.ipojo.annotations.Component;
-import org.apache.felix.ipojo.handlers.event.Subscriber;
-import org.apache.felix.ipojo.handlers.event.Publishes;
-import org.apache.felix.ipojo.handlers.event.publisher.Publisher;
-import org.osgi.service.event.Event;
-
-
-@Component
-public class PubSub {
- @Publishes(name="p1", synchronous=true)
- Publisher publisher1;
-
- @Publishes(name="p2", synchronous=false, topics="foo,bar", data_key="data")
- Publisher publisher2;
-
- @Publishes(name="p3", synchronous=true, topics="bar")
- Publisher publisher3;
-
- @Subscriber(name="s1", data_key="data")
- public void receive1(Object foo) {
- // Process event
- }
-
- @Subscriber(name="s2", topics="foo,bar", filter="(foo=true)")
- public void receive2(Event foo) {
- // Process event
- }
-
- @Subscriber(name="s3", topics="foo", data*key="data", data*type="java.lang.String")
- public void receive3(String foo) {
- // Process event
- }
-}
-----
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/extender-pattern-handler.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/extender-pattern-handler.adoc
deleted file mode 100644
index 5103874..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/extender-pattern-handler.adoc
+++ /dev/null
@@ -1,148 +0,0 @@
-= The Extender Pattern handler
-
-_The objective of this handler is to simplify the development of extender-based architecture.
-This architecture-style is based on two different entities:_
-
-* _The extender (also called host)_
-* _The extensions_
-
-
-
-== The Extender pattern
-
-This architecture-style is based on two different roles:
-
-* The extender
-* The extension
-
-image::documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/extender.png[]
-
-The relation is basically a 1..n relation.
-The extender tracks extensions.
-The particularity of this architecture-style is that extensions are packaged in different bundles.
-An extension is detected by analyzing the bundle.
-Indeed these bundles can have a special mark in their manifest of a special file...
-Implementing an extender pattern could be complex as the extender needs to track these marks dynamically.
-When a bundle starts, it needs to look at the mark.
-Then a bundle leave, the extender must release all object created from this bundle.
-This handler tracks bundle for you based on the specified required mark.
-At each time a matching bundle appears or disappears, a callback is invoked.
-The mark is currently a header in the bundle manifest.
-Nowadays, a lot of frameworks use this pattern such as iPOJO it-self (to find both bundles containing components and bundles adding a new implementation type), Spring-DM ...
-
-== Using the handler
-
-First of all, you need to configure the component type to use the handler such as:
-
-[source,xml]
-----
-<ipojo xmlns:extender="org.apache.felix.ipojo.extender">
- <component
- classname="org.apache.felix.ipojo.extender.MyExtender">
-
- <!-- Extender Pattern handler configuration -->
- <extender:extender
- extension="My-Extension"
- onArrival="onBundleArrival"
- onDeparture="onBundleDeparture"
- />
-
- <callback transition="invalidate" method="stopping" />
- <callback transition="validate" method="starting" />
- <provides />
- </component>
-</ipojo>
-----
-
-Notice that, this handler is an external handler.
-So, it uses the "org.apache.felix.ipojo.extender" namespace.
-You can also use annotations:
-
-[source,java]
-----
-@Component
-@Extender(
- onArrival="onBundleArrival",
- onDeparture="onBundleDeparture",
- extension="My-Extension")
-public class MyExtender {
-
- @Validate
- public void starting() {
- // ...
- }
-
- @Invalidate
- public void stopping {
- // ...
- }
-
- void onBundleArrival(Bundle bundle, String header) {
- // Do something
- }
-
- void onBundleDeparture(Bundle bundle) {
- // Do something
- }
-}
-----
-
-The methods specified methods will be called when a matching bundle arrives or leaves.
-In the previous example, these methods could be:
-
-[source,java]
-----
-void onBundleArrival(Bundle bundle, String header) {
- // Do something
-}
-
-void onBundleDeparture(Bundle bundle) {
- // Do something
-}
-----
-
-Notice the different signatures of the methods.
-The arrival method is called with the arriving bundle and the matching header value (i.e.
-the value of the My-Extension header of the bundle manifest).
-The departure method just receives the leaving bundle.
-
-== Configuration
-
-The handler has only three mandatory attributes:
-
-* Extension: declaring the looked manifest header.
-* onArrival: declaring the method to invoke when a matching bundle arrives
-* onDeparture: declaring the method to invoke when a matching bundle leaves
-
-*Called despite being invalid*
-
-== Configuring the handler with annotations
-
-It is possible to configure the handler with a simple annotation available in the annotation pack ('annotations' project in the iPOJO trunk).
-Here is an example of usage:
-
-[source,java]
-----
-import org.apache.felix.ipojo.annotations.Component;
-import org.osgi.framework.Bundle;
-
-@Component
-@org.apache.felix.ipojo.extender.Extender(extension="foo", onArrival="onArrival", onDeparture="onDeparture")
-public class Extender {
-
- public void onArrival(Bundle bundle, String foo) {
- // do something
- }
-
- public void onDeparture(Bundle bundle) {
- // do something
- }
-}
-----
-
-The `extension` attribute allows setting the bundle filter.
-
-== A more realistic example
-
-The Junit4OSGi framework, available https://svn.apache.org/repos/asf/felix/trunk/ipojo/examples/junit4osgi[here], uses this handler to track Junit Test Suite offered by the installed bundles.
-The Junit4Osgi bundle has a component using this handler to be notified when a bundle with the `Test-Suite` header appears or leaves.
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/injecting-bundle-context.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/injecting-bundle-context.adoc
deleted file mode 100644
index 4453292..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/injecting-bundle-context.adoc
+++ /dev/null
@@ -1,72 +0,0 @@
-= Accessing the Bundle Context
-
-_Despite iPOJO hides most of the OSGi mechanisms, you often need to access the `Bundle Context`.
-This page explains how you can access to the bundle context from your component code._
-
-
-
-== Bundle Context
-
-The `BundleContext` is an object provided by the OSGi Framework to access services as well as resources contained in bundles.
-Using the bundle context is often required in the later case, i.e.
-loading files contained in the bundle.
-The API of the bundle context is available http://www.osgi.org/javadoc/r4v43/core/org/osgi/framework/BundleContext.html[here].
-
-== Retrieving the Bundle Context as constructor parameter
-
-The first way to retrieve the bundle context is as a constructor parameter:
-
-[source,java]
- public MyComponent(BundleContext context) {
- // context is the bundle context
- }
-
-With such way, the bundle context of the bundle declaring the component is injected.
-Notice that such injection can be mixed with other constructor injection such as `@Requires` for service dependencies and `@Property` to configuration property.
-
-== Using `@Context` (version 1.11.2+)
-
-The second way to retrieve the `Bundle Context` uses a _bundle context handler_ responsible for injecting the bundle context.
-This handler let you inject the bundle context in a field, in a setter method or as constructor parameter:
-
-[source,java]
-----
-@Component
-public MyComponent {
- /**
- * Field injection.
- */
- @Context
- private BundleContext context;
-
- /**
- * Constructor injection, equivalent to the the previous approach.
- */
- public MyComponent(@Context BundleContext context) {
- // ...
- }
-
- /**
- * Method injection.
- */
- @Context
- public void setBundleContext(BundleContext context) {
- // ...
- }
-}
-----
-
-The `@Context` annotation takes an optional parameter indicating which `Bundle Context` has to be injected.
-By default it injects the `component` bundle context, meaning the bundle context of the bundle declaring the component.
-But, you can asks iPOJO to injects the `instance` bundle context, i.e.
-the bundle context of the bundle declaring the instance:
-
-[source,java]
- @Component
- public MyComponent {
- /**
- * Injects the instance bundle context
- */
- @Context(Context.Source.INSTANCE)
- private BundleContext context;
- }
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/ipojo-jmx-handler.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/ipojo-jmx-handler.adoc
deleted file mode 100644
index 4ba16ad..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/ipojo-jmx-handler.adoc
+++ /dev/null
@@ -1,291 +0,0 @@
-= iPOJO JMX Handler
-
-_This handler provides JMX management of component instance.
-It could be useful to manage instance remotely.
-As the handler exposes MBeans, you must have a MBean server running on your platform (as the platform MBean server or the MOSGi MBean Server)._
-
-
-
-== Features
-
-The handler allows to:
-
-* Expose attributes accessible via JMX (with right management).
-* Expose methods to be called through JMX.
-* Get notifications when attributes are modified .
-
-== Prerequisites
-
-To be functional this handler must register on an MBean Server,thus you obviously need it.
-Several servers are currently supported : the standard platform MBean server (included in the Java Virtual Machine since version 5), MOSGi (Apache Felix sub-project), ...
-
-== Download
-
-The JMX handler is available in the Felix trunk in the iPOJO project.
-See the link:{{ refs.download.path }}[Download] page to download and compile these sources.
-
-== How to use it
-
-The handler needs to be added in the metadata.xml, you just add a namespace (e.g., jmx) :
-[source,xml]
- <ipojo xmlns:jmx="org.apache.felix.ipojo.handlers.jmx">
- ...
- </ipojo>
-
-So, you could now expose in JMX properties and methods of your component.
-They are surrounded by the <jmx:config>tag.
-[source,xml]
- <jmx:config>
- <jmx:property name="message" field="m_msg" rights="w" notification="true"/>
- <jmx:method name="doSomethingBad"/>
- <jmx:method name="doSomethingGood"/>
- </jmx:config>
-
-[discrete]
-==== ALERT Serialization
-
-Be careful that the argument and return type of methods must be serializable.
-In case of several methods have the same name, each of them will be exposed.
-
-== JMX Handler options
-
-Here you can find all configuration options of the JMX handler.
-There are two kinds of manageable elements : properties and methods.
-First is described the global configuration of the handler.
-Then elements can be configured, using several attributes, as described below.
-
-== Global handler attributes
-
-|===
-| Attribute name | Required | Description
-
-| objectName
-| No
-| The complete object name of the managed component.
-The syntax of this attribute must be compliant with the ObjectName syntax, detailed in the JMX specification.
-If neither domain nor name attributes are specified, the default value is determined by the package, the type and the instance name of the component.
-This attribute overrides the domain and name attributes.
-_Example:_ `"my.domain:type=myType,name=myName"`
-
-| domain
-| No
-| The domain of the managed object (i.e., the left part of the object name).
-This attribute must be compliant with the domain syntax, as described in the JMX specification.
-_Example:_ `"my.domain:type=myType,name=my.domain"`
-
-| name
-| No
-| The name property of the managed object.
-The value of this attribute must comply with the ObjectName value syntax, as described in the JMX specification.
-
-| usesMOSGi
-| No
-| Determines if the component must be register on the MOSGi MBean server or not.
-
-| preRegister, postRegister, preDeregister, postDeregister
-| No
-| These attributes allow to specify methods to carry out operations before and after being registered or unregistered from the MBean server.
-|===
-
-== Properties attributes
-
-+++<table class="table table-bordered">++++++<thead>++++++<tr>++++++<th>+++Attribute name+++</th>+++
- +++<th>+++Required+++</th>+++
- +++<th>+++Description+++</th>++++++</tr>++++++</thead>+++
- +++<tbody>++++++<tr>++++++<td>+++field+++</td>+++
- +++<td>+++Yes+++</td>+++
- +++<td>+++The name of the component's field to expose.+++</td>++++++</tr>+++
-
- +++<tr>++++++<td>+++rights+++</td>+++
- +++<td>+++No+++</td>+++
- +++<td>+++The domain of the managed object (i.e., the left part of the object name). This attribute must be compliant with the domain syntax, as described in the JMX specification. +++<em>+++Example:+++</em>+++ +++<code>+++"my.domain:type=myType,name=my.domain"+++</code>++++++</td>++++++</tr>+++
-
- +++<tr>++++++<td>+++name+++</td>+++
- +++<td>+++No+++</td>+++
- +++<td>+++Specify the access permission of the exposed field. The accepted values are :
- +++<ul>++++++<li>+++"r" : read-only access, the default value.+++</li>+++
- +++<li>+++"w" : read and write access.+++</li>++++++</ul>++++++</td>++++++</tr>+++
-
- +++<tr>++++++<td>+++notification+++</td>+++
- +++<td>+++No+++</td>+++
- +++<td>+++Enable or disable attribute change notification sending for this property. If set to `true`, a notification is sent each time the value of the field changes.+++</td>++++++</tr>++++++</tbody>++++++</table>+++
-
-== Methods attributes
-
-|===
-| Attribute name | Required | Description
-
-| name
-| Yes
-| The name of the method to expose.
-If multiple methods have the same name, all of them are exposed.
-
-| description
-| No
-| The description of the exposed method, as it will appear in JMX.
-|===
-
-== Examples
-
-In this part, we will give you a complete example of a component managed with JMX, using the JConsole provided by the SUN JDK.
-
-=== Exposing Attributes
-
-In first time we create a simple component named MyComponent.
-We have add two fields named m__level (int) and m__message (String).
-
-[source,java]
- public class MyComponent ... {
- // Exposed attributes
- private String m_message;
- private int m_level;
- }
-
-We expose now the attributes in the jmx:config tag in the metadata :
-
-[source,xml]
-----
-<?xml version="1.0" encoding="UTF-8"?>
-<iPOJO xmlns:jmx="org.apache.felix.ipojo.handlers.jmx">
- <component className="...MyComponent"
- architecture="true"
- immediate="true">
-
- <provides/>
- <jmx:config>
- <!-- Exposed properties -->
- <jmx:property field="m_level"
- name="The level"
- rights="r"/>
- <jmx:property field="m_message"
- name="The message"
- rights="w"/>
- </jmx:config>
- </component>
- <instance
- component="...MyComponent"/>
-</iPOJO>
-----
-
-Now, we could get and write the properties in the JConsole :
-
-image::documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/JMXHandler_1.png[]
-
-=== Exposing Methods
-
-We could now add methods in the initial class :
-
-[source,java]
-----
-/**
-Do something good
-*/
-public void doSomethingGood() {
- ...
-}
-
-/**
-Do something bad
-*/
-public void doSomethingBad() {
- ...
-}
-
-/**
-Do nothing
-*/
-public void doNothing() {
- ...
-}
-----
-
-We add corresponding tags in the metadata to expose these methods:
-[source,xml]
- <!-- Exposed methods -->
- <jmx:method name="doSomethingGood"
- description="Do something good."/>
- <jmx:method name="doSomethingBad"
- description="Do something bad."/>
- <jmx:method name="doNothing"
- description="Do absolutely nothing."/>
-
-Now the three methods are exposed in the operations tab of the JConsole.
-We can invoked these methods :
-
-image::documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/JMXHandler_2.png[]
-
-=== Attribute Notifications:
-
-You could subscribe to attribute notification by adding the notification attribute in property tag.
-In our example if we want to be notified when m_level is modified, we change the property line in the metatada like this:
-[source,xml]
- <jmx:property field="m_level"
- name="The level"
- rights="r"
- notification="true"/>
-
-So now if we change the string through JConsole (or in the VisualVM) or if the POJO is modified in other way, a notification will be sent to every listener.
-For example, we subscribe in the notification tab, and we get notification when the message changes :
-
-image::documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/JMXHandler_3.png[]
-
-== Configuring the handler with annotations
-
-It is possible to configure the handler with simple annotations available with iPOJO annotations.
-Here is an example of usage:
-
-[source,java]
-----
-import org.apache.felix.ipojo.annotations.Component;
-import org.apache.felix.ipojo.handlers.jmx.Config;
-import org.apache.felix.ipojo.handlers.jmx.Method;
-import org.apache.felix.ipojo.handlers.jmx.Property;
-
-@Component
-@Config(domain="my-domain", usesMOSGi=false)
-public class JMXSimple {
-
- @Property(name="prop", notification=true, rights="w") // Field published in the MBean
- String m_foo;
-
- @Method(description="set the foo prop") // Method published in the MBean
- public void setFoo(String mes) {
- System.out.println("Set foo to " + mes);
- m_foo = mes;
- }
-
- @Method(description="get the foo prop") // Method published in the MBean
- public String getFoo() {
- return m_foo;
- }
-}
-----
-
-The `@org.apache.felix.ipojo.handlers.jmx.Config` (`@Config` if the package it correctly imported) annotation is a type annotation (so placed on the `class` element.
-This annotation indicates that the instance will be exposed as an MBean.
-This annotation supports:
-
-* usesMOSGi: set to `true` to use MOSGi.
-Otherwise, the MBean will be exposed in the MBean Platform Server (default: `false`).
-* objectname: set the MBean objectname.
-The objectname must follow JMX specification.
-(default: `package-name:factory-name:instance-name`)
-* domain: set the MBean domain.
-(default: `package-name`)
-* name: set the MBean name.
-(default: `instance-name`).
-
-The `@org.apache.felix.ipojo.handlers.jmx.Property` (`@Property`) annotation is a field annotation indicating that the field is exposed in the MBean.
-The supported attributes are:
-
-* name: set the property name
-* rights: set the access permission.
-Possible values are `r` (read only) and `w` (read and write).
-By default, properties are in read-only mode.
- ** notification: enables notification on this property.
-By default notifications are disabled.
-
-The `@org.apache.felix.ipojo.handlers.jmx.Method` annotation is a method annotation indicating that the method is exposed in the MBean.
-Only one attribute can be customized:
-
-* description: set the method description.
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/lifecycle-callback-handler.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/lifecycle-callback-handler.adoc
deleted file mode 100644
index 437d0c7..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/lifecycle-callback-handler.adoc
+++ /dev/null
@@ -1,168 +0,0 @@
-= Lifecycle callbacks
-
-_It is often necessary to create a POJO object as soon the instance becomes valid (i.e.
-required services are available).
-It is also often needed to be able to stop it nicely.
-This pages presents the iPOJO capabilities to achieve such actions.
-iPOJO allows you to invoke methods (callbacks) on the POJO object when instance's state changed.
-For example, it allows invoking a `start` method when the instance becomes valid and a `stop` method when the instance becomes invalid.
-It allows the creation of `immediate` component.
-This page presents how to use this handler._
-
-
-
-== Instance Lifecycle
-
-iPOJO instances have a very simple lifecycle.
-This lifecycle contains two states: `INVALID` and `VALID`.
-Once an instance is created, this instance can only be valid if all its plugged handlers are valid.
-In the most basic case it means all required services are available.
-For example, an instance requiring a service (and so using the dependency handler) cannot be valid if the required service is unavailable.
-
-An instance starts and stops in the invalid state.
-
-image::documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/lifecycle.png[,25%]
-
-== Lifecycle callback
-
-This handler supports two kinds of callback.
-The INVALID\=>VALID callback are invoked when the instance becomes valid (at starting or when an event allows the instance to become valid).
-The VALID\=>INVALID callback are invoked when the instance becomes invalid (at stopping or when an event invalids the instance).
-
-image::documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/callback.png[,10%]
-
-== An example
-
-Let's take an example.
-The following class requires a FooService and has two lifecycle callbacks: start and stop.
-
-[source,java]
-----
-@Component
-@Instantiate
-public class Foo {
- @Requires
- FooService fs;
-
- @Validate
- private void start() {
- // Starting method
- //...
- fs.foo();
- //...
- }
-
- @Invalidate
- protected void stop() {
- // Stopping method
- if(fs!=null) { fs.foo(); }
- }
-}
-----
-
-You can also remove the annotations to use the XML format:
-[source,xml]
- <component className="...Foo">
- <requires field="fs"/>
- <callback transition="validate" method="start"/>
- <callback transition="invalidate" method="stop"/>
- </component>
- <instance component="...Foo"/>
-
-When an instance of this component type is created, the start method is called as soon as the `Foo` Service (service requirement) becomes available.
-If the `Foo` Service is no more available or when the instance is stopped, the stop method is called.
-
-The invoked methods have no argument, but could be private, protected or public.
-Public methods can be in parent classes too.
-Moreover, the `+INVALID=>VALID+` (validate) method can use service dependencies (the instance becomes valid means that all required services are available);
-however, in the stop method (invalidate) it is possible that one of these dependency can be `null`.
-Indeed, the departure of a service can be the cause of the instance invalidation.
-
-== Managing threads
-
-One usage of lifecycle callback is when the instance needs to create threads.
-Indeed, the thread can be created in the validate callback, and stopped in the invalidate method.
-The next class shows an example of a class handling a thread by using lifecycle callbacks.
-
-[source,java]
-----
-@Component
-@Instantiate
-public class HelloRequesterImpl implements Runnable {
-
- final static int DELAY=10000;
-
- @Requires
- HelloService[] m_hello; // Service Dependency
-
- boolean end;
-
- public void run() {
- while (!end) {
- try {
- synchronized (this) {
- for(int i = 0; i < m_hello.length; i++) {
- System.out.println(m_hello[i].sayHello("Clement"));
- }
- }
- Thread.sleep(DELAY);
- } catch (InterruptedException ie) {
- /* will recheck quit */
- }
- }
- }
-
- @Validate
- public void starting() {
- Thread T = new Thread(this);
- end = false;
- T.start();
- }
-
- @Invalidate
- public void stopping() { end = true; }
-----
-
-== Invalidate callbacks and services
-
-The invalidate callback has to be developed defensively.
-Indeed, inside this callback, it might be possible that a service is no more there (the departure of this service has thrown the instance invalidation, which calls the callback).
-So, you must check that the service is not `null` before using it:
-
-[source,java]
- @Invalidate
- public void stop() {
- if (myservice != null) {
- // you can use the service
- }
- // ...
- }
-
-Thanks to the iPOJO synchronization model, you can be sure that if the service is available, it will be there until the end of the method.
-
-== Immediate component
-
-An instance of an `immediate` component type is instantiated as soon it becomes valid.
-It means that, when the instance becomes valid, the constructor of the implementation class is called.
-This can replace the validate callback.
-However, it stills a difference between the immediate and the validate callback.
-The constructor is call only once time.
-The validate callback is re-called each time the instance becomes valid.
-Components that do not provide services are automatically set as immediate.
-
-image::documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/constructor.png[]
-
-To set a component as immediate you must add the `immediate` attribute to `component`:
-
-[source,java]
- @Component(immediate=true)
- @Instantiate
- public class MyComponent implements MyService {
- // ...
- }
-
-However as there is no 'destructor' in Java, the invalidate callback is necessary if some actions are needed when stopping.
-
-== Callback on several objects
-
-If you instance has created several objects (called the implementation class constructor several times), the callback is called on each object in the creation order.
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/providing-osgi-services.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/providing-osgi-services.adoc
deleted file mode 100644
index 43e2966..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/providing-osgi-services.adoc
+++ /dev/null
@@ -1,435 +0,0 @@
-= Providing OSGi services
-
-_This pages explains how to publish OSGi services with iPOJO.
-It presents:_
-
-* _service publication_
-* _service properties publication and management_
-* _service object creation and creation strategies_
-* _service un-registration_
-* _configuration property propagation_
-* _the management of the exposition from the implementation class_
-
-
-
-== A simple example
-
-The following code snippet shows a simple class implementing the `FooService` interface:
-
-[source,java]
-----
-@Component
-@Provides
-public class FooProviderType1 implements FooService {
- private String m_foo = "foo";
-
- public void foo() {
- System.out.println("foo " + m_foo);
- }
-
-}
-----
-
-To provide a service, the implementation class _MUST_ implement the service interface.
-
-In XML, to provide the service, the component type needs to contain the `<provides/>` element:
-[source,xml]
- <component className="...FooProviderType1">
- <provides/>
- </component>
-
-image::documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/ps-foo.png[]
-
-The `<provides/>` or `@Provides` suffice to declare that each instance of this type will provide the FooService (for more info about instances see 'xref:documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/how-to-use-ipojo-factories.adoc[How to use iPOJO factories]`).
-The provided specifications can be discovered by analyzing the implementation class.
-By default, all implemented interface are published in the same service registration.
-iPOJO looks down the entire inheritance tree.
-
-== Service Publication
-
-The provided service handler manages service publication.
-For each declared `<provides/>`, the handler registers a service.
-Since the `@Provides` annotation can be used only once, only one service is registered that provides all interfaces.
-The service is published as long as the instance is valid.
-If the instance becomes invalid, the service is removed from the service registry.
-
-By default, it publishes all interfaces implemented by the implementation class of the component class.
-It collects all super-interfaces (interfaces implemented by implemented interfaces and by the super class).
-However, it is possible to explicitly declare which service specifications are published with the `specifications` attribute, such as:
-
-[source,java]
- @Component
- @Provides(specifications={FooService.class})
- public class FooProviderType1 implements FooService, Runnable {
- // ...
- }
-
-=== Specification checking
-
-If you use the `specifications` attribute, the handler checks that all declared interfaces are really implemented by the implementation class.
-If an interface is not implemented, the handler logs a warning.
-
-=== No service
-
-If the implementation class does not implement any interface, you cannot provide a service.
-In this case, the handler throws an error.
-
-== Service Properties
-
-You can also attach properties to a service registration.
-Service properties are attached to published service and allow consumer filtering/selecting providers.
-A property can be attached to a field (contained in the component implementation class), and so can be handle dynamically.
-
-Let's take a new example very closed of the last one:
-
-[source,java]
-----
-@Component
-@Provides
-public class FooProviderType1 implements FooService {
-
- @ServiceProperty(name="foo", value="Foo")
- private String m_foo;
-
- public void foo() {
- System.out.println("foo " + m_foo);
- m_foo = "bar";
- }
-}
-----
-
-Using XML, it gives:
-[source,xml]
- <component classname="...FooProviderType1">
- <provides>
- <property name="foo" field="m_foo" value="Foo"/>
- </provides>
- </component>
-
-The declared property is attached to the `m_foo` field.
-This property is published with the name `foo`.
-This property has a default value "Foo".
-This value will be injected into the `m*foo` field, when this field asks for a value.
-A property with a field attribute does not need to declare a type (the type can be discovered by analyzing the implementation class).
-
-The implementation class set a new value to the `m_foo` field in the code.
-When this action occurs, the service publication is updated.
-If a published property value becomes `null`, the property is unpublished since it has a new value.
-
-You can also publish 'static' properties (not attached to a field):
-
-[source,java]
-----
-@Component
-@Provides(properties= {
- @StaticServiceProperty(name="static", type="java.lang.String", value="this is a static property")
- })
-public class FooProviderType1 implements FooService {
-
- @ServiceProperty(name="foo", value="Foo")
- private String m_foo;
-
- public void foo() {
- System.out.println("foo " + m_foo);
- m_foo = "bar";
- }
-}
-----
-
-The second property (`Static`) is published as a static property.
-This property is not attached to a field, so, we need to declare the property type.
-All primitive types or objects can be used has property type (for object, the qualified name of the class is used as java.lang.String).
-
-In XML, this can also be done:
-[source,xml]
- <component classname="...FooProviderType1">
- <provides>
- <property name="foo" field="m_foo" value="Foo"/>
- <property name="static" type="java.lang.String" value="this is a static property"/>
- </provides>
- </component>
-
-Properties may have a default value (set using the `value` attribute).
-This value will be used as initial value.
-The value can be given in the instance configuration.
-The default value will be overridden in this case:
-[source,xml]
- <instance component="...FooProviderType1">
- <property name="foo" value="My New Foo Value"/>
- <property name="static" value="My Value For Static"/>
- </instance>
-
-Properties can also be 'mandatory'.
-Mandatories properties must receive a value from the instance configuration.
-If the instance configuration _forgets_ a mandatory properties, the configuration is rejected.
-Mandatory attribute let you be sure to receive the complete set of initialization values:
-
-[source,java]
-----
-@Component
-@Provides
-public class MyComponent implements MyService {
-
- @ServiceProperty(name="username", mandatory=true)
- private String m_username;
-
- @Property(name="password", mandatory=true)
- private String m_password;
-
- //...
-}
-----
-
-For the previous components:
-
-* `+(name=myname, password=****)+` is a valid configuration
-* `+(password=****)+` is an invalid configuration that will be rejected by iPOJO
-
-== Advanced features
-
-=== Service Serving & Object Creation
-
-When a consumer requires the published service, the handler sends an object (from the component class) of the implementation class.
-By default, it is always the same POJO object.
-If no objects already exists, an instance is created.
-
-However, the handler supports the OSGi _Service Factory_.
-In this case, for each requester bundle, the handler sends a new object.
-To activate this policy, add the `strategy` attribute in the `provides` element:
-
-[source,java]
- @Component
- @Provides(strategy="SERVICE")
- public class MyComponent implements MyService {
- //...
- }
-
-or:
-[source,xml]
- <provides strategy="SERVICE"/>
-
-Other strategies are available:
-
-* `strategy="instance"` allows creating one service object per iPOJO instance using the service
-* it is possible to create your own creation strategy by extending the `org.apache.felix.ipojo.handlers.providedservice.CreationStrategy` class and by indicating the qualified class name in the `strategy` attribute:
-+
-[source,java]
- @Component @Provides(strategy="org.acme.foo.MyCreationStrategy") public class MyComponent implements MyService { //...
-}
-
-=== Providing Several Services (XML only)
-
-In XML, you can declare several `provides` inside the same component.
-All those provided services will be managed individually, so will be published using several publication (i.e.
-`org.osgi.frameowrk.ServiceRegistration`).
-This case is useful when service properties are different for the different services.
-[source,xml]
- <component classname="...FooProviderType1">
- <provides specifications="...Foo"/>
- <provides specifications="...Bar">
- <property name="foo" value="baz"/>
- </provides>
- </component>
-
-image::documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/ps-foobar2.png[]
-
-=== Service Property Propagation
-
-The configuration handler has the possibility to propagate received properties to service publication.
-So, when the propagation is activated (on the `properties` element or on the `@Component` annotation), all properties received by the configuration handler will be propagated to all published services.
-If some properties are mapped on methods, these methods are invoked with the new value in argument.
-
-image::documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/ps-propagation.png[]
-
-If an instance configuration contains properties starting with `service.`, they are automatically propagated.
-In the following example, the `service.pid` is automatically propagated.
-[source,xml]
- <instance component="...">
- <property name="service.pid" value="my.pid"/>
- </instance>
-
-=== Instance reconfiguration
-
-iPOJO supports instance reconfiguration.
-When an instance is dynamically reconfigured and if the instance published service properties, the values are updated with the new configuration.
-For example, let's take the following component.
-
-[source,java]
-----
-@Component
-@Instantiate
-@Provides
-public class MyComponent implements MyService {
-
- @ServiceProperty(name="prop", value="initial")
- private String myProp;
-
- //...
-
-}
-----
-
-The previous code also declares an instance (created without any configuration).
-This instance registers `MyService` with the service property `prop=initial`.
-If this instance is reconfigured using a configuration like: `{prop="my value"}`, the published properties will be updated with the new value, so `prop=my value`.
-
-=== Publishing an abstract or concrete class as a Service
-
-It is also possible to expose an abstract or concrete class as a service.
-To to this, just specify the published class in the `specifications` attribute:
-
-[source,java]
- @Component
- @Provides(specifications=MyComponent.class)
- public class MyComponent {
- // ...
- }
-
-or in XML:
-[source,xml]
- <component classname="...FooProviderType1">
- <provides specifications="...AbstractFoo"/>
- </component>
- <component classname="...FooBarProviderType1">
- <provides specifications="[...AbstractFoo, ...Bar]"/>
- </component>
-
-As illustrated with the example using annotation, the component can also publish itself as a service.
-However, such practice is not recommended.
-
-=== Controlling the service exposition from the implementation class
-
-To control the exposition of the published service, you can use a `service controller`.
-A service controller is a boolean field of the component class.
-The injected boolean field allows the code to impact the service publication.
-Setting the field to `false` unregisters the service from the service registry.
-Setting it back to `true` re-publishes the service.
-
-[source,java]
-----
-@Component
-@Provides
-public class ControllerCheckService implements FooService, CheckService {
-
- @ServiceController
- private boolean controller; // Service Controller
-
- public boolean foo() {
- return controller;
- }
-
- public boolean check() {
- System.out.println("Before : " + controller);
- controller = ! controller; // Change the publication
- System.out.println("After : " + controller);
- return controller;
- }
-}
-----
-
-Using XML, the previous component description is:
-[source,xml]
- <component classname="org.apache.felix.ipojo.test.scenarios.component.controller.ControllerCheckService"
- name="PS-Controller-1-default">
- <provides>
- <controller field="controller"/>
- </provides>
- </component>
-
-The `controller` may have a value attribute setting the initial value.
-Setting this value to `false` disables the initial service registration:
-
-[source,java]
-----
-@Component
-@Provides
-public class ControllerCheckService implements FooService, CheckService {
-
- @ServiceController(value=false)
- private boolean controller; // Service Controller
-
- public boolean foo() {
- return controller;
- }
-
- public boolean check() {
- System.out.println("Before : " + controller);
- controller = ! controller; // Change the publication
- System.out.println("After : " + controller);
- return controller;
- }
-
-}
-----
-
-If several interfaces are exposed, the controller may have a `specification` attribute indicating the impacted service:
-
-[source,java]
-----
-@Component
-@Provides
-public class ControllerCheckService implements FooService, CheckService {
-
- @ServiceController(value=false, specification=FooService.class)
- private boolean controller; // Service Controller
-
- public boolean foo() {
- return controller;
- }
-
- public boolean check() {
- System.out.println("Before : " + controller);
- controller = ! controller; // Change the publication
- System.out.println("After : " + controller);
- return controller;
- }
-
-}
-----
-
-In XML, each `provides` can have one `controller` element.
-[source,xml]
- <component classname="org.apache.felix.ipojo.test.scenarios.component.controller.ControllerCheckService"
- name="PS-Controller-1-false">
- <provides>
- <controller field="controller" value="false"/>
- </provides>
- </component>}
-
-=== Being notified of the service registration and unregistration
-
-You can also be notified when the service is published and unpublished.
-This is done by specifying the two callbacks in the `<provides/>` element:
-[source,xml]
- <component
- classname="org.apache.felix.ipojo.test.scenarios.component.callbacks.CallbacksCheckService"
- name="PS-Callbacks-both-1">
- <provides
- specifications="org.apache.felix.ipojo.test.scenarios.ps.service.FooService"
- post-unregistration="unregistered" post-registration="registered"/>
- <provides
- specifications="org.apache.felix.ipojo.test.scenarios.ps.service.CheckService"
- post-unregistration="unregistered" post-registration="registered"/>
- </component>
-
-Or by using the `@PostRegistration` and `@PostUnregistration` annotations:
-
-[source,java]
-----
-@PostRegistration
-public void registered(ServiceReference ref) {
- System.out.println("Registered");
-}
-
-@PostUnregistration
-public void unregistered(ServiceReference ref) {
- System.out.println("Unregistered");
-}
-----
-
-* The `post-registration` callback is called after the service publication
-* The `post-unregistration` callback is called after the service unpublication
-
-Those callback methods must have the following signature: `public void name(ServiceReference ref)`.
-So they receive the published / unpublished service reference.
-The callbacks are called in the _same thread_ as the publication / unpublication itself.
diff --git a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/service-requirement-handler.adoc b/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/service-requirement-handler.adoc
deleted file mode 100644
index 1fffc37..0000000
--- a/modules/ROOT/pages/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/service-requirement-handler.adoc
+++ /dev/null
@@ -1,867 +0,0 @@
-= Requiring services
-
-_One of the main iPOJO feature is the service injection.
-So, a component can consume a service without managing the service discovery, tracking and binding.
-iPOJO manages all these interactions and injects required service into the component.
-This page explains how to use services._
-
-
-
-== Service Dependency
-
-=== What's a service dependency?
-
-A required service is described by a service dependency.
-The dependency defines what kind of service is required, how to select the it, the resilience to its dynamism...
-iPOJO handles all these aspects for you, just tell, iPOJO tracks, selects, binds and injects the matching services directly in your code.
-Service dependencies can be:
-
-* Scalar or Aggregate : the component can require one or several service providers
-* Mandatory or Optional : a component can declare an optional dependency, and defined what should be done when no services are available
-* Filtered : a component can filter available providers, and even choose a specific provider
-* Resilient to dynamism : iPOJO supports three binding policy depending on your reaction to dynamism
-
-=== Dynamism, Resilience & Instance Lifecycle
-
-In OSGi™, services can appear and disappear dynamically.
-This implies dependencies can target a provider which can appear or disappear dynamically.
-So, dependencies need to manage this dynamism by tracking every time available services.
-At any moment, a dependency can be unresolved (i.e.
-no more provider can fulfill the requirement).
-In the case of a mandatory requirement, the instance becomes invalid (an invalid instance is no more accessible externally, for example provided services are unpublished).
-If a service, resolving the unfilled dependency appears, the instance becomes valid.
-In consequence, dependencies affect directly the instance state, and must manage correctly OSGi dynamism to allow a complete unloading when a service goes away.
-As soon a mandatory dependency cannot be fulfilled, the instance is invalidated.
-
-By default, dependencies are managed dynamically (as previously explained).
-However, iPOJO supports two other types of binding policies:
-
-* Static : if a bound service disappears, the instance is invalidated and cannot be revalidated (binding broken forever)
-* Dynamic-Priority: at each injection, the _best_ provider is injected, or the providers array is sorted according to the OSGi Ranking policy or to a specified sorting algorithm.
-
-== Service Requirement Injection Mechanisms
-
-iPOJO support several types of injections:
-
-*Field injection*: a field contains the service object.
-As soon as the field is used, a consistent service object is injected.
-This injection type fully hides the dynamism
-
-[source,java]
- @Requires
- private LogService log;
-
-*Method invocation*: when a service appears, or disappears a method in the component is invoked.
-For each dependency, bind / unbind / modified methods are invoked to notify the component of the event.
-
-[source,java]
- @Bind
- public void bindLogService(LogService log) { /*...*/ }
- @Unbind
- public void unbindLogService(LogService log) { /*...*/ }
- @Modified
- public void modifiedLogService(LogService log) { /*...*/ }
-
-*Constructor injection*: services can also be injected as constructor parameter (only if proxies are enabled).
-_1.7.0-SNAPSHOT_
-
-[source,java]
- public MyComponent(@Requires LogService log) { /*...*/ }
-
-Moreover, the injections types can be mixed.
-A component can declare a requirement containing both a field and 'binding' methods.
-
-=== Field injection
-
-Let's imagine a Hello service with one method 'getMessage' returning a "Hello Message".
-The following component implementation can use this service by attaching this service to a field and by using the field:
-
-[source,java]
-----
-@Component
-@Instantiate
-public class HelloConsumer {
- @Requires
- private Hello m_hello;
-
- public doSomething() {
- System.out.println(m_hello.getMesage());
- }
-}
-----
-
-You can also use XML to describe this component type:
-[source,xml]
- <component classname="...HelloConsumer">
- <requires field="m_hello"/>
- ...
- </component>
-
-The metadata contains a 'requires' element (representing the service dependency) and specify a field used to inject the service.
-The implementation uses the field as a normal field without managing service interactions.
-
-=== Method invocation
-
-The second injection mechanism uses methods in the implementation class.
-By this way, the dynamics can be managed directly by the developer.
-Each dependency can declare three methods:
-
-* A bind method called when a service appears
-* An unbind method called when a service disappears
-* A modified method called when a service is modified (the service properties have changed, but the service still matches the requirement)
-
-Moreover, callbacks can be in the component super class (in this case methods must be public).
-These methods can have one of these signatures:
-
-* Without any argument: the method is just a notification
-
- [source,java]
- public void bindService() {
- // ...
- }
-
-* With the service object: the object is the implicated service object.
-Service dependency type is inferred from the parameter's type.
-
- [source,java]
- public void bindService(HelloService hello) {
- m_hello = hello;
- }
-
-* With an OSGi service reference: the service reference appearing or disappearing.
-
- [source,java]
- public void bindService(ServiceReference<HelloService> reference) {
- // ...
- }
- public void bindService(ServiceReference reference) {
- // ...
- }
- public void bindService(ServiceReference reference) {
- // ...
- }
-
-* With the service object and the OSGi service reference.
-
- [source,java]
- public void bindService(HelloService hello, ServiceReference<HelloService> reference) {
- // ...
- }
-
-* With the service object and the service properties inside a Map (no adherence to OSGi APIs).
-
- [source,java]
- public void bindService(HelloService hello, Map<String, Object> properties) {
- // ...
- }
-
-* With the service object and the service properties inside a Dictionary (no adherence to OSGi APIs).
-
- [source,java]
- public void bindService(HelloService hello, Dictionary<String, Object> properties) {
- // ...
- }
-
-=== ALERT Important
-
-Notice that, when missing (typically no interface can be inferred from the code) dependency information must be supplied to iPOJO in some way
-
-* `@Bind` with `specification` and/or `filter` attribute
-* Using XML metadata declaration
-
-The following component implementation shows an example of implementation using this mechanism:
-
-[source,java]
-----
-@Component
-public class HelloConsumer {
- private Hello m_hello;
-
- @Bind
- public void bindHello(Hello h) { m_hello = h; }
- @Unbind
- public void unbindHello() { m_hello = null; }
- public doSomething() { System.out.println(m_hello.getMesage()); }
-}
-----
-
-The `modified` callback is not mandatory.
-The following XML metadata are describing the same component type:
-[source,xml]
- <component classname="...HelloConsumer">
- <requires>
- <callback type="bind" method="bindHello"/>
- <callback type="unbind" method="unbindHello"/>
- </requires>
- ...
- </component>
-
-Note, that the different callbacks can be have different signatures.
-By using this mechanism, you need to be sure to manage the dynamism correctly.
-(<<note-on-service-interface-discovery,See note on type discovery>>
-
-Using the `@Modified` callback is also quite simple:
-
-[source,java]
-----
-@Component
-public class HelloConsumer {
- private Hello m_hello;
-
- @Bind
- public void bindHello(Hello h) { m_hello = h; }
- @Unbind
- public void unbindHello() { m_hello = null; }
- @Modified
- public void modifiedHello() { /* ... */ }
- public doSomething() { System.out.println(m_hello.getMesage()); }
-}
-----
-
-=== Using constructor injection (_1.7.0-SNAPSHOT_)
-
-Services can also be injected using constructor parameters:
-
-[source,java]
-----
-@Component
-public class MyComponent {
- private LogService log;
-
- public MyComponent(@Requires LogService log) {
- this.log = log;
- }
-}
-----
-
-=== Mixing injections types
-
-The different mechanisms can be used together.
-In this case, the field receives the value before the bind method invocation.
-Constructor parameters get their values during the constructor invocation.
-So, if the field is used in the method, the returned value will be up to date.
-The following component implementation uses this mechanism:
-
-[source,java]
-----
-public class HelloConsumer {
- @Requires(id="hello")
- private Hello m_hello; // Injected Field
-
- @Bind(id="hello")
- public void bindHello() { System.out.println("Hello appears"); }
- @Unbind(id="hello")
- public void unbindHello() { System.out.println("Hello disapears"); }
-
- public doSomething() { System.out.println(m_hello.getMesage()); }
-}
-----
-
-In XML, it results in:
-[source,xml]
- <component classname="...HelloConsumer">
- <requires field="m_hello">
- <callback type="bind" method="bindHello"/>
- <callback type="unbind" method="unbindHello"/>
- </requires>
- ...
- </component>
-
-The `id` attribute is used to determine which callbacks / fields go together.
-If ommitted, it is computed automaticcally:
-
-* for field it uses the field type.
-* for method starting with `bind` / `unbind` / `modified`, it extract the end of the method name (`+bindFoo => Foo+`)
-* for constructor parameter, it uses the parameter index
-
-So, it is strongly recommended to specify the id manually.
-
-=== Injection mechanisms & lazy object creation
-
-iPOJO creates objects only when required.
-When needed, iPOJO invokes the constructor of the implementation class.
-The implementation class can use field requirement because values are already injected and obviously constructor parameters.
-However, method dependencies are called _after_ the constructor.
-If the service is available before the constructor call, the invocation of the bind methods is delayed until the a component class object is created.
-
-== Examples
-
-For all examples both annotations and XML forms are given.
-Just choose what you'd like to use.
-
-=== Simple Requirement
-
-By default, a requirement is mandatory, non-filtered and simple (non-aggregate).
-The previous examples illustrate this kind of dependency.
-When services goes away and appears, the service substitution is hidden.
-Fields attached to simple requirement point always a consistent service object.
-For a simple dependency, the bind method is called once time when the service appears or just after the POJO constructor invocation is the service is available.
-When the service disappears the unbind method is called.
-The bind method is re-invoked as soon as another service provider is available.
-This invocation occurs immediately if another service provider if available.
-In this case, the instance is not invalidated.
-
-=== Aggregate Requirement
-
-When a component requires several providers of the same service, it declares an aggregate dependency.
-
-==== Aggregate Dependency with field injection
-
-[source,java]
- @Component
- public class HelloConsumer {
- @Requires
- private Hello m_hellos[]; // Array => Aggregate
- public doSomething() {
- for(int I = 0; I < m_hellos.length; i++) {
- System.out.println(m_hellos[i].getMessage());
- }
- }
- }
-
-For this component, XML metadata could be:
-[source,xml]
- <component classname="...HelloConsumer">
- <requires field="m_hellos"/>
- ...
- </component>
-
-To declare an aggregate field for field requirement, you only need to declare an array (instead of a scalar type).
-iPOJO will create and inject the service object array.
-iPOJO discover that the dependency is aggregate during the bytecode introspection.
-
-Array types cannot be 'proxied'.
-Moreover array dependencies cannot be injected as constructor parameter.
-
-==== Synchronization
-
-The synchronization is managed by iPOJO.
-As soon as you are 'touching' a dependency in a method, iPOJO ensure that you will keep these objects until the end of the method.
-Nested methods will share the same service object set.
-
-==== Aggregate Dependency with field injection: list, vector, collection and set
-
-It is also possible to inject service objects inside fields of the type:
-
-* list
-* vector
-* collection
-* set
-+
-[source,java]
-----
- @Component
- @Instantiate
- public class HelloConsumer {
- @Requires
- private Hello m_hello;
-
- public doSomething() {
- System.out.println(m_hello.getMesage());
- }
- }
-----
-For this component, XML metadata could be:
-
-[source,xml]
- <component classname="...HelloConsumer">
- <requires field="m_hellos" specification="org.apache.felix.ipojo.example.Hello"/>
- ...
- </component>
-
-In this case, just use the supported type that you want.
-iPOJO will automatically understand that it is an aggregate dependency, and will create the collection object containing service objects.
-However, you must specify the service specification.
-Indeed, generics types cannot be discovered at runtime reliably.
-
-==== Service specification discovery
-
-The service specification (i.e.
-interface) cannot be discovered when using these types as the bytecode does not provide enough information.
-So, you have to indicate the required service interface (with the 'specification' attribute) in the requirement description.
-
-==== How iPOJO manage the synchronization for you
-
-As in the previous case, the synchronization is managed by iPOJO.
-As soon as you are *touching* a dependency in a method, iPOJO ensure that you will keep these objects until the end of the method.
-Nested methods will share the same service object set.
-
-==== Aggregate Dependency with callbacks
-
-[source,java]
- public class HelloConsumer {
- private List m_hellos = new ArrayList();
- @Bind(aggregate=true)
- private void bindHello(Hello h) { m_hellos.add(h); }
- @Unbind
- private void unbindHello(Hello h) { m_hellos.remove(h); }
- public synchronized doSomething() {
- for(Hello h : m_hellos) {
- System.out.println(h.getMessage());
- }
- }
- }
- }
-
-This dependency can also be described in XML as follow:
-
-[source,xml]
- <requires aggregate="true">
- <callback type="bind" method="bindHello"/>
- <callback type="unbind" method="unbindHello"/>
- </requires>
-
-In this case, iPOJO cannot detect if the dependency is aggregate or not.
-So, you need to add the '_aggregate_' attribute.
-The bindHello and unbindHello will be called each time a Hello service appears or disappears.
-
-==== Synchronization
-
-To avoid the list modification during the loop, you need synchronized the block.
-Indeed, as the field is not an iPOJO requirement, iPOJO will not manage the synchronization.
-
-=== Optional Requirement (Scalar)
-
-An optional requirement does not invalidate the instance despite no providers are available.
-Moreover, it is possible to inject a default service implementation when no _real_ providers are available.
-
-==== Optional Requirement with field injection
-
-[source,java]
-----
-@Component
-public class HelloConsumer {
- @Requires(optional=true)
- private Hello m_hello;
-
- public doSomething() {
- System.out.println(m_hello.getMesage());
- }
-}
-----
-
-For this component, equivalent XML metadata could be:
-[source,xml]
- <component classname="...HelloConsumer">
- <requires field="m_hello" optional="true"/>
- ...
- </component>
-
-To declare an optional requirement, you need to add the _'optional'_ attribute.
-To avoid `null` pointer exception, iPOJO injects a `Nullable` object in the field when no service provider is available.
-The _nullable_ object implements the service interface, but does nothing.
-Moreover, it is possible to set a _default-implementation_ for the service.
-A default-implementation is a class implementing the service but used only when no others service providers are available.
-The default-implementation object will be injected instead of the _Nullable_ objet.
-For further information <<note-about-nullable-object-default-implementation,refer to the note about nullable object>>.
-
-==== Optional Dependency with callbacks invocation
-
-[source,java]
-----
-@Component
-public class HelloConsumer {
- private Hello m_hello;
-
- @Bind(optional=true)
- public void bindHello(Hello h) { m_hello = h; }
-
- @Unbind
- public void unbindHello() { m_hello = null; }
-
- public doSomething() {
- if(m_hello != null) { // Must be checked
- System.out.println(m_hello.getMesage());
- }
- }
-}
-----
-
-For this component, XML metadata could be:
-[source,xml]
- <component classname="...HelloConsumer">
- <requires optional="true">
- <callback type="bind" method="bindHello"/>
- <callback type="unbind" method="unbindHello"/>
- </requires>
- ...
- </component>
-
-As for field requirement, the dependency metadata needs to contain the optional attribute.
-iPOJO invokes the method only when a 'real' service is available, so you need to test if `m_hello` is `null` before to use it.
-
-=== Aggregate & Optional Requirement
-
-A dependency can be both aggregate and optional.
-
-==== Aggregate & Optional Dependency with field injection
-
-[source,java]
-----
-@Component
-public class HelloConsumer {
- @Requires(optional=true)
- private Hello m_hellos[];
-
- public doSomething() {
- for(Hello h : m_hellos) {
- System.out.println(h.getMessage());
- }
- }
-}
-----
-
-For this component, XML metadata could be:
-[source,xml]
- <component classname="...HelloConsumer">
- <requires field="m_hellos" optional="true"/>
- ...
- </component>
-
-To declare an optional & aggregate field requirement you need to write the optional attribute in the dependency metadata and to point on a field array.
-If no service available, iPOJO injects an empty array.
-
-==== Aggregate & Optional Requirement with callbacks
-
-[source,java]
-----
-@Component
-public class HelloConsumer {
-
- private List m_hellos<Hello> = new ArrayList<Hello>();
-
- @Bind(aggregate=true, optional=true)
- private void bindHello(Hello h) { m_hellos.add(h); }
-
- @Unbind
- private void unbindHello(Hello h) { m_hellos.remove(h); }
-
- public synchronized doSomething() {
- for(Hello h : m_hellos) {
- System.out.println(h.getMessage());
- }
- }
-}
-----
-
-For this component, XML metadata could be:
-[source,xml]
- <requires aggregate="true" optional="true">
- <callback type="bind" method="bindHello"/>
- <callback type="unbind" method="unbindHello"/>
- </requires>
-
-In this case, you need to add the _'aggregate'_ attribute and the __'optional'__attribute.
-The `bindHello` and `unbindHello` will be called each time a Hello service appears or disappears.
-These bind / unbind methods are not called when binding / unbinding a Nullable object (when both field and method are used).
-
-=== Filtered Requirement
-
-A filtered dependency applies an LDAP filter on service provider.
-iPOJO reuses OSGi LDAP filter ability.
-The following metadata illustrates how to use filters:
-
-[source,java]
-----
-@Requires(filter="(language=fr)")
-private String DictionaryService dict;
-[source,xml]
-<requires filter="(language=fr)" field="dict"/>
-----
-
-To add a filter, just add a 'filter' attribute in your dependency containing the LDAP filter.
-iPOJO will select only provider matching with this filter.
-
-When using a filter, you can also use the `modified` callback invoked when a matching service is _modified_ but still matches the filter:
-
-[source,java]
-----
-@Component
-public class MyComponent {
-
- @Bind(filter="(langage=en)")
- public void bindHDictionary(DictionaryService svc) { ... }
-
- @Unbind
- public void unbindDictionary() { ...}
-
- @Modified
- public void modifiedDictionary() { ... }
-}
-----
-
-Moreover, filters can be customized instance by instance.
-It is possible to specialize / change / add the filter of a component in the instance description.
-It is useful when you want to create different instances of the same component, with different filter.
-To achieve this customization, you have to identify your dependency with the 'id' attribute.
-Then, you can adapt the filter of the dependency in the instance description by using the property "requires.filters".
-In this property you can specify each dependency identified by its id and the new value of the filter.
-
-[source,xml]
-----
-<component
- className="org.apache.felix.ipojo.example.FilteredDependency">
- <requires field="m_foo" fiter="(foo.property=FOO)" id="id1">
- <callback type="bind" method="bind"/>
- <callback type="unbind" method="unbind"/>
- </requires>
-</component>
-
-<instance name="FOO1" component="FOO"/>
-
-<instance name="FOO2" component="FOO">
- <property name="requires.filters">
- <property name="id1" value="(foo.property=BAR)"/>
- </property>
-</instance>
-
-<instance name="FOO3" component="FOO">
... 4654 lines suppressed ...