Versions Compared

Old Version 25

changes.mady.by.user Clement Escoffier

Saved on

compared with

New Version 26

changes.mady.by.user Clement Escoffier

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 4.0

...

Include Page
apache-felix-ipojo-header
apache-felix-ipojo-header

...

Wiki Markup
{html}
<div class="content">
{html}

...

Configuration 
...
 Handler
...
This 
...
 page 
...
 presents 
...
 how 
...
 to 
...
 configure 
...
 component 
...
 instances. 
...
 This 
...
 is 
...
 managed 
...
 by 
...
 the 
...
 configuration 
...
 handler. 
...
 This 
...
 handler 
...
 allows 
...
 the 
...
 configuration 
...
 and 
...
 dynamic 
...
 reconfiguration 
...
 of 
...
 instances. 
...
 A 
...
 configuration 
...
 is 
...
 basically 
...
 a 
...
 set 
...
 of 
...
 couple 
...
 (name, 
...
 value). 
...
 The 
...
 name 
...
 can 
...
 be 
...
 a 
...
 field 
...
 name 
...
 or 
...
 a 
...
 property 
...
 name 
...
 associated 
...
 to 
...
 a 
...
 field 
...
 or/and 
...
 a 
...
 method. 
...
 iPOJO 
...
 also 
...
 supports 
...
 complex 
...
 properties 
...
 composed 
...
 by 
...
 maps, 
...
 dictionaries, 
...
 lists 
...
 and 
...
 arrays.
 Wiki Markup
_

{div:class=toc}
{toc:maxLevel=4|minLevel=2}
{div}

h2. 
Configurable 
...
 Properties
...
To 
...
 support 
...
 configuration, 
...
 the 
...
 component 
...
 type 
...
 needs 
...
 to 
...
 declare 
...
 which 
...
 properties 
...
 are 
...
 configurable. 
...
 These 
...
 properties 
...
 are 
...
 not 
...
 necessarily 
...
 service 
...
 properties 
...
 but 
...
 can 
...
 be 
...
 internal 
...
 component 
...
 properties.
...
Examples
The following code depicts a simple configurable component. The 'm_foo' 
...
 field 
...
 will 
...
 be 
...
 injected 
...
 using 
...
 the 
...
 'foo' 
...
 property, 
...
 and 
...
 will 
...
 also 
...
 be 
...
 exposed 
...
 as 
...
 a 
...
 service 
...
 property. 
...
 The 
...
updateArray
...
 method 
...
 is 
...
 a 
...
 'setter' 
...
 method 
...
 where 
...
 the 
...
 'array' 
...
 property 
...
 will 
...
 be 
...
 injected. 
...
 Properties 
...
 injected 
...
 into 
...
 field 
...
 are 
...
 available 
...
 in 
...
 the 
...
 constructor, 
...
 setter 
...
 method 
...
 are 
...
 available 
...
 only 
...
 after 
...
 the 
...
 constructor.

{
 Code Block
}
@Component
@Provides
public class MyComponent implements MyService {
    @Property(name="foo")
    @ServiceProperty
    private String m_foo;

    @Property(name="array")
    public void updateArray(String[] array) {
     //...
    }
}
{code}


The 
...
 previous 
...
 component 
...
 can 
...
 also 
...
 be 
...
 described 
...
 using 
...
 XML:
 Code Block
xml
xml

{code:xml}
<component classname="...MyComponent">
   <provides>
       <property name="foo" field="m_foo"/>
   </provides>
   <properties propagation="false"/>
       <Property name="foo" field="m_foo"/>
       <Property name="array" method="updateArray"/>
   </properties>
</component>
{code}


The instance contains the configuration:
{code:xml}
The instance contains the configuration:
 Code Block
xml
xml
<instance component="...MyComponent">
   <property name="foo" value="bar"/>
   <property name="array" value="{1, 2, 3}"/>
</instance>
{code}

In 
...
 the 
...
 previous 
...
 snippet, 
...
 you 
...
 can 
...
 see 
...
 three 
