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
[email protected](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:[email protected]]; after subscribing, email questions
or feedback to [mailto:[email protected]]
