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/02/13 08:25:24 UTC
svn commit: r1445489 - in
/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide:
./ describing-components/ ipojo-advanced-topics/
Author: clement
Date: Wed Feb 13 07:25:24 2013
New Revision: 1445489
URL: http://svn.apache.org/r1445489
Log:
update pages to new CMS
Added:
felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/JMXHandler_1.png (with props)
felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/JMXHandler_2.png (with props)
felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/JMXHandler_3.png (with props)
Modified:
felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components.mdtext
felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/ipojo-jmx-handler.mdtext
felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/temporal-service-dependency.mdtext
felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/white-board-pattern-handler.mdtext
felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/combining-ipojo-and-configuration-admin.mdtext
Modified: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components.mdtext?rev=1445489&r1=1445488&r2=1445489&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components.mdtext (original)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components.mdtext Wed Feb 13 07:25:24 2013
@@ -8,12 +8,9 @@ Title: Describing 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?"*
-{div:class=toc}
-[TOC]
-{div}
-
## Core features
Core features are provided with the iPOJO runtime bundles. You can use it directly, as soon as the iPOJO runtime is deployed.
+
* [How to require a service]({{ refs.service-requirement-handler.path }})
* [How to publish and provide a service]({{ refs.providing-osgi-services.path }})
* [How to react to lifecycle state changes]({{ refs.lifecycle-callback-handler.path }})
Added: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/JMXHandler_1.png
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/JMXHandler_1.png?rev=1445489&view=auto
==============================================================================
Binary file - no diff available.
Propchange: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/JMXHandler_1.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/JMXHandler_2.png
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/JMXHandler_2.png?rev=1445489&view=auto
==============================================================================
Binary file - no diff available.
Propchange: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/JMXHandler_2.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Added: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/JMXHandler_3.png
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/JMXHandler_3.png?rev=1445489&view=auto
==============================================================================
Binary file - no diff available.
Propchange: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/JMXHandler_3.png
------------------------------------------------------------------------------
svn:mime-type = application/octet-stream
Modified: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/ipojo-jmx-handler.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/ipojo-jmx-handler.mdtext?rev=1445489&r1=1445488&r2=1445489&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/ipojo-jmx-handler.mdtext (original)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/ipojo-jmx-handler.mdtext Wed Feb 13 07:25:24 2013
@@ -7,13 +7,12 @@ Title: 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).*
-{div:class=toc}
[TOC]
-{div}
## 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 .
@@ -22,6 +21,7 @@ The handler allows to:
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 JDK), MOSGi (provided with Felix), ...
To use MOSGi, you have to deploy at least the following three bundles of MOSGi:
+
* org.apache.felix.mosgi.jmx.agent
* org.apache.felix.mosgi.jmx.registry
* org.apache.felix.mosgi.jmx.rmiconnector
@@ -36,6 +36,7 @@ The JMX handler is available in the Feli
The handler needs to be added in the metadata.xml, you just add a namespace (e.g., jmx) :
+ :::xml
<ipojo xmlns:jmx="org.apache.felix.ipojo.handlers.jmx">
...
</ipojo>
@@ -43,56 +44,132 @@ The handler needs to be added in the met
So, you could now expose in JMX properties and methods of your component. They are surrounded by the <jmx:config>
tag.
+ :::xml
<jmx:config>
<jmx:property name="message" field="m_msg" rights="w" notification="true"/>
<jmx:method name="doSomethingBad"/>
<jmx:method name="doSomethingGood"/>
</jmx:config>
-<div class="info" markdown="1">
-**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.
+<div class="alert alert-info info" markdown="1">
+<h4>Serialization</h4>
+<p>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.</p>
</div>
+
## 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
-{div:class=borderedTable}
-|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"|
-|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.|
-{div}
-
+
+<table class="table table-bordered">
+<thead>
+ <tr>
+ <th>Attribute name</th>
+ <th>Required</th>
+ <th>Description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>objectName</td>
+ <td>No</td>
+ <td>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. <em>Example:</em> <code>"my.domain:type=myType,name=myName"</code></td>
+ </tr>
+
+ <tr>
+ <td>domain</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>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.</td>
+ </tr>
+
+ <tr>
+ <td>usesMOSGi</td>
+ <td>No</td>
+ <td>Determines if the component must be register on the MOSGi MBean server or not.</td>
+ </tr>
+
+ <tr>
+ <td>preRegister, postRegister, preDeregister, postDeregister</td>
+ <td>No</td>
+ <td>These attributes allow to specify methods to carry out operations before and after being registered or unregistered from the MBean server.</td>
+ </tr>
+ </tbody>
+</table>
+
## Properties attributes
-{div:class=borderedTable}
-|Attribute name|Required|Description|
-|--|--|--|
-|field|YES|The name of the component's field to expose.|
-|name|NO|The name of the property as it will appear in JMX. If unspecified, the default value is the name of the exposed field.|
-|rights|NO|Specify the access permission of the exposed field. The accepted values are :
-* "r" : read-only access, the default value.
-* "w" : read and write access.|
-|notification|NO|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.|
-{div}
+
+<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
-{div:class=borderedTable}
-|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.|
-{div}
+
+<table class="table table-bordered">
+<thead>
+ <tr>
+ <th>Attribute name</th>
+ <th>Required</th>
+ <th>Description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>name</td>
+ <td>Yes</td>
+ <td>The name of the method to expose. If multiple methods have the same name, all of them are exposed.</td>
+ </tr>
+
+ <tr>
+ <td>description</td>
+ <td>No</td>
+ <td>The description of the exposed method, as it will appear in JMX.</td>
+ </tr>
+ </tbody>
+</table>
## Examples
@@ -102,8 +179,8 @@ In this part, we will give you a complet
In first time we create a simple component named MyComponent. We have add two fields named m*level (int) and m*message (String).
- public class
- MyComponent ... {
+ :::java
+ public class MyComponent ... {
// Exposed attributes
private String m_message;
private int m_level;
@@ -112,6 +189,7 @@ In first time we create a simple compone
We expose now the attributes in the jmx:config
tag in the metadata :
+ :::xml
<?xml version="1.0" encoding="UTF-8"?>
<iPOJO xmlns:jmx="org.apache.felix.ipojo.handlers.jmx">
<component className="...MyComponent"
@@ -134,12 +212,14 @@ tag in the metadata :
</iPOJO>
Now, we could get and write the properties in the JConsole :
-!JMXHandler_1.png!
+
+<img src="JMXHandler_1.png">
### Exposing Methods
We could now add methods in the initial class :
+ :::java
/**
Do something good
*/
@@ -163,6 +243,7 @@ We could now add methods in the initial
We add corresponding tags in the metadata to expose these methods:
+ :::xml
<!-- Exposed methods -->
<jmx:method name="doSomethingGood"
description="Do something good."/>
@@ -173,12 +254,13 @@ We add corresponding tags in the metadat
Now the three methods are exposed in the operations tab of the JConsole. We can invoked these methods :
-!JMXHandler_2.png!
+<img src="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:
+ :::xml
<jmx:property field="m_level"
name="The level"
rights="r"
@@ -186,48 +268,50 @@ You could subscribe to attribute notific
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 :
-!JMXHandler_3.png!
+<img src="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:
-{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)
-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;
+ :::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 <code>@org.apache.felix.ipojo.handlers.jmx.Config</code> (<code>@Config</code> if the package it correctly imported) annotation is a type annotation (so placed on the <code>class</code> 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.
+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.
- \\
- \\
+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.
Modified: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/temporal-service-dependency.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/temporal-service-dependency.mdtext?rev=1445489&r1=1445488&r2=1445489&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/temporal-service-dependency.mdtext (original)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/temporal-service-dependency.mdtext Wed Feb 13 07:25:24 2013
@@ -1,20 +1,17 @@
translation_pending: true
Title: Temporal Service Dependency
-
-
# The temporal dependency handler
*Regular service dependencies participate to the instance lifecycle. Moreover, the injected service object is either available or not available. A temporal dependency handler is a little different and provides a different resolution pattern. Indeed, the temporal dependency does not invalidate the instance. Moreover, if not available, the temporal dependency waits (and so blocks the current thread) for a provider. Of course, the maximum waiting time can be specified. If a timeout occurs, the handler throws a Runtime Exception.*
-{div:class=toc}
[TOC]
-{div}
## Using the handler
First of all, you need to configure the component type to use the handler such as:
+ :::xml
<iPOJO xmlns:temporal="org.apache.felix.ipojo.handler.temporal">
<component
className="org.apache.felix.ipojo.example.Temporal">
@@ -33,8 +30,9 @@ Using the field in your code will try to
You can also use annotations:
+ :::java
@Component
- public class Temporal {
+ public class UseTemporal {
@Temporal // was org.apache.felix.ipojo.handler.temporal.Requires before the 1.7.0
private FooService mytemporal;
@@ -45,22 +43,26 @@ You can also use annotations:
## Configuration
The handler has only one mandatory attributes:
+
* Field: the implementation field supporting the dependency (not needed with annotations)
The handler supports on specific optional attributes:
-* Timeout: the maximum time waited in order to find a provider (default: 3s). For an infinite timeout, the timeout value is either "infinite" or "-1".
-* OnTimeout: specifies the action to do when the timeout occurs. Four actions are supported: null, nullable, empty-array, default-implementation. By default, no action is specified, and an exception occurs when the timeout is reached.
+
+* Timeout: the maximum time waited in order to find a provider (default: 3s). For an infinite timeout, the timeout value is either `infinite` or `-1`.
+* OnTimeout: specifies the action to do when the timeout occurs. Four actions are supported: `null`, `nullable`, `empty-array`, `default-implementation`. By default, no action is specified, and an exception occurs when the timeout is reached.
The attributes from "regular" dependencies are also supported (like filter).
-OnTimeout actions
+
+## OnTimeout actions
When a timeout occurs, you can specify what the handler must do. By default, it throws a runtime exception. However, four others actions can be set in the 'onTimeout' attribute.
-* The null action (onTimeout="null") will return "null" instead of the service object.
-* The "nullable" action (onTimeout="nullable") will return a "Nullable" object instead of the service object. This object is a fake but can be used a regular service object. However, invoking actions on this object will do nothing. In the case of aggregate dependency, an array containing a "nullable" object is returned.
-* The empty action is only supported for aggregate dependency (the field must be an array). In this case, an empty-array is returned. (In the 1.2.0 version, the `empty-array` attribute became `empty`)
-* The default-implementation action is a little different. Instead of specifying the action, you need to specify the default-implementation (the qualified class name) that you want to use. For example onTimeout="o.a.f.i.MyDefaultLogServiceImpl". In this case, the handler will inject an instance of this object instead of a real service object. On aggregate dependency, an array with one default-implementation object is returned.
+* The null action (`onTimeout="null"`) will return `null` instead of the service object.
+* The nullable action (`onTimeout="nullable"`) will return a "Nullable" object instead of the service object. This object is a fake but can be used a regular service object. However, invoking actions on this object will do nothing. In the case of aggregate dependency, an array containing a "nullable" object is returned.
+* The empty action is only supported for aggregate dependency (the field must be an array). In this case, an empty array is returned. (In the 1.2.0 version, the `empty-array` attribute became `empty`)
+* The default-implementation action is a little different. Instead of specifying the action, you need to specify the default-implementation (the qualified class name) that you want to use. For example `onTimeout="o.a.f.i.MyDefaultLogServiceImpl"`. In this case, the handler will inject an instance of this object instead of a real service object. On aggregate dependency, an array with one default-implementation object is returned.
+ :::xml
<iPOJO xmlns:temporal="org.apache.felix.ipojo.handler.temporal">
<component
className="org.apache.felix.ipojo.example.Temporal">
@@ -76,6 +78,7 @@ When a timeout occurs, you can specify w
This is equivalent to:
+ :::java
@Component
public class Temporal {
@@ -88,6 +91,7 @@ This is equivalent to:
## Collection injection
Temporal dependencies can also be injected inside Collection. To achieve this, the 'specification' attribute must indicates the looked specification, and the field must be a Collection.
+ :::xml
<iPOJO xmlns:temporal="org.apache.felix.ipojo.handler.temporal">
<component
className="org.apache.felix.ipojo.example.Temporal">
@@ -103,6 +107,7 @@ Temporal dependencies can also be inject
This is equivalent to:
+ :::java
@Component
public class Temporal {
@@ -115,11 +120,11 @@ This is equivalent to:
## Proxy injection
Temporal dependencies can also be injected as proxies. So it is possible to give the temporal dependency to helper object.
On 'scalar' dependencies, the service lookup is executed during an operation invocation. Timeout policies are also executed is the lookup failed.
-On aggregate dependencies (necessary Collection), the service lookup is executed when the iterator(), and toArray(...) methods are invoked. Timeout policies
-are also executed if the lookup failed. Proxies are enabled by default since the 1.7.0 version.
+On aggregate dependencies (necessary Collection), the service lookup is executed when the iterator(), and toArray(...) methods are invoked. Timeout policies are also executed if the lookup failed. Proxies are enabled by default since the 1.7.0 version.
To set a temporal dependency as a proxy, just add the `proxy` attribute as follows:
+ :::xml
<iPOJO xmlns:temporal="org.apache.felix.ipojo.handler.temporal">
<component
className="org.apache.felix.ipojo.example.Temporal">
@@ -134,13 +139,5 @@ To set a temporal dependency as a proxy,
</iPOJO>
-By default, proxies are *enabled*. Setting proxy to `false` disables them.
-
-## Download
-
-The handler is available on the [download]({{ refs.download.path }}) page.
-Sources are available on the Felix trunk at the following location: [http://svn.apache.org/repos/asf/felix/trunk/ipojo/handler/temporal](http://svn.apache.org/repos/asf/felix/trunk/ipojo/handler/temporal).
-
-
-
+By default, proxies are **enabled**. Setting proxy to `false` disables them.
Modified: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/white-board-pattern-handler.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/white-board-pattern-handler.mdtext?rev=1445489&r1=1445488&r2=1445489&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/white-board-pattern-handler.mdtext (original)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/white-board-pattern-handler.mdtext Wed Feb 13 07:25:24 2013
@@ -6,22 +6,21 @@ Title: White Board Pattern Handler
# The white board pattern handler
The objective of this handler is to simplify the development of white-board architecture. This architecture-style is based is very close to the extender architecture style but relies on services instead of bundles.
-{div:class=toc}
[TOC]
-{div}
-<div class="info" markdown="1">
-**Change in the 1.2.0**
-The 1.2.0 uses the namespace `org.apache.felix.ipojo.whiteboard` instead of `org.apache.felix.ipojo.white-board-pattern`
+<div class="alert alert-info info" markdown="1">
+<h4>Change in the 1.2.0</h4>
+<p>The 1.2.0 uses the namespace <code>org.apache.felix.ipojo.whiteboard</code> instead of <code>org.apache.felix.ipojo.white-board-pattern</code></p>
</div>
-<div class="info" markdown="1">
-** Change in the 1.7.0**
-The 1.7.0 has introduced a new annotations allowing to declare several whiteboard patterns in the same class. The ``@Whiteboards}} annotation is not available in previous version.
+<div class="alert alert-info info" markdown="1">
+<h4>Change in the 1.7.0</h4>
+<p>The 1.7.0 has introduced a new annotations allowing to declare several whiteboard patterns in the same class. The <code>@Whiteboards</code> annotation is not available in previous version.</p>
</div>
## The whiteboard pattern
A whiteboard is based on two different roles:
+
* A consumer looking to special services or a services published with a special mark
* Looked services
@@ -31,24 +30,24 @@ Implementing a white board pattern could
## Using the handler
First of all, you need to configure the component type to use the handler such as:
+ :::xml
<ipojo xmlns:wbp="org.apache.felix.ipojo.whiteboard">
- <component
- className="org.apache.felix.ipojo.test.FooWhiteBoardPattern"
- >
- <wbp:wbp
- filter="(my.property=1)"
- onArrival="onArrival"
- onDeparture="onDeparture"
- onModification="onModification"
- />
-
- </component>
+ <component
+ className="org.apache.felix.ipojo.test.FooWhiteBoardPattern">
+ <wbp:wbp
+ filter="(my.property=1)"
+ onArrival="onArrival"
+ onDeparture="onDeparture"
+ onModification="onModification"
+ />
+ </component>
Notice that, this handler is an external handler. So, it uses the "org.apache.felix.ipojo.whiteboard" namespace.
-Once described, you can implement your component. The methods specified methods will be called when a matching services arrives or leaves or are modified. The modification callback is optional. A matching service is detected by confronting the service reference against the specified filter.
+Once described, you can implement your component. The methods specified methods will be called when a matching services arrives or leaves or are modified.The modification callback is optional. A matching service is detected by confronting the service reference against the specified filter.
The filter can target specific service interface (with the objectclass property) or property values.
In the previous example, these methods could be:
+ :::java
public class FooWhiteBoardPattern {
List list = new ArrayList();
int modifications = 0;
@@ -66,6 +65,7 @@ All methods received the arriving, leavi
You can also use annotation to declare the same component:
+ :::java
@Component
@Wbp(
filter="my.property=1",
@@ -89,70 +89,64 @@ You can also use annotation to declare t
## Configuration
The handler has only three mandatory attributes:
+
* Filter: filter use to discover matching filter.
* onArrival: declaring the method to invoke when a matching service arrives
* onDeparture: declaring the method to invoke when a matching service leaves
The onModification attribute is optional. This method is called when an injected service reference is modified but stills valid against the filter.
-<div class="note" markdown="1">
-**Notifications**
+
+<div class="alert alert-info info" markdown="1">
+<h4>Notifications</h4>
The implementation will be notified of arrivals, modifications and departures, despite the instance is invalid. Indeed, the implementation must release all objects created from another bundle as soon it leaves.
</div>
+
## Configuring the handler with annotations
It is possible to configure the handler with a simple annotation available in the annotation pack ('annotation' project in the iPOJO trunk). Here is an example of usage:
-{code:java}
-import org.apache.felix.ipojo.annotations.Component;
-import org.osgi.framework.ServiceReference;
-
-@Component
-@org.apache.felix.ipojo.whiteboard.Wbp(filter="(foo=true)",
- onArrival="onArrival",
- onDeparture="onDeparture",
- onModification="onModification")
-public class WhiteBoardExemple {
-
- public void onArrival(ServiceReference ref) {
- // do something
- }
-
- public void onDeparture(ServiceReference ref) {
- // do something
- }
-
- public void onModification(ServiceReference ref) {
- // do something
- }
-}
+ :::java
+ import org.apache.felix.ipojo.annotations.Component;
+ import org.osgi.framework.ServiceReference;
-
- The {{onModification}} attribute is optional.The {{filter}} attribute allows setting the service filter.
-
- In the 1.7.0, a new annotation was introduced to support the declaration of several whiteboard patterns in the same component:
+ @Component
+ @org.apache.felix.ipojo.whiteboard.Wbp(filter="(foo=true)",
+ onArrival="onArrival",
+ onDeparture="onDeparture",
+ onModification="onModification")
+ public class WhiteBoardExemple {
+
+ public void onArrival(ServiceReference ref) {
+ // do something
+ }
+
+ public void onDeparture(ServiceReference ref) {
+ // do something
+ }
+
+ public void onModification(ServiceReference ref) {
+ // do something
+ }
-@Component
-@Whiteboards(whiteboards={
- @Wbp(filter="(foo=true)",
- onArrival="onArrival",
- onDeparture="onDeparture",
- onModification="onModification"),
- @Wbp(filter="(bar=true)",
- onArrival="onArrival2",
- onDeparture="onDeparture2")}
-)
-public class WhiteBoardExemple {
+ }
- // ...
-
-}
-
-
-
-## Download
-The handler is available on the [download]({{ refs.download.path }}) page.
-Sources are available on the Felix trunk at the following location: [http://svn.apache.org/repos/asf/felix/trunk/ipojo/handler/whiteboard](http://svn.apache.org/repos/asf/felix/trunk/ipojo/handler/whiteboard).
-
-
-
+The `onModification` attribute is optional.The `filter` attribute allows setting the service filter.
+
+In the 1.7.0, a new annotation was introduced to support the declaration of several whiteboard patterns in the same component:
+ :::java
+ @Component
+ @Whiteboards(whiteboards={
+ @Wbp(filter="(foo=true)",
+ onArrival="onArrival",
+ onDeparture="onDeparture",
+ onModification="onModification"),
+ @Wbp(filter="(bar=true)",
+ onArrival="onArrival2",
+ onDeparture="onDeparture2")}
+ )
+ public class WhiteBoardExemple {
+
+ // ...
+
+ }
Modified: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/combining-ipojo-and-configuration-admin.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/combining-ipojo-and-configuration-admin.mdtext?rev=1445489&r1=1445488&r2=1445489&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/combining-ipojo-and-configuration-admin.mdtext (original)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/combining-ipojo-and-configuration-admin.mdtext Wed Feb 13 07:25:24 2013
@@ -7,9 +7,7 @@ Title: Combining iPOJO and Configuration
*This page presents how creating, reconfiguring and destroying iPOJO component instance with the OSGi Configuration Admin.*
-{div:class=toc}
[TOC]
-{div}
## Configuration Admin
@@ -21,7 +19,7 @@ As the configuration admin offer an admi
* Create new component instances
* Configuring / reconfiguring these instances
* Destroying these instances
-* Reconfiguring instances by using Managed Services (not addressed in this page, see [here]({{ refs.configuration-handler.path }}) for further information)
+* Reconfiguring instances by using Managed Services (not addressed in this page, see [here](/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/configuration-handler.html) for further information)
The configuration admin is persistent, so stored configuration will be reload it the framework restarts.
Moreover, using the configuration admin allows avoiding describing instances inside iPOJO metadata file. These instances are created by inserting new configurations in the configuration admin.
@@ -31,12 +29,14 @@ Moreover, using the configuration admin
iPOJO has a component type concept. For each (public) component type, a `ManagedServiceFactory` is published. For each configurations matching with the component type from the Configuration Admin, a new component instance is created. Moreover, when this configuration is updated, the instance is dynamically reconfigured. If the configuration is removed, the instance is disposed.
If a new Configuration is created:
+
* If the factory is available or an instance is create immediately,
* Else the factory is not available and the instance will be created as soon as the factory appears.
## Examples
This section presents 3 examples about the management of iPOJO instances with the configuration admin:
+
* A simple instantiation example and destruction
* An instantiation with property injection and dynamic reconfiguration
* A property propagation example
@@ -45,19 +45,22 @@ All these examples are downloadable [her
To compile the project, launch ant from the *config.admin.tutorial* directory
Then, you can launch Felix by launching the following command from the `felix` directory:
- Java -jar bin/felix.jar
+ :::sh
+ java -jar bin/felix.jar
### Prerequisites
Let's take 4 Felix shell commands to manage configuration admin configurations (available in the example archive):
-* `create_conf <type> <property-key=property-value>\*` allows to create a new Factory Configuration attached to the given type. The configuration contains the given properties.
-* `update*conf <configuration*name> < property-key=property-value>\*` allows to update the configuration with the given name with the given properties.
-* `delete*conf <configuration*name>` allows deleting the configuration with the given name. If the name is 'all', delete all stored configurations.
+
+* `create_conf <type> <property-key=property-value>` allows to create a new Factory Configuration attached to the given type. The configuration contains the given properties.
+* `update_conf <configuration*name> < property-key=property-value>` allows to update the configuration with the given name with the given properties.
+* `delete_conf <configuration*name>` allows deleting the configuration with the given name. If the name is 'all', delete all stored configurations.
* `list_conf` allows listing all stored configuration.
Moreover iPOJO and an implementation of the Configuration Admin must be deployed on the gateway:
+ :::sh
-> ps
START LEVEL 1
ID State Level Name
@@ -73,15 +76,17 @@ Moreover iPOJO and an implementation of
### Simple Instantiation
Imagine the following very simple component implementation:
-{code:java}
-public class Hello1 {
- public Hello1() {
- System.out.println("Hello");
+
+ :::java
+ public class Hello1 {
+ public Hello1() {
+ System.out.println("Hello");
+ }
}
-}
- The component type is defined with following metadata:
- {code:xml}
+The component type is defined with following metadata:
+
+ :::xml
<component
classname="org.apache.felix.ipojo.example.ca.component.Hello1"
factory="hello1" immediate="true" architecture="true"/>
@@ -89,6 +94,7 @@ public class Hello1 {
The defined component type (*Hello1*) just creates a Hello1 object when the instance is created (thanks to the *immediate* attribute).
So if we deploy this bundle and add a consistent configuration we obtain (note that bundle need to be already compiled):
+ :::sh
-> start file:..\config.admin.tutorial\output\config.admin.tutorial.jar
-> create_conf org.apache.felix.ipojo.example.ca.component.Hello1
Insert the configuration : {org.apache.felix.ipojo.example.ca.component.Hello1}
@@ -97,6 +103,7 @@ So if we deploy this bundle and add a co
*Note*: Debug messages from the configuration admin were removed
So as predicted, the Hello message appears. To be really sure of the creating, we can ask for the instance architecture (the component type allows architecture introspection thank to the architecture attribute):
+ :::sh
-> arch
Instance ArchCommand -> valid
Instance org.apache.felix.ipojo.example.ca.component.Hello1.e40fe80a-2c0d-4c51-b00b-a82565874cd8 -> valid
@@ -119,6 +126,7 @@ So as predicted, the Hello message appea
So, the instance is correctly created. The name of the instance was created by the configuration admin. It could change according to your configuration admin implementation.
Then, we can delete the instance by removing the configuration from the configuration admin:
+ :::sh
-> delete_conf
org.apache.felix.ipojo.example.ca.component.Hello1.e40fe80a-2c0d-4c51-b00b-a82565874cd8
Delete the configuration :
@@ -131,19 +139,22 @@ So, arch does no more displayed any *hel
### Reconfiguring instances with the Configuration Admin
Imagine the following component implementation:
-{code:java}
-public class Hello2 {
- String m_name;
- public void stop() {
- System.out.println("Good by " + m_name);
- }
- public void setName(String newName) {
- m_name = newName;
- System.out.println("Hello " + m_name);
- }
- And the following metadata:
- {code:xml}
+ :::java
+ public class Hello2 {
+ String m_name;
+ public void stop() {
+ System.out.println("Good by " + m_name);
+ }
+ public void setName(String newName) {
+ m_name = newName;
+ System.out.println("Hello " + m_name);
+ }
+ }
+
+And the following metadata:
+
+ :::xml
<component
classname="org.apache.felix.ipojo.example.ca.component.Hello2"
factory="hello2" immediate="true" architecture="true">
@@ -155,11 +166,14 @@ public class Hello2 {
The defined component type (*Hello2*) write "Hello + $name" when the property 'to' (attached to the field m_name) receive a new value. A value is necessary insert in the instance configuration. Moreover when killed, the instance will display a "Good By" message.
Let's play a simple scenario:
+
* Create a Hello2 instance
* Update the instance configuration
* Kill the created instance
+
+ :::sh
-> create_conf org.apache.felix.ipojo.example.ca.component.Hello2 to=ipojo
Insert the configuration :
{service.factoryPid=org.apache.felix.ipojo.example.ca.component.Hello2, to=ipojo}
@@ -183,9 +197,9 @@ Let's play a simple scenario:
org.apache.felix.ipojo.example.ca.component.Hello2.75082279-9b4b-4c49-b0e0-8efb38b67aa3
Good by felix-> list_conf
-In this simple scenario, we see that when the configuration is updated, the instance receives the new value. The *setName* method is immediately invoked to inject the new value. Moreover, when the configuration is deleted, the instance is going to be killed: the "Good Bye" message appears and the instance is disposed.
-Obviously it is possible to create several instance of the same type:
+In this simple scenario, we see that when the configuration is updated, the instance receives the new value. The *setName* method is immediately invoked to inject the new value. Moreover, when the configuration is deleted, the instance is going to be killed: the "Good Bye" message appears and the instance is disposed. Obviously it is possible to create several instance of the same type:
+ :::sh
-> create_conf org.apache.felix.ipojo.example.ca.component.Hello2 to=ipojo
Insert the configuration :
{service.factoryPid=org.apache.felix.ipojo.example.ca.component.Hello2, to=ipojo}
@@ -201,15 +215,16 @@ Obviously it is possible to create sever
The 'arch' command displays the two created instances.
-<div class="info" markdown="1">
-**Delete configurations**
-you can delete all created configurations with the *delete*conf all_ command
+<div class="alert alert-info info" markdown="1">
+<h4>Delete configurations</h4>
+<p>you can delete all created configurations with the delete_conf all command</p>
</div>
### Property Propagation
It is possible to propagate the instance configuration to the published service properties. To activate property propagation you need to write the *'propagation'* attribute in the 'properties' element as in
+ :::xml
<component
classname="org.apache.felix.ipojo.example.ca.component.Hello3"
factory="hello3" architecture="true">
@@ -219,15 +234,16 @@ It is possible to propagate the instance
</properties>
</component>
-The defined type provides a service. Moreover it supports properties propagation. So all property, except listed one (m_name), will be published inside the provided services.
-So create an instance of the Hello3 component type as follow:
+The defined type provides a service. Moreover it supports properties propagation. So all property, except listed one (m_name), will be published inside the provided services. So create an instance of the Hello3 component type as follow:
+ :::sh
-> create_conf org.apache.felix.ipojo.example.ca.component.Hello3
Insert the configuration :
{service.factoryPid=org.apache.felix.ipojo.example.ca.component.Hello3}
Then, you can check provided services with the *services 7* command
+ :::sh
-> services 7
// Factories and Managed Service factories //
----
@@ -241,6 +257,7 @@ Then, you can check provided services wi
Now, we update the instance configuration with a new property 'p1':
+ :::sh
-> update_conf
org.apache.felix.ipojo.example.ca.component.Hello3.a5ca5901-6e20-4636-8805-fbca2db1d68b p1=v1
Update the configuration : {p1=v1}
@@ -259,6 +276,7 @@ Now, we update the instance configuratio
Remark that the new property p1 is published.
Now we can remove this property by reconfiguring the instance with an empty configuration:
+ :::sh
-> update_conf
org.apache.felix.ipojo.example.ca.component.Hello3.a5ca5901-6e20-4636-8805-fbca2db1d68b
Update the configuration : {}
@@ -275,9 +293,6 @@ Now we can remove this property by recon
The service does no more publish the `p1` property.
-## Conclusion
-
-This page has presented how to combine the configuration admin and iPOJO. You can also use [FileInstall in combination with iPOJO and the Configuration Admin](http://ipojo-dark-side.blogspot.com/2009/04/ipojo-and-file-install-configuring.html). Subscribe to the Felix users mailing list by sending a message to [mailto:users-subscribe@felix.apache.org]; after subscribing, email questions or feedback to [mailto:users@felix.apache.org]