...
 configurable 
...
 properties. 
...
 The 
...
 first 
...
 is 
...
 a 
...
 configurable 
...
 property 
...
 attached 
...
 to 
...
 the 
...
 field 
...
 'foo' 
...
 that 
...
 is 
...
 a 
...
 service 
...
 property 
...
 too. 
...
 The 
...
 second 
...
 is 
...
 an 
...
 array 
...
 property 
...
 attached 
...
 to 
...
 a 
...
 method 
...
 (updatArray). 
...
 These 
...
 three 
...
 properties 
...
 are 
...
 configured 
...
 by 
...
 the 
...
 instance 
...
 configuration.
...
By 
...
 setting 
...
 the 
...
 attribute 
...
propagation
...
 to 
...
"true"
...
, 
...
 you 
...
 allow 
...
 the 
...
 property 
...
 propagation 
...
 to 
...
 the 
...
 service 
...
 registration. 
...
 It 
...
 means 
...
 that 
...
 at 
...
 each 
...
 time 
...
 that 
...
 the 
...
 configuration 
...
 of 
...
 the 
...
 instance 
...
 is 
...
 updated; 
...
 all 
...
 properties 
...
 contained 
...
 in 
...
 the 
...
 configuration 
...
 are 
...
 propagated 
...
 to 
...
 the 
...
 service 
...
 registrations. 
...
 For 
...
 example, 
...
 in 
...
 the 
...
 previous 
...
 example, 
...
 not 
...
 only 
...
foo
...
 will 
...
 be 
...
 published 
...
 but 
...
array
...
 are 
...
 also 
...
 published. 
...
 To 
...
 enable 
...
 propagation 
...
 use:

{
 Code Block
}
@Component(propagation=true)
{code}


If 
...
 a 
...
 property 
...
 has 
...
 a 
...
 method, 
...
 this 
...
 method 
...
 is 
...
 invoked 
...
 each 
...
 time 
...
 that 
...
 the 
...
 property 
...
 value 
...
 changes 
...
 (the 
...
 method 
...
 is 
...
 called 
...
 to 
...
 push 
...
 the 
...
 initial 
...
 value 
...
 just 
...
 after 
...
 the 
...
 constructor). 
...
 The 
...
 method 
...
 receives 
...
 one 
...
 argument 
...
 of 
...
 the 
...
 type 
...
 of 
...
 the 
...
 property 
...
 (an 
...
 integer 
...
 array 
...
 in 
...
 the 
...
 example).
...
When 
...
 an 
...
 instance 
...
 is 
...
 reconfigured, 
...
 an 
...
 updated 
...
 callback 
...
 can 
...
 also 
...
 be 
...
 called:

{
 Code Block
}
@Updated
public void updated() {
  // The instance was reconfigured
}

// OR
@Updated
public void updated(Dictionary conf) {
  // The instance was reconfigured, conf is the new configuration.
}
{code}
h2. Exposing a Managed Service
The ManagedService is a service specified in the OSGi Compendium. It allows reconfiguring an instance with the Configuration Admin. There is two way for an iPOJO instance to expose a Managed Service.
* In the {{@Component}} annotation the {{managedservice}} attribute defines the managed service PID. In XML this is done using the {{pid}} attribute in the properties element (XML)
* In the instance configuration by configuring the {{managed.service.pid}} property

So, using annotation, you 
Exposing a Managed Service
The ManagedService is a service specified in the OSGi Compendium. It allows reconfiguring an instance with the Configuration Admin. There is two way for an iPOJO instance to expose a Managed Service.
  • In the @Component annotation the managedservice attribute defines the managed service PID. In XML this is done using the pid attribute in the properties element (XML)
  • In the instance configuration by configuring the managed.service.pid property
So, using annotation, you should use the managedservice attribute as follow:
 Code Block
should use the {{managedservice}} attribute as follow:
{code}
@Component(managedservice="my.pid")
public class MyComponent {

}
{code}


In 
...
 XML, 
...
 the 
...
pid
...
 attribute 
