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/11 10:16:10 UTC
svn commit: r1444686 - in
/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components:
extender-pattern-handler.mdtext providing-osgi-services.mdtext
service-requirement-handler.mdtext
Author: clement
Date: Mon Feb 11 09:16:09 2013
New Revision: 1444686
URL: http://svn.apache.org/r1444686
Log:
migrate pages to new CMS
Modified:
felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/extender-pattern-handler.mdtext
felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/providing-osgi-services.mdtext
felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/service-requirement-handler.mdtext
Modified: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/extender-pattern-handler.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/extender-pattern-handler.mdtext?rev=1444686&r1=1444685&r2=1444686&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/extender-pattern-handler.mdtext (original)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/extender-pattern-handler.mdtext Mon Feb 11 09:16:09 2013
@@ -6,20 +6,20 @@ Title: Extender Pattern Handler
# The extender pattern handler
*The objective of this handler is to simplify the development of extender-based architecture. This architecture-style is based on two different entities:*
+
* *The extender (also called host)*
* *The extensions*
-{div:class=toc}
[TOC]
-{div}
## The Extender pattern
This architecture-style is based on two different roles:
+
* The extender
* The extension
-!extender.png!
+<img src="extender.png">
The relation is basically a 1..n relation. The extender tracks extensions. The particularity of this architecture-style is that extensions are packaged in different bundles. An extension is detected by analyzing the bundle. Indeed these bundles can have a special mark in their manifest of a special file...
Implementing an extender pattern could be complex as the extender needs to track these marks dynamically. When a bundle starts, it needs to look at the mark. Then a bundle leave, the extender must release all object created from this bundle.
@@ -29,6 +29,7 @@ Nowadays, a lot of frameworks use this p
## Using the handler
First of all, you need to configure the component type to use the handler such as:
+ :::xml
<ipojo xmlns:extender="org.apache.felix.ipojo.extender">
<component
classname="org.apache.felix.ipojo.extender.MyExtender">
@@ -49,6 +50,7 @@ First of all, you need to configure the
Notice that, this handler is an external handler. So, it uses the "org.apache.felix.ipojo.extender" namespace.
You can also use annotations:
+ :::java
@Component
@Extender(
onArrival="onBundleArrival",
@@ -79,6 +81,7 @@ You can also use annotations:
The methods specified methods will be called when a matching bundle arrives or leaves.
In the previous example, these methods could be:
+ :::java
void onBundleArrival(Bundle bundle, String header) {
// Do something
}
@@ -91,54 +94,41 @@ Notice the different signatures of the m
## Configuration
The handler has only three mandatory attributes:
+
* Extension: declaring the looked manifest header.
* onArrival: declaring the method to invoke when a matching bundle arrives
* onDeparture: declaring the method to invoke when a matching bundle leaves
-
-
-<div class="box">
- <div class="box-yellow-header">
- <div class="box-yellow-title">
- <img src="http://people.apache.org/~clement/ipojo/site/warning.gif"> <b>Called despite being invalid</b>
- </div>
- </div>
- <div class="box-yellow-content">
+<div class="alert alert-warning">
+ <strong>Called despite being invalid</strong>
+ <p>
The implementation will be notified of arrivals and departures despite the instance is invalid. Indeed, the implementation must release all objects created from another bundle as soon it leaves.
- </div>
- <div class="box-yellow-footer"></div>
+ </p>
</div>
+## Configuring the handler with annotations
-## 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/extender/](http://svn.apache.org/repos/asf/felix/trunk/ipojo/handler/extender/)
+It is possible to configure the handler with a simple annotation available in the annotation pack ('annotations' project in the iPOJO trunk). Here is an example of usage:
-## Configuring the handler with annotations
+ :::java
+ import org.apache.felix.ipojo.annotations.Component;
+ import org.osgi.framework.Bundle;
-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.Bundle;
-
-@Component
-@org.apache.felix.ipojo.extender.Extender(extension="foo", onArrival="onArrival", onDeparture="onDeparture")
-public class Extender {
-
- public void onArrival(Bundle bundle, String foo) {
- // do something
- }
-
- public void onDeparture(Bundle bundle) {
- // do something
+ @Component
+ @org.apache.felix.ipojo.extender.Extender(extension="foo", onArrival="onArrival", onDeparture="onDeparture")
+ public class Extender {
+
+ public void onArrival(Bundle bundle, String foo) {
+ // do something
+ }
+
+ public void onDeparture(Bundle bundle) {
+ // do something
+ }
}
-}
+The `extension` attribute allows setting the bundle filter.
- The {{extension}} attribute allows setting the bundle filter.
-
-
- h2. A more realistic example
- The Junit4OSGi framework, available [here|https://svn.apache.org/repos/asf/felix/trunk/ipojo/examples/junit4osgi] , uses this handler to track Junit Test Suite offered by the installed bundles. The Junit4Osgi bundle has a component using this handler to be notified when a bundle with the {{Test-Suite}} header appears or leaves.
- \\
- \\
+## A more realistic example
+
+The Junit4OSGi framework, available [here](https://svn.apache.org/repos/asf/felix/trunk/ipojo/examples/junit4osgi), uses this handler to track Junit Test Suite offered by the installed bundles. The Junit4Osgi bundle has a component using this handler to be notified when a bundle with the `Test-Suite` header appears or leaves.
Modified: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/providing-osgi-services.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/providing-osgi-services.mdtext?rev=1444686&r1=1444685&r2=1444686&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/providing-osgi-services.mdtext (original)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/providing-osgi-services.mdtext Mon Feb 11 09:16:09 2013
@@ -6,6 +6,7 @@ Title: Providing OSGi services
# Providing OSGi services
*This pages explains how to publish OSGi services with iPOJO. It presents:*
+
* *service publication*
* *service properties publication and management*
* *service object creation and creation strategies*
@@ -13,14 +14,13 @@ Title: Providing OSGi services
* *configuration property propagation*
* *the management of the exposition from the implementation class*
-{div:class=toc}
[TOC]
-{div}
## A simple example
The following code snippet shows a simple class implementing the `FooService` interface:
+ :::java
@Component
@Provides
public class FooProviderType1 implements FooService {
@@ -36,11 +36,12 @@ To provide a service, the implementation
In XML, to provide the service, the component type needs to contain the `<provides/>` element:
+ :::xml
<component className="...FooProviderType1">
<provides/>
</component>
-!ps-foo.png!
+<img src="ps-foo.png">
The `<provides/>` or `@Provides` suffice to declare that each instance of this type will provide the FooService (for more info about instances see [FELIX:How-to use iPOJO factories]({{ refs.felix-how-to-use-ipojo-factories.path }})). The provided specifications can be discovered by analyzing the implementation class. By default, all implemented interface are published in the same service registration. iPOJO looks down the entire inheritance tree.
@@ -50,27 +51,21 @@ The provided service handler manages ser
By default, it publishes all interfaces implemented by the implementation class of the component class. It collects all super-interfaces (interfaces implemented by implemented interfaces and by the super class). However, it is possible to explicitly declare which service specifications are published with the `specifications` attribute, such as:
-
+ :::java
@Component
@Provides(specifications={FooService.class})
public class FooProviderType1 implements FooService, Runnable {
// ...
}
-
-<div class="info" markdown="1">
-**Change in the 1.2.0**
-In the 1.0.0 version and before, the `specifications` attribute was named `interface`.
-</div>
-
-<div class="info" markdown="1">
-**Specification checking**
-If you use the `specifications` attribute, the handler checks that all declared interfaces are really implemented by the implementation class. If an interface is not implemented, the handler logs a warning.
+<div class="alert alert-warning info">
+<h4>Specification checking</h4>
+<p>If you use the <code>specifications</code> attribute, the handler checks that all declared interfaces are really implemented by the implementation class. If an interface is not implemented, the handler logs a warning.</p>
</div>
-<div class="info" markdown="1">
-**No service**
-If the implementation class does not implement any interface, you cannot provide a service. In this case, the handler throws an error.
+<div class="alert alert-warning info">
+<h4>No service</h4>
+<p>If the implementation class does not implement any interface, you cannot provide a service. In this case, the handler throws an error.</p>
</div>
## Service Properties
@@ -79,6 +74,7 @@ You can also attach properties to a serv
Let's take a new example very closed of the last one:
+ :::java
@Component
@Provides
public class FooProviderType1 implements FooService {
@@ -94,6 +90,7 @@ Let's take a new example very closed of
Using XML, it gives:
+ :::xml
<component classname="...FooProviderType1">
<provides>
<property name="foo" field="m_foo" value="Foo"/>
@@ -101,13 +98,14 @@ Using XML, it gives:
</component>
-The declared property is attached to the `m*foo` field. This property is published with the name `foo`. This property has a default value "Foo". This value will be injected into the `m*foo` field, when this field asks for a value. A property with a field attribute does not need to declare a type (the type can be discovered by analyzing the implementation class).
+The declared property is attached to the `m_foo` field. This property is published with the name `foo`. This property has a default value "Foo". This value will be injected into the `m*foo` field, when this field asks for a value. A property with a field attribute does not need to declare a type (the type can be discovered by analyzing the implementation class).
The implementation class set a new value to the `m_foo` field in the code. When this action occurs, the service publication is updated. If a published property value becomes `null`, the property is unpublished since it has a new value.
You can also publish 'static' properties (not attached to a field):
+ :::java
@Component
@Provides(properties= {
@StaticServiceProperty(name="static", type="java.lang.String", value="this is a static property")
@@ -128,6 +126,7 @@ The second property (`Static`) is publis
In XML, this can also be done:
+ :::xml
<component classname="...FooProviderType1">
<provides>
<property name="foo" field="m_foo" value="Foo"/>
@@ -138,6 +137,7 @@ In XML, this can also be done:
Properties may have a default value (set using the `value` attribute). This value will be used as initial value. The value can be given in the instance configuration. The default value will be overridden in this case:
+ :::xml
<instance component="...FooProviderType1">
<property name="foo" value="My New Foo Value"/>
<property name="static" value="My Value For Static"/>
@@ -146,6 +146,7 @@ Properties may have a default value (set
Properties can also be 'mandatory'. Mandatories properties must receive a value from the instance configuration. If the instance configuration *forgets* a mandatory properties, the configuration is rejected. Mandatory attribute let you be sure to receive the complete set of initialization values:
+ :::java
@Component
@Provides
public class MyComponent implements MyService {
@@ -161,6 +162,7 @@ Properties can also be 'mandatory'. Mand
For the previous components:
+
* `(name=myname, password=****)` is a valid configuration
* `(password=****)` is an invalid configuration that will be rejected by iPOJO
@@ -173,7 +175,7 @@ When a consumer requires the published s
However, the handler supports the OSGi *Service Factory*. In this case, for each requester bundle, the handler sends a new object. To activate this policy, add the `strategy` attribute in the `provides` element:
-
+ :::java
@Component
@Provides(strategy="SERVICE")
public class MyComponent implements MyService {
@@ -182,6 +184,7 @@ However, the handler supports the OSGi *
or:
+ :::xml
<provides strategy="SERVICE"/>
@@ -189,6 +192,7 @@ Other strategies are available:
* `strategy="instance"` allows creating one service object per iPOJO instance using the service
* it is possible to create your own creation strategy by extending the `org.apache.felix.ipojo.handlers.providedservice.CreationStrategy` class and by indicating the qualified class name in the `strategy` attribute:
+ :::java
@Component
@Provides(strategy="org.acme.foo.MyCreationStrategy")
public class MyComponent implements MyService {
@@ -199,6 +203,7 @@ Other strategies are available:
### Providing Several Services (XML only)
In XML, you can declare several `provides` inside the same component. All those provided services will be managed individually, so will be published using several publication (i.e. `org.osgi.frameowrk.ServiceRegistration`). This case is useful when service properties are different for the different services.
+ :::xml
<component classname="...FooProviderType1">
<provides specifications="...Foo"/>
<provides specifications="...Bar">
@@ -206,16 +211,17 @@ In XML, you can declare several `provide
</provides>
</component>
-!ps-foobar2.png!
+<img src="ps-foobar2.png">
### Service Property Propagation
The configuration handler has the possibility to propagate received properties to service publication. So, when the propagation is activated (on the `properties` element or on the `@Component` annotation), all properties received by the configuration handler will be propagated to all published services. If some properties are mapped on methods, these methods are invoked with the new value in argument.
-!ps-propagation.png!
+<img src="ps-propagation.png">
If an instance configuration contains properties starting with `service.`, they are automatically propagated. In the following example, the `service.pid` is automatically propagated.
+ :::xml
<instance component="...">
<property name="service.pid" value="my.pid"/>
</instance>
@@ -225,34 +231,36 @@ If an instance configuration contains pr
iPOJO supports instance reconfiguration. When an instance is dynamically reconfigured and if the instance published service properties, the values are updated with the new configuration. For example, let's take the following component.
-{code:java}
-@Component
-@Instantiate
-@Provides
-public class MyComponent implements MyService {
+ :::java
+ @Component
+ @Instantiate
+ @Provides
+ public class MyComponent implements MyService {
- @ServiceProperty(name="prop", value="initial")
- private String myProp;
+ @ServiceProperty(name="prop", value="initial")
+ private String myProp;
- //...
-
-}
+ //...
+
+ }
- The previous code also declares an instance (created without any configuration). This instance registers {{MyService}} with the service property {{prop}}={{initial}}. If this instance is reconfigured using a configuration like: {{\{prop="my value"\}}}, the published properties will be updated with the new value, so {{prop}}={{my value}}.
+The previous code also declares an instance (created without any configuration). This instance registers `MyService` with the service property `prop=initial`. If this instance is reconfigured using a configuration like: `{prop="my value"}`, the published properties will be updated with the new value, so `prop=my value`.
- h3. Publishing an abstract or concrete class as a Service
+### Publishing an abstract or concrete class as a Service
- It is also possible to expose an abstract or concrete class as a service. To to this, just specify the published class in the {{specifications}} attribute:
+It is also possible to expose an abstract or concrete class as a service. To to this, just specify the published class in the `specifications` attribute:
-@Component
-@Provides(specifications=MyComponent.class)
-public class MyComponent {
- // ...
-}
+ :::java
+ @Component
+ @Provides(specifications=MyComponent.class)
+ public class MyComponent {
+ // ...
+ }
- or in XML:
- {code:xml}
+or in XML:
+
+ :::xml
<component classname="...FooProviderType1">
<provides specifications="...AbstractFoo"/>
</component>
@@ -266,40 +274,40 @@ As illustrated with the example using an
To control the exposition of the published service, you can use a `service controller`. A service controller is a boolean field of the component class. The injected boolean field allows the code to impact the service publication. Setting the field to `false` unregisters the service from the service registry. Setting it back to `true` re-publishes the service.
-{code:java}
-@Component
-@Provides
-public class ControllerCheckService implements FooService, CheckService {
-
- @ServiceController
- private boolean controller; // Service Controller
+ :::java
+ @Component
+ @Provides
+ public class ControllerCheckService implements FooService, CheckService {
+
+ @ServiceController
+ private boolean controller; // Service Controller
- public boolean foo() {
- return controller;
- }
+ public boolean foo() {
+ return controller;
+ }
- public boolean check() {
- System.out.println("Before : " + controller);
- controller = ! controller; // Change the publication
- System.out.println("After : " + controller);
- return controller;
+ public boolean check() {
+ System.out.println("Before : " + controller);
+ controller = ! controller; // Change the publication
+ System.out.println("After : " + controller);
+ return controller;
+ }
}
-}
+Using XML, the previous component description is:
-
- Using XML, the previous component description is:
- {code:xml}
- <component classname="org.apache.felix.ipojo.test.scenarios.component.controller.ControllerCheckService"
+ :::xml
+ <component classname="org.apache.felix.ipojo.test.scenarios.component.controller.ControllerCheckService"
name="PS-Controller-1-default">
<provides>
- <controller field="controller"/>
+ <controller field="controller"/>
</provides>
- </component>
+ </component>
The `controller` may have a value attribute setting the initial value. Setting this value to `false` disables the initial service registration:
+ :::java
@Component
@Provides
public class ControllerCheckService implements FooService, CheckService {
@@ -323,6 +331,7 @@ The `controller` may have a value attrib
If several interfaces are exposed, the controller may have a `specification` attribute indicating the impacted service:
+ :::java
@Component
@Provides
public class ControllerCheckService implements FooService, CheckService {
@@ -346,17 +355,19 @@ If several interfaces are exposed, the c
In XML, each `provides` can have one `controller` element.
- <component classname="org.apache.felix.ipojo.test.scenarios.component.controller.ControllerCheckService"
+ :::xml
+ <component classname="org.apache.felix.ipojo.test.scenarios.component.controller.ControllerCheckService"
name="PS-Controller-1-false">
<provides>
- <controller field="controller" value="false"/>
+ <controller field="controller" value="false"/>
</provides>
- </component>
+ </component>}
### Being notified of the service registration and unregistration
You can also be notified when the service is published and unpublished. This is done by specifying the two callbacks in the `<provides/>` element:
+ :::xml
<component
classname="org.apache.felix.ipojo.test.scenarios.component.callbacks.CallbacksCheckService"
name="PS-Callbacks-both-1">
@@ -368,23 +379,22 @@ You can also be notified when the servic
post-unregistration="unregistered" post-registration="registered"/>
</component>
-Or by using the @PostRegistration and @PostUnregistration annotations:
-{code:java}
+Or by using the `@PostRegistration` and `@PostUnregistration` annotations:
+
+ :::java
@PostRegistration
public void registered(ServiceReference ref) {
System.out.println("Registered");
}
- @PostUnregistration
+ @PostUnregistration
public void unregistered(ServiceReference ref) {
System.out.println("Unregistered");
}
- * The {{post-registration}} callback is called after the service publication
- * The {{post-unregistration}} callback is called after the service unpublication
-
- Those callback methods must have the following signature: {{public void name(ServiceReference ref)}}. So they receive the published / unpublished service reference. The callbacks are called in the *same thread* as the publication / unpublication itself.
+* The `post-registration` callback is called after the service publication
+* The `post-unregistration` callback is called after the service unpublication
- \\
- \\
+Those callback methods must have the following signature: `public void name(ServiceReference ref)`. So they receive the published / unpublished service reference. The callbacks are called in the *same thread* as the publication / unpublication itself.
+
\ No newline at end of file
Modified: felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/service-requirement-handler.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/service-requirement-handler.mdtext?rev=1444686&r1=1444685&r2=1444686&view=diff
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/service-requirement-handler.mdtext (original)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/service-requirement-handler.mdtext Mon Feb 11 09:16:09 2013
@@ -8,15 +8,14 @@ Title: Service Requirement Handler
*One of the main iPOJO feature is the service injection. So, a component can consume a service without managing the service discovery, tracking and binding. iPOJO manages all these interactions and injects required service into the component. This page explains how to use services.*
-{div:class=toc}
[TOC]
-{div}
## Service Requirement
### What's a service requirement?
A requirement represents a required service. Therefore, it manages the service lookup and the service binding. When an instance requires a service, the handler injects directly a service object inside a field, or invokes a method when a consistent service appears (or disappears). Service requirements can be:
+
* Simple / Aggregate : the component can require one or several service providers
* Mandatory / Optional : a component can declare an optional dependency
* Filtered : a component can filter available providers
@@ -29,19 +28,23 @@ A requirement represents a required serv
In OSGiâ¢, services can appear and disappear dynamically. This implies dependencies can target a provider which can appear or disappear dynamically. So, dependencies need to manage this dynamism by tracking every time available services. At any moment, a dependency can be unresolved (i.e. no more provider can fulfill the requirement). In the case of a mandatory requirement, the instance becomes invalid (an invalid instance is no more accessible externally, for example provided services are unpublished). If a service, resolving the unfilled dependency appears, the instance becomes valid. In consequence, dependencies affect directly the instance state, and must manage correctly OSGi dynamism to allow a complete unloading when a service goes away. As soon a mandatory dependency cannot be fulfilled, the instance is invalidated.
By default, dependencies are managed dynamically (as previously explained). However, iPOJO supports two other types of binding policies:
+
* Static : if a bound service disappears, the instance is invalidated and cannot be revalidated (binding broken forever)
* Dynamic-Priority: at each injection, the *best* provider is injected, or the providers array is sorted according to the OSGi Ranking policy or to a specified sorting algorithm.
## Service Requirement Injection Mechanisms
iPOJO support several types of injections:
-* Field injection: a field contains the service object. As soon as the field is used, a consistent service object is injected. This injection type fully hides the dynamism
+**Field injection**: a field contains the service object. As soon as the field is used, a consistent service object is injected. This injection type fully hides the dynamism
+
+ :::java
@Requires
private LogService log;
-* Method invocation: when a service appears, or disappears a method in the component is invoked. For each dependency, bind / unbind / modified methods are invoked to notify the component of the event.
+**Method invocation**: when a service appears, or disappears a method in the component is invoked. For each dependency, bind / unbind / modified methods are invoked to notify the component of the event.
+ :::java
@Bind
public void bindLogService(LogService log) { /*...*/ }
@Unbind
@@ -49,30 +52,32 @@ iPOJO support several types of injection
@Modified
public void modifiedLogService(LogService log) { /*...*/ }
-* Constructor injection: services can also be injected as constructor parameter (only if proxies are enabled). *1.7.0-SNAPSHOT*
+**Constructor injection**: services can also be injected as constructor parameter (only if proxies are enabled). *1.7.0-SNAPSHOT*
+ :::java
public MyComponent(@Requires LogService log) { /*...*/ }
-
Moreover, the injections types can be mixed. A component can declare a requirement containing both a field and 'binding' methods.
### Field injection
Let's imagine a Hello service with one method 'getMessage' returning a "Hello Message". The following component implementation can use this service by attaching this service to a field and by using the field:
-{code:java}
-@Component
-@Instantiate
-public class HelloConsumer {
- @Requires
- private Hello m_hello;
- public doSomething() {
- System.out.println(m_hello.getMesage());
+ :::java
+ @Component
+ @Instantiate
+ public class HelloConsumer {
+ @Requires
+ private Hello m_hello;
+
+ public doSomething() {
+ System.out.println(m_hello.getMesage());
+ }
}
-}
- You can also use XML to describe this component type:
- {code:xml}
+You can also use XML to describe this component type:
+
+ :::xml
<component classname="...HelloConsumer">
<requires field="m_hello"/>
...
@@ -83,11 +88,13 @@ The metadata contains a 'requires' eleme
### Method invocation
The second injection mechanism uses methods in the implementation class. By this way, the dynamics can be managed directly by the developer. Each dependency can declare three methods:
+
* A bind method called when a service appears
* An unbind method called when a service disappears
* A modified method called when a service is modified (the service properties changed, but the service still matches the requirement)
Moreover, callbacks can be in the component super class (in this case methods must be public). These methods can have one of these four signatures:
+
* Without any argument: the method is just a notification (method())
* With the service object : the object is the implicated service object (method(Service svc))
* With an OSGi service reference: the service reference appearing or disappearing (method(ServiceReference ref))
@@ -96,20 +103,22 @@ Moreover, callbacks can be in the compon
* With the service object and the service properties inside a Dictionary (method(Service svc, Dictionary properties))
The following component implementation shows an example of implementation using this mechanism:
-{code:java}
-@Component
-public class HelloConsumer {
- private Hello m_hello;
-
- @Bind
- public void bindHello(Hello h) { m_hello = h; }
- @Unbind
- public void unbindHello() { m_hello = null; }
- public doSomething() { System.out.println(m_hello.getMesage()); }
-}
+
+ :::java
+ @Component
+ public class HelloConsumer {
+ private Hello m_hello;
- The {{modified}} callback is not mandatory. The following XML metadata are describing the same component type:
- {code:xml}
+ @Bind
+ public void bindHello(Hello h) { m_hello = h; }
+ @Unbind
+ public void unbindHello() { m_hello = null; }
+ public doSomething() { System.out.println(m_hello.getMesage()); }
+ }
+
+The `modified` callback is not mandatory. The following XML metadata are describing the same component type:
+
+ :::xml
<component classname="...HelloConsumer">
<requires>
<callback type="bind" method="bindHello">
@@ -121,40 +130,43 @@ public class HelloConsumer {
Note, that the different callbacks can be have different signatures. By using this mechanism, you need to be sure to manage the dynamism correctly.
([See note on type discovery]({{ refs.-discovery.path }}))
-Using the @Modified callback is also quite simple:
-{code:java}
-@Component
-public class HelloConsumer {
- private Hello m_hello;
-
- @Bind
- public void bindHello(Hello h) { m_hello = h; }
- @Unbind
- public void unbindHello() { m_hello = null; }
- @Modified
- public void modifiedHello() { /* ... */ }
- public doSomething() { System.out.println(m_hello.getMesage()); }
+Using the `@Modified` callback is also quite simple:
+
+ :::java
+ @Component
+ public class HelloConsumer {
+ private Hello m_hello;
-}
+ @Bind
+ public void bindHello(Hello h) { m_hello = h; }
+ @Unbind
+ public void unbindHello() { m_hello = null; }
+ @Modified
+ public void modifiedHello() { /* ... */ }
+ public doSomething() { System.out.println(m_hello.getMesage()); }
+ }
- h3. Using constructor injection (*1.7.0-SNAPSHOT*)
- Services can also be injected using constructor parameters:
+### Using constructor injection (*1.7.0-SNAPSHOT*)
-@Component
-public class MyComponent {
- private LogService log;
+Services can also be injected using constructor parameters:
- public MyComponent(@Requires LogService log) {
- this.log = log;
+ :::java
+ @Component
+ public class MyComponent {
+ private LogService log;
+
+ public MyComponent(@Requires LogService log) {
+ this.log = log;
+ }
}
-}
- h3. Mixing injections types
+### Mixing injections types
- The different mechanisms can be used together. In this case, the field receives the value before the bind method invocation. Constructor parameters get their values during the constructor invocation. So, if the field is used in the method, the returned value will be up to date. The following component implementation uses this mechanism:
- {code:java}
+The different mechanisms can be used together. In this case, the field receives the value before the bind method invocation. Constructor parameters get their values during the constructor invocation. So, if the field is used in the method, the returned value will be up to date. The following component implementation uses this mechanism:
+
+ :::java
public class HelloConsumer {
@Requires(id="hello")
private Hello m_hello; // Injected Field
@@ -170,6 +182,7 @@ public class MyComponent {
In XML, it results in:
+ :::xml
<component classname="...HelloConsumer">
<requires field="m_hello">
<callback type="bind" method="bindHello">
@@ -180,6 +193,7 @@ In XML, it results in:
The `id` attribute is used to determine which callbacks / fields go together. If ommitted, it is computed automaticcally:
+
* for field it uses the field type.
* for method starting with `bind` / `unbind` / `modified`, it extract the end of the method name (`bindFoo => Foo`)
* for constructor parameter, it uses the parameter index
@@ -204,21 +218,21 @@ When a component requires several provid
#### Aggregate Dependency with field injection
-{code:java}
-@Component
-public class HelloConsumer {
- @Requires
- private Hello m_hellos[]({{ refs..path }}); // Array => Aggregate
- public doSomething() {
- for(int I = 0; I < m_hellos.length; i++) {
- System.out.println(m_hellos[i]({{ refs.i.path }}).getMessage());
- }
- }
-}
+ :::java
+ @Component
+ public class HelloConsumer {
+ @Requires
+ private Hello m_hellos[]({{ refs..path }}); // Array => Aggregate
+ public doSomething() {
+ for(int I = 0; I < m_hellos.length; i++) {
+ System.out.println(m_hellos[i]({{ refs.i.path }}).getMessage());
+ }
+ }
+ }
-
- For this component, XML metadata could be:
- {code:xml}
+For this component, XML metadata could be:
+
+ :::xml
<component classname="...HelloConsumer">
<requires field="m_hellos"/>
...
@@ -229,32 +243,35 @@ To declare an aggregate field for field
Array types cannot be 'proxied'. Moreover array dependencies cannot be injected as constructor parameter.
-<div class="info" markdown="1">
-**Synchronization**
-The synchronization is managed by iPOJO. As soon as you are 'touching' a dependency in a method, iPOJO ensure that you will keep these objects until the end of the method. Nested methods will share the same service object set.
+<div class="alert alert-info info" markdown="1">
+<h4>Synchronization</h4>
+<p>The synchronization is managed by iPOJO. As soon as you are 'touching' a dependency in a method, iPOJO ensure that you will keep these objects until the end of the method. Nested methods will share the same service object set.</p>
</div>
#### Aggregate Dependency with field injection: list, vector, collection and set
It is also possible to inject service objects inside fields of the type:
+
* list
* vector
* collection
* set
+
-{code:java}
-@Component
-public class HelloConsumer {
- @Requires(specification="org.apache.felix.ipojo.example.Hello")
- private List<Hello> m_hellos;
- public doSomething() {
- for(Hello h : m_hellos) {
- System.out.println(h).getMessage());
- }
- }
-}
+ :::java
+ @Component
+ public class HelloConsumer {
+ @Requires(specification="org.apache.felix.ipojo.example.Hello")
+ private List<Hello> m_hellos;
+ public doSomething() {
+ for(Hello h : m_hellos) {
+ System.out.println(h).getMessage());
+ }
+ }
+ }
+
+For this component, XML metadata could be:
- For this component, XML metadata could be:
- {code:xml}
+ :::xml
<component classname="...HelloConsumer">
<requires field="m_hellos" specification="org.apache.felix.ipojo.example.Hello"/>
...
@@ -263,20 +280,20 @@ public class HelloConsumer {
In this case, just use the supported type that you want. iPOJO will automatically understand that it is an aggregate dependency, and will create the collection object containing service objects. However, you must specify the service specification. Indeed, generics types cannot be discovered at runtime reliably.
-<div class="info" markdown="1">
-**Service specification discovery**
-The service specification (i.e. interface) cannot be discovered when using these types as the bytecode does not provide enough information. So, you have to indicate the required service interface (with the 'specification' attribute) in the requirement description.
+<div class="alert alert-info info" markdown="1">
+<h4>Service specification discovery</h4>
+<p>The service specification (i.e. interface) cannot be discovered when using these types as the bytecode does not provide enough information. So, you have to indicate the required service interface (with the 'specification' attribute) in the requirement description.</p>
</div>
-<div class="info" markdown="1">
-**How iPOJO manage the synchronization for you**
-As in the previous case, the synchronization is managed by iPOJO. As soon as you are *touching* a dependency in a method, iPOJO ensure that you will keep these objects until the end of the method. Nested methods will share the same service object set.
+<div class="alert alert-info info" markdown="1">
+<h4>How iPOJO manage the synchronization for you</h4>
+<p>As in the previous case, the synchronization is managed by iPOJO. As soon as you are *touching* a dependency in a method, iPOJO ensure that you will keep these objects until the end of the method. Nested methods will share the same service object set.</p>
</div>
#### Aggregate Dependency with callbacks
-{code:java}
-public class HelloConsumer {
+ :::java
+ public class HelloConsumer {
private List m_hellos = new ArrayList();
@Bind(aggregate=true)
private void bindHello(Hello h) { m_hellos.add(h); }
@@ -288,10 +305,11 @@ public class HelloConsumer {
}
}
}
-}
+ }
+
+This dependency can also be described in XML as follow:
- This dependency can also be described in XML as follow:
- {code:xml}
+ :::xml
<requires aggregate="true">
<callback type="bind" method="bindHello">
<callback type="unbind" method="unbindHello">
@@ -299,9 +317,9 @@ public class HelloConsumer {
In this case, iPOJO cannot detect if the dependency is aggregate or not. So, you need to add the '*aggregate*' attribute. The bindHello and unbindHello will be called each time a Hello service appears or disappears.
-<div class="info" markdown="1">
-**Synchronization**
-To avoid the list modification during the loop, you need synchronized the block. Indeed, as the field is not an iPOJO requirement, iPOJO will not manage the synchronization.
+<div class="alert alert-info info" markdown="1">
+<h4>Synchronization</h4>
+<p>To avoid the list modification during the loop, you need synchronized the block. Indeed, as the field is not an iPOJO requirement, iPOJO will not manage the synchronization.</p>
</div>
### Optional Requirement (Scalar)
@@ -310,19 +328,20 @@ An optional requirement does not invalid
#### Optional Requirement with field injection
-{code:java}
-@Component
-public class HelloConsumer {
- @Requires(optional=true)
- private Hello m_hello;
+ :::java
+ @Component
+ public class HelloConsumer {
+ @Requires(optional=true)
+ private Hello m_hello;
- public doSomething() {
- System.out.println(m_hello.getMesage());
- }
-}
+ public doSomething() {
+ System.out.println(m_hello.getMesage());
+ }
+ }
- For this component, equivalent XML metadata could be:
- {code:xml}
+For this component, equivalent XML metadata could be:
+
+ :::xml
<component classname="...HelloConsumer">
<requires field="m_hello" optional="true"/>
...
@@ -332,32 +351,33 @@ To declare an optional requirement, you
#### Optional Dependency with callbacks invocation
-{code:java}
-@Component
-public class HelloConsumer {
- private Hello m_hello;
-
- @Bind(optional=true)
- public void bindHello(Hello h) { m_hello = h; }
-
- @Unbind
- public void unbindHello() { m_hello = null; }
-
- public doSomething() {
- if(m_hello != null) { // Must be checked
- System.out.println(m_hello.getMesage());
- }
+ :::java
+ @Component
+ public class HelloConsumer {
+ private Hello m_hello;
+
+ @Bind(optional=true)
+ public void bindHello(Hello h) { m_hello = h; }
+
+ @Unbind
+ public void unbindHello() { m_hello = null; }
+
+ public doSomething() {
+ if(m_hello != null) { // Must be checked
+ System.out.println(m_hello.getMesage());
+ }
+ }
}
-}
- For this component, XML metadata could be:
- {code:xml}
+For this component, XML metadata could be:
+
+ :::xml
<component classname="...HelloConsumer">
- <requires optional="true">
- <callback type="bind" method="bindHello">
- <callback type="unbind" method="unbindHello">
- </requires>
- ...
+ <requires optional="true">
+ <callback type="bind" method="bindHello">
+ <callback type="unbind" method="unbindHello">
+ </requires>
+ ...
</component>
As for field requirement, the dependency metadata needs to contain the optional attribute. iPOJO invokes the method only when a 'real' service is available, so you need to test if `m_hello` is `null` before to use it.
@@ -368,74 +388,78 @@ A dependency can be both aggregate and o
#### Aggregate & Optional Dependency with field injection
-{code:java}
-@Component
-public class HelloConsumer {
- @Requires(optional=true)
- private Hello m_hellos[]({{ refs..path }});
-
- public doSomething() {
- for(Hello h : m_hellos) {
- System.out.println(h.getMessage());
- }
- }
-}
+ :::java
+ @Component
+ public class HelloConsumer {
+ @Requires(optional=true)
+ private Hello m_hellos[]({{ refs..path }});
+
+ public doSomething() {
+ for(Hello h : m_hellos) {
+ System.out.println(h.getMessage());
+ }
+ }
+ }
+
+For this component, XML metadata could be:
- For this component, XML metadata could be:
- {code:xml}
+ :::xml
<component classname="...HelloConsumer">
- <requires field="m_hellos" optional="true"/>
- ...
+ <requires field="m_hellos" optional="true"/>
+ ...
</component>
To declare an optional & aggregate field requirement you need to write the optional attribute in the dependency metadata and to point on a field array. If no service available, iPOJO injects an empty array.
#### Aggregate & Optional Requirement with callbacks
-{code:java}
-@Compoent
-public class HelloConsumer {
+ :::java
+ @Component
+ public class HelloConsumer {
- private List m_hellos<Hello> = new ArrayList<Hello>();
+ private List m_hellos<Hello> = new ArrayList<Hello>();
- @Bind(aggregate=true, optional=true)
- private void bindHello(Hello h) { m_hellos.add(h); }
+ @Bind(aggregate=true, optional=true)
+ private void bindHello(Hello h) { m_hellos.add(h); }
- @Unbind
- private void unbindHello(Hello h) { m_hellos.remove(h); }
+ @Unbind
+ private void unbindHello(Hello h) { m_hellos.remove(h); }
- public synchronized doSomething() {
- for(Hello h : m_hellos) {
- System.out.println(h.getMessage());
- }
- }
-}
+ public synchronized doSomething() {
+ for(Hello h : m_hellos) {
+ System.out.println(h.getMessage());
+ }
+ }
+ }
- For this component, XML metadata could be:
- {code:xml}
+For this component, XML metadata could be:
+
+ :::xml
<requires aggregate="true" optional="true">
<callback type="bind" method="bindHello">
<callback type="unbind" method="unbindHello">
</requires>
-In this case, you need to add the *'aggregate'*attribute and the *'optional'*attribute. The `bindHello` and `unbindHello` will be called each time a Hello service appears or disappears. These bind / unbind methods are not called when binding / unbinding a Nullable object (when both field and method are used).
+In this case, you need to add the *'aggregate'* attribute and the *'optional'*attribute. The `bindHello` and `unbindHello` will be called each time a Hello service appears or disappears. These bind / unbind methods are not called when binding / unbinding a Nullable object (when both field and method are used).
### Filtered Requirement
A filtered dependency applies an LDAP filter on service provider. iPOJO reuses OSGi LDAP filter ability. The following metadata illustrates how to use filters:
+ :::java
@Requires(filter="(language=fr)")
private String DictionaryService dict;
+
-
+ :::xml
<requires filter="(language=fr)" field="dict"/>
-
To add a filter, just add a 'filter' attribute in your dependency containing the LDAP filter. iPOJO will select only provider matching with this filter.
When using a filter, you can also use the `modified` callback invoked when a matching service is *modified* but still matches the filter:
+ :::java
@Component
public class MyComponent {
@@ -447,12 +471,11 @@ When using a filter, you can also use th
@Modified
public void modifiedDictionary() { ... }
-
}
-
Moreover, filters can be customized instance by instance. It is possible to specialize / change / add the filter of a component in the instance description. It is useful when you want to create different instances of the same component, with different filter. To achieve this customization, you have to identify your dependency with the 'id' attribute. Then, you can adapt the filter of the dependency in the instance description by using the property "requires.filters". In this property you can specify each dependency identified by its id and the new value of the filter.
+ :::xml
<component
className="org.apache.felix.ipojo.example.FilteredDependency">
<requires field="m_foo" fiter="(foo.property=FOO)" id="id1">
@@ -480,18 +503,20 @@ The component type declares a service de
### Targeting a specific provider
A service dependency can choose a specific provider. To achieve this, add a 'from' attribute in your requirement description such as in:
+ :::java
@Requires(from="MyHelloProvider")
private Hello m_hello;
or in XML:
+ :::xml
<requires from="MyHelloProvider" field="m_hello"/>
iPOJO maps the `from` attribute to a specific filter : '|(instance.name=MyHelloProvider)(service.pid=MyHelloProvider)'. Then the dependency can only be fulfilled by a service matching this filter.
Moreover, from attributes can be customized instance by instance. It is possible to specialize / change / add a 'from' attribute of a component in the instance configuration. It is useful when you want to create different instances of the same component, with different 'from' clauses. To do it, you have to identify your dependency with an 'id' attribute. Then, you can adapt the 'from' of the dependency in the instance configuration by using the property "requires.from". In this property you can specify each dependency identified by its id and the 'from' value.
-
+ :::xml
<component
className="org.apache.felix.ipojo.example.FilteredDependency"
name="FOO">
@@ -522,38 +547,45 @@ The FOO component type declares a servic
## Binding Policies
Three binding policies are supported inside iPOJO.
-* Dynamic policy (default): the binding are managed dynamically. At each injection, the same provider is injected if the provider is always available. Else a new one is chosen. For aggregate dependency, the array order does not change; new providers are placed at the end of the array.
-* Static policy: the binding is static. So, once bound a provider cannot disappear. If it disappears, the instance is invalidated and cannot be revalidated without stopping and restarting the instance.
-* Dynamic-priority policy: the binding is managed dynamically but the injected provider is selected by using a ranking policy. Two injections can return two different providers, is a new provider is 'better' than the previous one, despite the first one is always available. For aggregate dependency, the array is sorted.
+
+* Dynamic policy (default): the binding are managed dynamically. At each injection, the same provider is injected if the provider is always available. Else a new one is chosen. For aggregate dependency, the array order does not change; new providers are placed at the end of the array.
+* Static policy: the binding is static. So, once bound a provider cannot disappear. If it disappears, the instance is invalidated and cannot be revalidated without stopping and restarting the instance.
+* Dynamic-priority policy: the binding is managed dynamically but the injected provider is selected by using a ranking policy. Two injections can return two different providers, is a new provider is 'better' than the previous one, despite the first one is always available. For aggregate dependency, the array is sorted.
A static binding is declared as following:
+ :::java
@Requires(policy="static")
private Hello[] m_hellos;
or
+ :::xml
<requires field="m_hellos" policy="static"/>
A dynamic-priority binding is declared as following:
+ :::java
@Requires(policy="dynamic-priority")
private Hello[] m_hellos;
or
-
+
+ :::xml
<requires field="m_hellos" policy="dynamic-priority"/>
By default, the dynamic-priority policy uses the OSGi service ranking policy. However, it is possible to customize the policy by adding the '*comparator*' attribute. This attribute indicates the class name of a class implementing the `java.util.Comparator` interface. iPOJO creates an instance of your comparator and uses it to sort service references (so your customized comparator needs to be able to sort OSGi Service Reference).
+ :::java
@Requires(policy="dynamic-priority", comparator=MyComparator.class)
private Hello[] m_hellos;
or
+ :::xml
<requires field="m_hellos" policy="dynamic-priority" comparator="great.MyComparator"/>
@@ -563,6 +595,7 @@ or
The instance implementation can use an optional dependency without any checking. Indeed, when an instance declares an optional dependency using field injection, iPOJO create on the fly a Nullable class implementing the service specification but doing nothing (mock object). Therefore, iPOJO cannot return a service to the instance, for an optional dependency, it returns a nullable object.
A nullable object returns:
+
* Null when the method returns an object
* 0 when the method returns an int, log, byte, short, char, float or a double
* False when the method return a boolean
@@ -571,11 +604,13 @@ You can check if the returned object is
You can disable the Nullable pattern too (activated by default). In this case, iPOJO injects `null` instead of a *Nullable* object. So, you can just test if your field is equals to *null* to check if the service is available. To disable the Nullable pattern, you need to add the 'nullable="false"' attribute in your service dependency description as follows:
+ :::java
@Requires(optional=true, nullable=false)
private LogService m_log;
or
-
+
+ :::xml
<requires field="m_log" optional="true" nullable="false"/>
@@ -583,22 +618,24 @@ However, you can also indicate a *defaul
For example, the following component uses a default implementation for a Log Service dependency:
+ :::java
@Requires(optional=true, default-implementation=MyLogService.class)
private LogService m_log;
or
-
+
+ :::xml
<requires field="m_log" optional="true"
default-implementation=
"org.apache.felix.ipojo.example.default.MyLogService"/>
If the log service is not available, iPOJO creates an object of the 'org.apache.felix.ipojo.example.default.MyLogService' class. This object is injected instead of a Nullable object. For instance, the default implementation can print messages on the System.err stream. The nullable object does no display anything.
-
## Note about Callbacks
Dependency manages two type of callback: bind and unbind. A callback with a type "bind" is called each type that a service provider arrives and the binding is necessary. According to the cardinality of the dependency it means:
-* Simple dependency : at the firs binding and at each rebinding to another service provider
-* Aggregate dependencies: each time that a service provider arrives
+
+* Simple dependency : at the firs binding and at each rebinding to another service provider
+* Aggregate dependencies: each time that a service provider arrives
An unbind callback is called each time that a *used* service provider goes away. For a simple dependency this method is called each time that the used service provider goes away. For a multiple dependency this method is called each time that a service provider goes away.
@@ -606,6 +643,7 @@ The method can receive in argument the s
## Proxies
Since iPOJO 1.6, iPOJO injects proxy objects. Those proxies are by default smart proxies and are design to be lightweight:
+
* for scalar requirement : the service object is a proxy
* for aggregate dependencies : iPOJO injects a smart collections
@@ -613,8 +651,6 @@ The goal of the proxies is to hide the d
By default iPOJO injects proxy except for arrays. Moreover, it is possible to disable the proxy injection by adding `proxy=false` to the `requires` element (or to the `@Requires` and `@Bind` annotations). It is also possible to inject dynamic proxies (if the platform does not support dynamically generated classes). To enable dynamic proxies, set the system or bundle property `ipojo.proxy.type` to `dynamic-proxy`. You can also disable completely the proxy injection by setting the system property `ipojo.proxy` to `disabled`.
-
-
## Note on service interface discovery
The `specification` attribute is generally optional except when iPOJO cannot discover the type of the service. iPOJO cannot infer the type when the dependency has no field and callbacks do not receive the service object in parameter. In this case, you must the service specification (i.e. interface).