You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@felix.apache.org by cl...@apache.org on 2013/04/09 11:37:22 UTC
svn commit: r1465947 [1/2] - in /felix/site/trunk:
content/documentation/subprojects/apache-felix-ipojo/
content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/
content/documentation/subprojects/apache-felix-ipojo/apache-felix...
Author: clement
Date: Tue Apr 9 09:37:22 2013
New Revision: 1465947
URL: http://svn.apache.org/r1465947
Log:
migrate tools and dev guide to the new CMS system
Added:
felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/Handler-Lifecycle.png (with props)
felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/POJO-Container-Handler.png (with props)
felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/log_handler.zip (with props)
felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/property-handler.zip (with props)
felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/apache-felix-ipojo-online-manipulator.mdtext
- copied, changed from r1464870, felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-online-manipulator.mdtext
Removed:
felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/ipojo-concepts-overview.mdtext
felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-online-manipulator.mdtext
felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-eclipse-plug-in.mdtext
Modified:
felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/how-to-write-your-own-handler.mdtext
felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-arch-command.mdtext
felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-maven-plug-in.mdtext
felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-webconsole-plugin.mdtext
felix/site/trunk/templates/ipojo.html
Added: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/Handler-Lifecycle.png
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/Handler-Lifecycle.png?rev=1465947&view=auto
==============================================================================
Binary file - no diff available.
Propchange: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/Handler-Lifecycle.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/POJO-Container-Handler.png
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/POJO-Container-Handler.png?rev=1465947&view=auto
==============================================================================
Binary file - no diff available.
Propchange: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/POJO-Container-Handler.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Modified: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/how-to-write-your-own-handler.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/how-to-write-your-own-handler.mdtext?rev=1465947&r1=1465946&r2=1465947&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/how-to-write-your-own-handler.mdtext (original)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/how-to-write-your-own-handler.mdtext Tue Apr 9 09:37:22 2013
@@ -7,37 +7,41 @@ Title: How to write your own 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.*
-{div:class=toc}
[TOC]
-{div}
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.
## 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>).
+
+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.
-!POJO-Container-Handler.png!
+<img src="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.
-*Note :* 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).
+<div class="alert alert-info">
+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. <code>org.apache.felix.ipojo</code>).
+</div>
## 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 an XML 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, in the `metadata.xml` of the bundle containing your handler, the class name of your handler and its name and XML namespace. You can, of course, declare several handlers, and even declare components using these handlers, in the same bundle.
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 its metadata.xml, as for classic iPOJO components.
+ :::xml
<ipojo>
...
<handler className="your.handler.class"
@@ -53,22 +57,28 @@ Then, you must know that a handler is a
</ipojo>
-*Note :* 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]({{ refs.-annotations.path }}) section.
-
-*Hint :* It is a good idea to provide a documented XML schema description (XSD) with your handler to help users to configure your handler and to validate their configurations. Refer to the [#xsd]({{ refs.-xsd.path }}) section.
+<div class="alert alert-info">
+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 <a href="#annotations">annotations</a> section.
+</div>
+
+<div class="alert alert-info">
+It is a good idea to provide a documented XML schema description (XSD) with your handler to help users to configure your handler and to validate their configurations. Refer to the <a href="#xsd">XML Schema</a> section.
+</div>
### Handler lifecycle
A handler lifecycle is composed of four different states.
-!Handler-Lifecycle.png!
+<img src="Handler-Lifecycle.png">
-* First, when iPOJO parses the `metadata.xml` 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).
+* First, when iPOJO parses the `metadata.xml` 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.
+* 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.
-*Note :* 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.
+<div class="alert alert-warning">
+Keep in mind that the <code>stop()</code> 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.
+</div>
### 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.
@@ -77,13 +87,13 @@ The `Element` type (placed in the `org.a
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]({{ refs.-description.path }}) 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) :
+* 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 <a href="#description">description</a> 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) :
+ :::java
Element[] handlerConfig =
componentMetadata.getElements("HandlerName",
"the.namespace.of.your.handler");
@@ -96,41 +106,46 @@ One of the most interesting features of
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 informations 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 informations about a particular method in the POJO.
+* 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 informations 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 informations 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.
-*Note :* 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.
+<div class="alert alert-info">
+The InstanceManager manages the component instance attached to your handler instance. Thus, it can't be available in the <code>initializeComponentFactory()</code> because this method is run before the creation of any component instance.
+</div>
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 `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.
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, Method method, Object[]({{ refs..path }}) 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, Method 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, Method 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, Method 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 `void onEntry(Object pojo, Method 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, Method 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, Method 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, Method 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.
*Warning :* 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 :
-
+ :::java
getInstanceManager().register(anInterestingFieldMetadata, this);
...
getInstanceManager().register(anInterestingMethodMetadata, this);
...
-*Note :* 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.
+<div class="alert alert-info">
+The <code>PrimitiveHandler</code> abstract class implements the <code>FieldInterceptor</code> and <code>MethodInterceptor</code> 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 <code>InstanceManager</code> register method instead of the handler object itself.
+</div>
### 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 :
+ :::xml
<ipojo xmlns:your-shortcut="the.namespace.of.your.handler">
...
<component className="your.component.class">
@@ -152,11 +167,12 @@ The remainder of this document describes
* 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. The code source of this handler is downloadable [here](http://people.apache.org/~clement/ipojo/tutorials/handler/loghandler.zip).
+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. The code source of this handler is downloadable <a href="loghandler.zip">here</a>.
### 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. If no log services are found, a default implementation is used instead.
+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. If no log services are found, a default implementation is used instead.
+ :::xml
<ipojo>
<!-- Declare the handler -->
<handler
@@ -183,6 +199,7 @@ The handler needs to be notified when co
#### InitializeComponentFactory Method
This method parses and checks the component type metadata. The handler needs a log element from its namespace. According to the result, the configure method can throw an exception or parse the level attribute (to get the logging level).
+ :::java
public void initializeComponentFactory(ComponentTypeDescription typeDesc,
Element metadata)
throws ConfigurationException {
@@ -212,6 +229,7 @@ This method parses and checks the compon
#### 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.
+ :::java
public void configure(Element metadata, Dictionary config)
throws ConfigurationException {
@@ -238,6 +256,7 @@ This method reads the component descript
#### 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.
+ :::java
public void stateChanged(int state) {
// Log the state changed events
if (state == InstanceManager.VALID) {
@@ -249,13 +268,13 @@ This method is called by the instance ma
}
}
-
-### Handler packaging
+## 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 needs to declare an `org.apache.felix.ipojo.log.handler.LogHandler:log` XML element, with a level attribute. This level attribute's value can be `"error"`, `"warning"` or `"info"`. Here is an usage example:
+ :::xml
<ipojo xmlns:log="org.apache.felix.ipojo.log.handler.LogHandler">
<!-- Declare a component using the LogHandler -->
@@ -268,9 +287,6 @@ To use this handler, a component needs t
</ipojo>
-### Download
-The LogHandler is available [here](http://people.apache.org/~clement/ipojo/tutorials/handler/loghandler.zip). The archive file contains the handler implementation and a simple component using this handler.
-
## 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.
@@ -297,7 +313,7 @@ The handler is implemented by the `Prope
#### 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 will be a part of the component instance container and will be notified of field access.
-
+ :::java
public void configure(Element metadata, Dictionary configuration)
throws ConfigurationException {
// Parse metadata to get <properties file="$file"/>
@@ -358,11 +374,13 @@ This method begins by parsing the compon
#### The start and stop methods
The start method does nothing, but needs to be implemented.
+ :::java
public void start() {}
The stop method stores properties inside the properties file.
+ :::java
public void stop() {
try {
saveProperties();
@@ -377,6 +395,7 @@ The stop method stores properties inside
#### 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.
+ :::java
public Object onGet(Object pojo, String field, Object o) {
// When the pojo requires a value for a managed field,
// this method is invoked.
@@ -401,17 +420,19 @@ To use this handler, a component need to
*Note :* you need to escape '\' (anti-slash characters) in the file path name.
### Download
-The PropertiesHandler is available [here](http://people.apache.org/~clement/ipojo/tutorials/handler/property-handler.zip). The archive file contains the handler implementation and a simple component using this handler.
+The PropertiesHandler is available <a href="property-handler.zip">here</a>. The archive file contains the handler implementation and a simple component using this handler.
## 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`).
+<a name="description"></a>
### 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 :
+ :::java
public class YourHandler extends PrimitiveHandler {
...
// Method returning the handler description.
@@ -440,31 +461,34 @@ By default, only the handler's name and
}
}
-
+<a name="annotations"></a>
## 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:
-{code:java}
-package org.apache.felix.ipojo.properties.handler;
-import java.lang.annotation.ElementType;
-import java.lang.annotation.Target;
+ :::java
+ package org.apache.felix.ipojo.properties.handler;
-@Target(ElementType.TYPE)
-public @interface Properties {
-
- String file();
+ 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:
- {code:java}
+This annotations is put on the {{class}} element, and allows setting the property file:
+
+ :::java
@Component
@Properties(file="/Users/clement/felix/properties/i1.properties")
public class Example {
@@ -473,37 +497,40 @@ public @interface Properties {
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:
-{code: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;
+ :::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:
- {code:shell}
+will be translated to:
+
+ :::sh
component {
$classname="org.apache.felix.ipojo.test.scenarios.component.jmx.JMXSimple"
$public="true" $name="org.apache.felix.ipojo.test.scenarios.component.jmx.JMXSimple"
@@ -521,14 +548,11 @@ public class JMXSimple {
*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`.
-
+ <a name="schemas"></a>
## 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.
-
-
-
+If you develop handler and you want to share it, feel free to contact us by sending a mail on the Felix mailing list.
\ No newline at end of file
Added: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/log_handler.zip
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/log_handler.zip?rev=1465947&view=auto
==============================================================================
Binary file - no diff available.
Propchange: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/log_handler.zip
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/property-handler.zip
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/property-handler.zip?rev=1465947&view=auto
==============================================================================
Binary file - no diff available.
Propchange: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/property-handler.zip
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Copied: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/apache-felix-ipojo-online-manipulator.mdtext (from r1464870, felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-online-manipulator.mdtext)
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/apache-felix-ipojo-online-manipulator.mdtext?p2=felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/apache-felix-ipojo-online-manipulator.mdtext&p1=felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-online-manipulator.mdtext&r1=1464870&r2=1465947&rev=1465947&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-online-manipulator.mdtext (original)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/apache-felix-ipojo-online-manipulator.mdtext Tue Apr 9 09:37:22 2013
@@ -7,59 +7,46 @@ Title: apache-felix-ipojo-online-manipul
*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!*
-{div:class=toc}
[TOC]
-{div}
+
## Features
-iPOJO is based on a bytecode [manipulation]({{ refs.dive-into-the-ipojo-manipulation-depths.path }}). 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.
+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
-{center}
-!manipulation.png|width=640|height=300!
-{center}
+
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 *
-This is a requirement. You must install and start the URL handler as well as iPOJO (core). The URL Handler is build by the online-manipulator iPOJO sub-project.
-On Felix you can either use the `start` command from the shell of OBR:
-
-| Shell Command | OBR |
-|--|--|
-
-
-start http://repo1.maven.org/maven2/org/apache/felix/org.apache.felix.ipojo.online.manipulator/1.6.0/org.apache.felix.ipojo.online.manipulator-1.6.0.jar|obr start "Apache Felix iPOJO URL Handler"|
+### Install and Start the URL Handler
-* Install a bundle using the `ipojo:` URL prefix
+Download and install the iPOJO online manipulator. You can download it from the <a href="http://felix.apache.org/downloads.cgi">Felix download page</a>
+
+### 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
+ :::sh
install ipojo:file:/.../bundle.jar
-
The complete URL syntax is
-
+
+ :::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
+ :::sh
install ipojo:bundle_url!metadata_url
-
-If you provide such url, it will override the contained `metadata.xml` file.
-
-
-
-
+If you provide such url, it will override the contained `metadata.xml` file.
\ No newline at end of file
Modified: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-arch-command.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-arch-command.mdtext?rev=1465947&r1=1465946&r2=1465947&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-arch-command.mdtext (original)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-arch-command.mdtext Tue Apr 9 09:37:22 2013
@@ -1,75 +1,64 @@
translation_pending: true
Title: iPOJO-Arch-Command
+# 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.*
-# iPOJO `Arch` command
-*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 `arch` command allows getting these data from the Felix Shell, from the Equinox shell and Gogo.*
-
-*Note* : The Gogo commands are not yet released but are available from the iPOJO trunk.
-
-{div:class=toc}
[TOC]
-{div}
-
-## Download
-The Felix commands is available from the [download]({{ refs.download.path }}) page.
-The Equinox command sources are available [http://svn.apache.org/repos/asf/felix/sandbox/clement/ipojo-utils/arch-equinox/](http://svn.apache.org/viewvc/felix/sandbox/clement/ipojo-utils/arch-equinox/). To compile sources, just launch the `mvn clean install` and deploy the resulting bundle.
## Installation
-Once you get the bundle, just install and start it in the OSGi Framework shell:
-{code:xml|title=Felix}
-start file:/BUNDLE_URL.jar
-
- {code:xml|title=Equinox}
- install file:/BUNDLE_URL.jar
- Bundle X installed
- start X
-
-{code:xml|title=Gogo}
-install file:/ARCH*GOGO*URL.jar
-Bundle X installed
-start X
-
- h2. Equinox and Felix Shells
-
- Then, you can use it to introspect the system by launching the {{arch}} command.
+According to your shell, download the adequate bundles from <a href="http://felix.apache.org/downloads.cgi">the Felix download page</a>
-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
+## 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
- h2. Gogo Shell Commands
- The set of commands available from Gogo is a little bit different:
- * {{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
-
-
- h2. Reading instance architecture
- When you launch the {{arch}} command (or {{instances}} on Gogo), the list of created instances (enabling architecture introspection) is displayed.
- {code:title=Felix or Equinox}
- -> arch
+For example:
+
+ :::sh
+ $ instances
Instance ArchCommand -> valid
Instance spell.english.EnglishDictionary-0 -> valid
Instance spell.checker.SpellCheck-0 -> valid
Instance spell.gui.SpellCheckerGui-0 -> valid
-<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>Gogo</B></DIV><DIV class="codeContent panelContent">
- $ instances
+ $ 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
+
+ :::sh
+ -> arch
Instance ArchCommand -> valid
Instance spell.english.EnglishDictionary-0 -> valid
Instance spell.checker.SpellCheck-0 -> valid
Instance spell.gui.SpellCheckerGui-0 -> valid
-To get more information on an instance, launch `arch -instance the*instance*name` (or `instance the*instance*name` on Gogo)
-<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>Felix or Equinox</B></DIV><DIV class="codeContent panelContent">
-> 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"
@@ -80,23 +69,17 @@ To get more information on an instance,
property value="spell.checker.SpellCheck-0" name="instance.name"
handler state="valid" name="org.apache.felix.ipojo.handlers.architecture.ArchitectureHandler"
-<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>Gogo</B></DIV><DIV class="codeContent panelContent">
- $ipojo: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:
+* 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:
+
+ :::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"
@@ -109,22 +92,8 @@ The `org.apache.felix.ipojo.handlers.dep
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:
-<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>Felix or Equinox</B></DIV><DIV class="codeContent panelContent">
- -> arch -instance spell.checker.SpellCheck-0
- 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"
-
-<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>Gogo</B></DIV><DIV class="codeContent panelContent">
- $instance spell.checker.SpellCheck-0
+ :::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"
@@ -140,31 +109,38 @@ In the previous case, the dependency on
You can also check created POJO objects (implementation class objet). Here, only one object was created (`spell.checker.SpellCheck@e222eb`).
## List available factories
-To list available factories (i.e. component types), launch the `arch -factories` command (or `factories` on Gogo):
-<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>Felix or Equinox</B></DIV><DIV class="codeContent panelContent">
+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.
+
+ :::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:
-<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>Gogo</B></DIV><DIV class="codeContent panelContent">
+ :::sh
$factories
Factory spell.checker.SpellCheck (VALID)
Factory spell.gui.SpellCheckerGui (VALID)
Factory spell.english.EnglishDictionary (VALID)
-
-
-For each available (public) factories,the name and the sate are displayed. A factory is valid if and only if all required handlers are available. To get more information on a factory launch the `arch -factory factory*name` (or `factory factory*name` on Gogo) command:
-
+ $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]"
+ 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
-You can also list available handlers with the `arch -handlers` (or `handlers` on Gogo) command.
-<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>Felix or Equinox</B></DIV><DIV class="codeContent panelContent">
+Like listing factories, you can get the list of handlers.
+
+ :::sh
-> arch -handlers
Handler org.apache.felix.ipojo:controller (VALID)
Handler org.apache.felix.ipojo:callback (VALID)
@@ -174,7 +150,9 @@ You can also list available handlers wit
Handler org.apache.felix.ipojo:architecture (VALID)
Handler org.apache.felix.ipojo.handler.whiteboard:wbp (VALID)
-<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>Gogo</B></DIV><DIV class="codeContent panelContent">
+On Gogo:
+
+ :::sh
$handlers
Handler org.apache.felix.ipojo:controller (VALID)
Handler org.apache.felix.ipojo:callback (VALID)
Modified: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-maven-plug-in.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-maven-plug-in.mdtext?rev=1465947&r1=1465946&r2=1465947&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-maven-plug-in.mdtext (original)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-maven-plug-in.mdtext Tue Apr 9 09:37:22 2013
@@ -5,170 +5,179 @@ Title: iPOJO Maven Plug-in
# How to use the iPOJO Maven Plug-in
-{div:class=toc}
[TOC]
-{div}
## Basic configuration
To use the iPOJO Maven plug-in, edit the following pom.xml (replace all $XXX elements):
-{div:class=pom}
-<project>
- <modelVersion>4.0.0</modelVersion>
-
- <packaging>bundle</packaging> <!-- Use the BND Maven plug-in -->
-{color:red} {color} {color:red}<groupId>$YOUR*GROUP*ID</groupId>{color}
-{color:red} {color} {color:red}<artifactId>$YOUR*ARTIFACT*ID</artifactId>{color}
-{color:red} {color} {color:red}<version>$YOUR*ARTIFACT*VERSION</version>{color}
-{color:red} {color} {color:red}<name>$YOUR*PROJECT*NAME</name>{color}
-
-{color:red} {color} {color:red}<dependencies>{color}
-{color:red} {color} {color:red}$YOUR*MAVEN*DEPENDENCIES{color}
-{color:red} {color} {color:red}</dependencies>{color}
-
- <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>
-{color:red} {color}{color:red}<Private-Package>$YOUR*PRIVATE*PACKAGE</Private-Package>{color}
-{color:red} {color}{color:red}<Export-Package>$YOUR*EXPORTED*PACKAGE</Export-Package>{color}
- </instructions>
- </configuration>
- </plugin>
- <!-- iPOJO Maven Plugin Configuration : nothing to do -->
- <plugin>
- <groupId>org.apache.felix</groupId>
- <artifactId>maven-ipojo-plugin</artifactId>
- <version>1.6.0</version>
- <executions>
- <execution>
- <goals>
- <goal>ipojo-bundle</goal>
- </goals>
- </execution>
- </executions>
- </plugin>
- </plugins>
- </build>
-</project>
-{div}
+
+ :::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>1.8.6</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:
-{div:class=pom}
-\[INFO\]({{ refs.info.path }}) Scanning for projects...
-\[INFO\]({{ refs.info.path }}) \---------------------------------------------------------------------------\-
-\[INFO\]({{ refs.info.path }}) Building Hello Client
-\[INFO\]({{ refs.info.path }}) task-segment: \[clean, install\]
-\[INFO\]({{ refs.info.path }}) \---------------------------------------------------------------------------\-
-\[INFO\]({{ refs.info.path }}) \[clean:clean\]
-\[INFO\]({{ refs.info.path }}) Deleting directory D:\clement\workspaces\iPOJO-Dev\hello.client\target
-\[INFO\]({{ refs.info.path }}) Deleting directory D:\clement\workspaces\iPOJO-Dev\hello.client\target\classes
-\[INFO\]({{ refs.info.path }}) Deleting directory D:\clement\workspaces\iPOJO-Dev\hello.client\target\test-classes
-\[INFO\]({{ refs.info.path }}) Deleting directory D:\clement\workspaces\iPOJO-Dev\hello.client\target\site
-\[INFO\]({{ refs.info.path }}) \[resources:resources\]
-\[INFO\]({{ refs.info.path }}) Using default encoding to copy filtered resources.
-\[INFO\]({{ refs.info.path }}) Copying 1 resource
-\[INFO\]({{ refs.info.path }}) \[compiler:compile\]
-\[INFO\]({{ refs.info.path }}) Compiling 1 source file to D:\clement\workspaces\iPOJO-Dev\hello.client\target\classes
-\[INFO\]({{ refs.info.path }}) \[resources:testResources\]
-\[INFO\]({{ refs.info.path }}) Using default encoding to copy filtered resources.
-\[INFO\]({{ refs.info.path }}) Resource directory does not exist: D:\clement\workspaces\iPOJO-Dev\hello.client\src\test\resources
-\[INFO\]({{ refs.info.path }}) \[compiler:testCompile\]
-\[INFO\]({{ refs.info.path }}) No sources to compile
-\[INFO\]({{ refs.info.path }}) \[surefire:test\]
-\[INFO\]({{ refs.info.path }}) No tests to run.
-\[INFO\]({{ refs.info.path }}) \[bundle:bundle\]
-\[INFO\]({{ refs.info.path }}) \[org.apache.felix.ipojo.:ipojo-bundle \{execution: default}\]
-\[INFO\]({{ refs.info.path }}) Start bundle manipulation
-\[INFO\]({{ refs.info.path }}) Metadata File : D:\clement\workspaces\iPOJO-Dev\hello.client\target\classes\metadata.xml
-\[INFO\]({{ refs.info.path }}) Input Bundle File : D:\clement\workspaces\iPOJO-Dev\hello.client\target\hello.client-0.0.1.jar
-\[INFO\]({{ refs.info.path }}) Bundle manipulation - SUCCESS
-\[INFO\]({{ refs.info.path }}) \[install:install\]
-\[INFO\]({{ refs.info.path }}) Installing D:\clement\workspaces\iPOJO-Dev\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\]({{ refs.info.path }}) \-----------------------------------------------------------------------\-
-\[INFO\]({{ refs.info.path }}) BUILD SUCCESSFUL
-\[INFO\]({{ refs.info.path }}) \-----------------------------------------------------------------------\-
-\[INFO\]({{ refs.info.path }}) Total time: 9 seconds
-\[INFO\]({{ refs.info.path }}) Finished at: Mon Aug 13 14:04:55 CEST 2007
-\[INFO\]({{ refs.info.path }}) Final Memory: 6M/13M
-\[INFO\]({{ refs.info.path }}) \-----------------------------------------------------------------------\-
-{div}
+
+ :::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:
-{div:class=pom}
-<plugin>
- <groupId>org.apache.felix</groupId>
- <artifactId>maven-ipojo-plugin</artifactId>
- <version>1.6.0</version>
- <executions>
- <execution>
- <goals>
- <goal>ipojo-bundle</goal>
- </goals>
- <configuration>
- {color:red}<metadata>ipojo/meta.xml</metadata>{color}
- </configuration>
- </execution>
- </executions>
-</plugin>
-{div}
+
+ :::xml
+ <plugin>
+ <groupId>org.apache.felix</groupId>
+ <artifactId>maven-ipojo-plugin</artifactId>
+ <version>1.8.6</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`.
-*Note:* The directory support was introduced in the `1.7.0` version. Previously only one metadata file was found.
-*Compatibility:* 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.
+<div class="alert alert-info">
+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.
+</div>
The second option allows skipping annotations processing, by using the `ignoreAnnotations` element:
-{div:class=pom}
-<plugin>
- <groupId>org.apache.felix</groupId>
- <artifactId>maven-ipojo-plugin</artifactId>
- <version>1.6.0</version>
- <executions>
- <execution>
- <goals>
- <goal>ipojo-bundle</goal>
- </goals>
- <configuration>
- {color:red}<ignoreAnnotations>true</ignoreAnnotations>{color}
- </configuration>
- </execution>
- </executions>
-</plugin>
-{div}
+
+ :::xml
+ <plugin>
+ <groupId>org.apache.felix</groupId>
+ <artifactId>maven-ipojo-plugin</artifactId>
+ <version>1.8.6</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:
-{div:class=pom}
-<plugin>
- <groupId>org.apache.felix</groupId>
- <artifactId>maven-ipojo-plugin</artifactId>
- <version>1.6.0</version>
- <executions>
- <execution>
- <goals>
- <goal>ipojo-bundle</goal>
- </goals>
- <configuration>
- {color:red}<ignoreEmbeddedSchemas>true</ignoreEmbeddedSchemas>{color}
- </configuration>
- </execution>
- </executions>
-</plugin>
-{div}
+
+ :::xml
+ <plugin>
+ <groupId>org.apache.felix</groupId>
+ <artifactId>maven-ipojo-plugin</artifactId>
+ <version>1.8.6</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:
+ :::sh
mvn org.apache.maven.plugins:maven-archetype-plugin:generate \
-DarchetypeArtifactId=maven-ipojo-plugin \
-DarchetypeGroupId=org.apache.felix \
@@ -184,57 +193,58 @@ This command generates :
The generated project uses iPOJO annotation and is ready to be deployed.
-<div class="info" markdown="1">
-**Maven Archetype**
+<div class="alert alert-info" markdown="1">
+<h4>Maven Archetype</h4>
The maven-ipojo-plugin archetype generates a pom file using the latest released version of the maven-ipojo-plugin.
</div>
## 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.
-{div:class=pom}
-<plugin>
- <groupId>org.apache.felix</groupId>
- <artifactId>maven-ipojo-plugin</artifactId>
- <version>1.6.0</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>
-{div}
+
+ :::xml
+ <plugin>
+ <groupId>org.apache.felix</groupId>
+ <artifactId>maven-ipojo-plugin</artifactId>
+ <version>1.8.6</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>
+
Modified: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-webconsole-plugin.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-webconsole-plugin.mdtext?rev=1465947&r1=1465946&r2=1465947&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-webconsole-plugin.mdtext (original)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-webconsole-plugin.mdtext Tue Apr 9 09:37:22 2013
@@ -5,13 +5,12 @@ Title: iPOJO Webconsole Plugin
# iPOJO Webconsole Plugin
-*If you like the [Apache Felix Web Console]({{ refs.apache-felix-web-console.path }}), 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.*
+*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.*
-{div:class=toc}
[TOC]
-{div}
## Features
+
* Lists created instances
* Gives details about instances (state, factory, required services, provided services, used instances, and raw architecture)
* Lists available factories
@@ -19,26 +18,10 @@ Title: iPOJO Webconsole Plugin
* List available handlers
* Instance and Factories are `navigable`, so you can easily understand the system architecture
-In other words, it replace the [`arch`]({{ refs.ipojo-arch-command.path }}) command.
-
## Using the plugin
To use the plugin you need an OSGi platform with:
-* an HTTP Service ([Download]({{ refs.downloads.path }}))
+
+* a HTTP Service
* The Apache Felix Webconsole
* iPOJO
-* The iPOJO Plugin (compiled with iPOJO)
-
-To start the web console, please refer to the [Apache Felix web console documentation]({{ refs.apache-felix-web-console.path }}).
-
-You can also use OBR to deploy the web console and the plugin:
-{code:none}
-obr start "Apache Felix Web Management Console"
-
-
- This command deploys an HTTP Service, the web console, iPOJO (core) and the plugin.
-
- h2. Screenshots
- !Picture 5.png|thumbnail! !Picture 6.png|thumbnail! !Picture 7.png|thumbnail!
- !Picture 8.png|thumbnail! !Picture 9.png|thumbnail! !Picture 10.png|thumbnail!
- \\
- \\
+* The iPOJO Web console plugin
\ No newline at end of file