...
 of 
...
 the 
...
properties
...
 element 
...
 does 
...
 the 
...
 same 
...
 job.
 Code Block
xml
xml

{code:xml}
<component classname="...MyComponent">
   <!-- ... -->
   <properties pid="my.pid"/>
       <!-- ... -->
   </properties>
</component>
{code}


Finally, 
...
 instance 
...
 may 
...
 configure 
...
 the 
...
 managed 
...
 service 
...
 using 
...
 the 
...
managed.service.pid
...
 configuration 
...
 property:

{
 Code Block
}
<instance component="...MyComponent">
  <property name="managed.service.pid" value="my.pid.2"/>
</instance>
{code}

{info:title=Type vs.
 Info
titleType vs. Instance configuration
If the managed service pid is specified both in the component type and in the instance configuration, the instance configuration is used.
The managed service pid is the identifier used by the Configuration Admin to attach configuration to Managed Services. First this pid must be unique (as any pid in OSGi). Moreover, this pid cannot be the same one that the pid used in the Managed Service Factory to create the instance (if you use this way to create your instance).
When an instance is reconfigured with the Managed Service, the configuration is propagated if the propagation is enabled.
Dynamic Reconfiguration using Factories or ManagedServiceFactories
iPOJO instances support dynamic reconfiguration. To reconfigure an instance you can use both iPOJO Factory and the ManagedServiceFactory services exposed by the factory of the targeted instance. By calling the method reconfigure or update (according of the service you use), the handler receive the new configuration and apply it. If the propagation is activated, the service registrations are updated too. If there is an updated callback, the callback is invoked.
Being notified when a reconfiguration is completed
Sometimes you need to be notified when a reconfiguration is done (all setter method called). This can be done thanks to the updated attribute. This attribute specifies a method claeed when a configuration/reconfiguration is completed. This method receives a Dictionary containing the properties (pair <key,value>). Properties with no value are not in the received configuration.
Updated callback are declared as follow using annotations:
 Code Block
 Instance configuration}
If the managed service pid is specified both in the component type and in the instance configuration, the instance configuration is used.
{info}

The managed service pid is the identifier used by the Configuration Admin to attach configuration to Managed Services. First this pid must be unique (as any pid in OSGi). Moreover, this pid cannot be the same one that the pid used in the Managed Service Factory to create the instance (if you use this way to create your instance).

When an instance is reconfigured with the Managed Service, the configuration is propagated if the propagation is enabled.

h2. Dynamic Reconfiguration using Factories or ManagedServiceFactories
iPOJO instances support dynamic reconfiguration. To reconfigure an instance you can use both iPOJO {{Factory}} and the {{ManagedServiceFactory}} services exposed by the factory of the targeted instance. By calling the method _reconfigure_ or _update_ (according of the service you use), the handler receive the new configuration and apply it. If the propagation is activated, the service registrations are updated too. If there is an  {{updated}} callback, the callback is invoked.

h2. Being notified when a reconfiguration is completed
Sometimes you need to be notified when a reconfiguration is done (all setter method called). This can be done thanks to the {{updated}} attribute. This attribute specifies a method claeed when a configuration/reconfiguration is completed. This method receives a {{Dictionary}} containing the properties (pair <key,value>). Properties with no value are not in the received configuration.

Updated callback are declared as follow using annotations:
{code}
@Updated
public void updated() {
  // The instance was reconfigured
}

// OR
@Updated
public void updated(Dictionary conf) {
  // The instance was reconfigured, conf is the new configuration.
}

In XML, the method name is given as an attribute of the {{properties}} element.
{code:xml}
<component className="...MyComponent">
   <!-- ... -->
   <properties updated="updated"/>
       <!-- ... -->
   </properties>
</Component>
{code}


The 
...
 callback 
...
 is 
...
 called 
...
AFTER
...
 the 
...
 successful 
...
 application 
...
 of 
...
 the 
...
 reconfiguration.
...

 Include Page
apache-felix-ipojo-footer
apache-felix-ipojo-footer
...