...
Include Page | |||
---|---|---|---|
|
|
...
HTML |
---|
...
<div class="content">
|
...
Service Dependency Management
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 | ||||||
---|---|---|---|---|---|---|
| ||||||
|
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
- Dynamic / Static / Dynamic-Priority : the component can specify the binding policy
- Specific : the dependency targets a specific service provider
- Proxy : by default, iPOJO injects a smart proxy, but it can also be a dynamic proxy or the direct references
Dynamism & Instance Lifecycle
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
Code Block @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.
...
Code Block
...
@Bind public void bindLogService(LogService log) { /*...*/ } @Unbind public void unbindLogService(LogService log) { /*...*/ } @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
...
Code Block
...
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 Block | ||||
---|---|---|---|---|
| ||||
{code:java} @Component @Instantiate public class HelloConsumer { @Requires private Hello m_hello; public doSomething() { System.out.println(m_hello.getMesage()); } } {code} |
You
...
can
...
also
...
use
...
XML
...
to
...
describe
...
this
...
component
...
type:
Code Block | ||||
---|---|---|---|---|
| ||||
{code:xml} <component classname="...HelloConsumer"> <requires field="m_hello"/> ... </component> {code} |
The
...
metadata
...
contains
...
a
...
'requires'
...
element
...
(representing
...
the
...
service
...
dependency)
...
and
...
specify
...
a
...
field
...
used
...
to
...
inject
...
the
...
service.
...
The
...
implementation
...
uses
...
the
...
field
...
as
...
a
...
normal
...
field
...
without
...
managing
...
service
...
interactions.
...
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))
...
- With
...
- the
...
- service
...
- object
...
- and
...
- the
...
- OSGi
...
- service
...
- reference
...
- (method(Service
...
- svc,
...
- ServiceReference
...
- ref))
...
- With
...
- the
...
- service
...
- object
...
- and
...
- the
...
- service
...
- properties
...
- inside
...
- a
...
- Map
...
- (method(Service
...
- svc,
...
- Map
...
- properties))
...
- 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 Block | ||||
---|---|---|---|---|
| ||||
{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()); } } {code} |
The
...
modified
...
callback
...
is
...
not
...
mandatory.
...
The
...
following
...
XML
...
metadata
...
are
...
describing
...
the
...
same
...
component
...
type:
Code Block | ||||
---|---|---|---|---|
| ||||
{code:xml} <component classname="...HelloConsumer"> <requires> <callback type="bind" method="bindHello"> <callback type="unbind" method="unbindHello"> </requires> ... </component> {code} |
Note,
...
that
...
the
...
different
...
callbacks
...
can
...
be
...
have
...
different
...
signatures.
...
By
...
using
...
this
...
mechanism,
...
you
...
need
...
to
...
be
...
sure
...
to
...
manage
...
the
...
dynamism
...
correctly.
...
(
...
...
...
...
...
...
)
...
Using
...
the
...
@Modified
...
callback
...
is
...
also
...
quite
...
simple:
Code Block | ||||
---|---|---|---|---|
| ||||
{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()); } } {code} h3. Using constructor injection (* |
Using constructor injection (1.7.0-SNAPSHOT
...
)
...
Services
...
can
...
also
...
be
...
injected
...
using
...
constructor
...
parameters:
Code Block |
---|
} @Component public class MyComponent { private LogService log; public MyComponent(@Requires LogService log) { this.log = log; } } {code} h3. 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} |
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 Block | ||||
---|---|---|---|---|
| ||||
public class HelloConsumer { @Requires(id="hello") private Hello m_hello; // Injected Field @Bind(id="hello") public void bindHello() { System.out.println("Hello appears"); } @Unbind(id="hello") public void unbindHello() { System.out.println("Hello disapears"); } public doSomething() { System.out.println(m_hello.getMesage()); } } {code} } |
In
...
XML,
...
it
...
results
...
in:
Code Block | ||||
---|---|---|---|---|
| ||||
{code:xml} <component classname="...HelloConsumer"> <requires field="m_hello"> <callback type="bind" method="bindHello"> <callback type="unbind" method="unbindHello"> </requires> ... </component> {code} The {{id}} attribute is used to determine which callbacks |
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
So, it is strongly recommended to specify the id manually.
Injection mechanisms & lazy object creation
iPOJO creates objects only when required. When needed, iPOJO invokes the constructor of the implementation class. The implementation class can use field requirement because values are already injected and obviously constructor parameters. However, method dependencies are called after the constructor. If the service is available before the constructor call, the invocation of the bind methods is delayed until the a component class object is created.
Examples
For all examples both annotations and XML forms are given. Just choose what you'd like to use.
Simple Requirement
By default, a requirement is mandatory, non-filtered and simple (non-aggregate). The previous examples illustrate this kind of dependency. When services goes away and appears, the service substitution is hidden. Fields attached to simple requirement point always a consistent service object. For a simple dependency, the bind method is called once time when the service appears or just after the POJO constructor invocation is the service is available. When the service disappears the unbind method is called. The bind method is re-invoked as soon as another service provider is available. This invocation occurs immediately if another service provider if available. In this case, the instance is not invalidated.
Aggregate Requirement
When a component requires several providers of the same service, it declares an aggregate dependency.
Aggregate Dependency with field injection
Code Block | ||||
---|---|---|---|---|
| ||||
/ 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 So, it is strongly recommended to specify the id manually. h3. Injection mechanisms & lazy object creation iPOJO creates objects only when required. When needed, iPOJO invokes the constructor of the implementation class. The implementation class can use field requirement because values are already injected and obviously constructor parameters. However, method dependencies are called *after* the constructor. If the service is available before the constructor call, the invocation of the bind methods is delayed until the a component class object is created. h2. Examples For all examples both annotations and XML forms are given. Just choose what you'd like to use. h3. Simple Requirement By default, a requirement is mandatory, non-filtered and simple (non-aggregate). The previous examples illustrate this kind of dependency. When services goes away and appears, the service substitution is hidden. Fields attached to simple requirement point always a consistent service object. For a simple dependency, the bind method is called once time when the service appears or just after the POJO constructor invocation is the service is available. When the service disappears the unbind method is called. The bind method is re-invoked as soon as another service provider is available. This invocation occurs immediately if another service provider if available. In this case, the instance is not invalidated. h3. Aggregate Requirement When a component requires several providers of the same service, it declares an aggregate dependency. h4. Aggregate Dependency with field injection {code:java} @Component public class HelloConsumer { @Requires private Hello m_hellos[]; // Array => Aggregate public doSomething() { for(int I = 0; I < m_hellos.length; i++) { System.out.println(m_hellos[i].getMessage()); } } } {code} |
For
...
this
...
component,
...
XML
...
metadata
...
could
...
be:
Code Block | ||||
---|---|---|---|---|
| ||||
{code:xml} <component classname="...HelloConsumer"> <requires field="m_hellos"/> ... </component> {code} |
To
...
declare
...
an
...
aggregate
...
field
...
for
...
field
...
requirement,
...
you
...
only
...
need
...
to
...
declare
...
an
...
array
...
(instead
...
of
...
a
...
scalar
...
type).
...
iPOJO
...
will
...
create
...
and
...
inject
...
the
...
service
...
object
...
array.
...
iPOJO
...
discover
...
that
...
the
...
dependency
...
is
...
aggregate
...
during
...
the
...
bytecode
...
introspection.
...
Array
...
types
...
cannot
...
be
...
'proxied'.
...
Moreover
...
array
...
dependencies
...
cannot
...
be
...
injected
...
as
...
constructor
...
parameter.
Info | ||||
---|---|---|---|---|
| =
| |||
}
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. |
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 Block | ||||
---|---|---|---|---|
| ||||
{info} h4. 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()); } } } {code} |
For
...
this
...
component,
...
XML
...
metadata
...
could
...
be:
Code Block | ||||
---|---|---|---|---|
| ||||
{code:xml} <component classname="...HelloConsumer"> <requires field="m_hellos" specification="org.apache.felix.ipojo.example.Hello"/> ... </component> {code} |
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.
Info | ||
---|---|---|
| ||
The service specification {info:title=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. |
Info | ||
---|---|---|
| ||
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. |
Aggregate Dependency with callbacks
Code Block | ||||
---|---|---|---|---|
| ||||
{info} {info:title=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. {info} h4. Aggregate Dependency with callbacks {code:java} public class HelloConsumer { private List m_hellos = new ArrayList(); @Bind(aggregate=true) private void bindHello(Hello h) { m_hellos.add(h); } @Unbind private void unbindHello(Hello h) { m_hellos.remove(h); } public synchronized doSomething() { for(Hello h : m_hellos) { System.out.println(h.getMessage()); } } } } {code} |
This
...
dependency
...
can
...
also
...
be
...
described
...
in
...
XML
...
as
...
follow:
Code Block | ||||
---|---|---|---|---|
| ||||
{code:xml} <requires aggregate="true"> <callback type="bind" method="bindHello"> <callback type="unbind" method="unbindHello"> </requires> {code} |
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.
Info | ||||
---|---|---|---|---|
| =
| |||
}
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. {info} h3. Optional Requirement |
Optional Requirement (Scalar)
...
An
...
optional
...
requirement
...
does
...
not
...
invalidate
...
the
...
instance
...
despite
...
no
...
providers
...
are
...
available.
...
Moreover,
...
it
...
is
...
possible
...
to
...
inject
...
a
...
default
...
service
...
implementation
...
when
...
no
...
real
...
providers
...
are
...
available.
...
Optional
...
Requirement
...
with
...
field
...
injection
Code Block | ||||
---|---|---|---|---|
| ||||
{code:java} @Component public class HelloConsumer { @Requires(optional=true) private Hello m_hello; public doSomething() { System.out.println(m_hello.getMesage()); } } {code} |
For
...
this
...
component,
...
equivalent
...
XML
...
metadata
...
could
...
be:
Code Block | ||||
---|---|---|---|---|
| ||||
{code:xml} <component classname="...HelloConsumer"> <requires field="m_hello" optional="true"/> ... </component> {code} |
To
...
declare
...
an
...
optional
...
requirement,
...
you
...
need
...
to
...
add
...
the
...
'optional'
...
attribute.
...
To
...
avoid
...
null
...
pointer
...
exception,
...
iPOJO
...
injects
...
a
...
Nullable
...
object
...
in
...
the
...
field
...
when
...
no
...
service
...
provider
...
is
...
available.
...
The
...
nullable
...
object
...
implements
...
the
...
service
...
interface,
...
but
...
does
...
nothing.
...
Moreover,
...
it
...
is
...
possible
...
to
...
set
...
a
...
default-implementation
...
for
...
the
...
service.
...
A
...
default-implementation
...
is
...
a
...
class
...
implementing
...
the
...
service
...
but
...
used
...
only
...
when
...
no
...
others
...
service
...
providers
...
are
...
available.
...
The
...
default-implementation
...
object
...
will
...
be
...
injected
...
instead
...
of
...
the
...
Nullable
...
objet.
...
For
...
further
...
information
...
...
...
...
...
...
...
Optional Dependency with callbacks invocation
Code Block | ||||
---|---|---|---|---|
| ||||
|#nullable]. h4. 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()); } } } {code} |
For
...
this
...
component,
...
XML
...
metadata
...
could
...
be:
Code Block | ||||
---|---|---|---|---|
| ||||
{code:xml} <component classname="...HelloConsumer"> <requires optional="true"> <callback type="bind" method="bindHello"> <callback type="unbind" method="unbindHello"> </requires> ... </component> {code} |
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.
...
Aggregate
...
&
...
Optional
...
Requirement
...
A
...
dependency
...
can
...
be
...
both
...
aggregate
...
and
...
optional.
...
Aggregate
...
&
...
Optional
...
Dependency
...
with
...
field
...
injection
Code Block | ||||
---|---|---|---|---|
| ||||
{code:java} @Component public class HelloConsumer { @Requires(optional=true) private Hello m_hellos[]; public doSomething() { for(Hello h : m_hellos) { System.out.println(h.getMessage()); } } } {code} |
For
...
this
...
component,
...
XML
...
metadata
...
could
...
be:
Code Block | ||||
---|---|---|---|---|
| ||||
{code:xml} <component classname="...HelloConsumer"> <requires field="m_hellos" optional="true"/> ... </component> {code} |
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 Block | ||||
---|---|---|---|---|
| ||||
{code:java} @Compoent public class HelloConsumer { private List m_hellos<Hello> = new ArrayList<Hello>(); @Bind(aggregate=true, optional=true) private void bindHello(Hello h) { m_hellos.add(h); } @Unbind private void unbindHello(Hello h) { m_hellos.remove(h); } public synchronized doSomething() { for(Hello h : m_hellos) { System.out.println(h.getMessage()); } } } {code} |
For
...
this
...
component,
...
XML
...
metadata
...
could
...
be:
Code Block | ||||
---|---|---|---|---|
| ||||
{code:xml} <requires aggregate="true" optional="true"> <callback type="bind" method="bindHello"> <callback type="unbind" method="unbindHello"> </requires> {code} |
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:
Code Block |
---|
} @Requires(filter="(language=fr)") private String DictionaryService dict; {code} {code:xml} |
Code Block | ||||
---|---|---|---|---|
| ||||
<requires filter="(language=fr)" field="dict"/>
{code}
|
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:
Code Block |
---|
} @Component public class MyComponent { @Bind(filter="(langage=en)") public void bindHDictionary(DictionaryService svc) { ... } @Unbind public void unbindDictionary() { ...} @Modified public void modifiedDictionary() { ... } } {code} |
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.
Code Block | ||||
---|---|---|---|---|
| ||||
{code:xml} <component className="org.apache.felix.ipojo.example.FilteredDependency"> <requires field="m_foo" fiter="(foo.property=FOO)" id="id1"> <callback type="bind" method="bind"/> <callback type="unbind" method="unbind"/> </requires> </component> <instance name="FOO1" component="FOO"/> <instance name="FOO2" component="FOO"> <property name="requires.filters"> <property name="id1" value="(foo.property=BAR)"/> </property> </instance> <instance name="FOO3" component="FOO"> <property name="requires.filters"> <property name="id1" value="(foo.property=BAZ)"/> </property> </instance> {code} |
The
...
component
...
type
...
declares
...
a
...
service
...
dependency
...
with
...
the
...
'id1'
...
id.
...
This
...
dependency
...
has
...
no
...
filter
...
by
...
default.
...
The
...
first
...
instance
...
is
...
just
...
an
...
instance
...
of
...
the
...
FOO
...
component
...
type
...
and
...
does
...
not
...
modify
...
the
...
dependency.
...
The
...
second
...
one
...
adds
...
a
...
filter
...
to
...
the
...
declared
...
dependency
...
to
...
target
...
providers
...
with
...
foo.property
...
=
...
BAR.
...
The
...
last
...
one
...
adds
...
another
...
filter
...
to
...
the
...
declared
...
dependency.
...
By
...
using
...
instance
...
filter
...
customization,
...
it
...
is
...
possible
...
to
...
create
...
complex
...
applications
...
where
...
you
...
avoid
...
binding
...
problems
...
by
...
filtering
...
dependencies
...
instance
...
by
...
instance.
...
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:
Code Block |
---|
} @Requires(from="MyHelloProvider") private Hello m_hello; {code} |
or
...
in
...
XML:
Code Block | ||||
---|---|---|---|---|
| ||||
{code:xml} <requires from="MyHelloProvider" field="m_hello"/> {code} |
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.
Code Block | ||||
---|---|---|---|---|
| ||||
{code:xml} <component className="org.apache.felix.ipojo.example.FilteredDependency" name="FOO"> <requires field="m_foo" id="id1"> <callback type="bind" method="bind"/> <callback type="unbind" method="unbind"/> </requires> </component> <instance name="FOO1" component="FOO"/> <instance name="FOO2" component="FOO"> <property name="requires.from"> <property name="id1" value="myprovider"/> </property> </instance> <instance name="FOO3" component="FOO"> <property name="requires.from"> <property name="id1" value="myotherprovider"/> </property> </instance> {code} |
The
...
FOO
...
component
...
type
...
declares
...
a
...
service
...
dependency
...
with
...
the
...
'id1'
...
id.
...
This
...
dependency
...
has
...
no
...
'from'
...
attribute
...
by
...
default.
...
The
...
first
...
instance
...
is
...
just
...
an
...
instance
...
of
...
the
...
FOO
...
component
...
type
...
and
...
does
...
not
...
modify
...
the
...
dependency.
...
The
...
second
...
one
...
adds
...
a
...
'from'
...
attribute
...
to
...
the
...
declared
...
dependency
...
to
...
target
...
the
...
'myprovider'
...
provider.
...
The
...
last
...
one
...
adds
...
another
...
'from'
...
clause
...
to
...
the
...
declared
...
dependency.
...
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.
A static binding is declared as following:
Code Block |
---|
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: {code} @Requires(policy="static") private Hello[] m_hellos; {code} or {code:xml} |
or
Code Block | ||||
---|---|---|---|---|
| ||||
<requires field="m_hellos" policy="static"/>
{code}
|
A
...
dynamic-priority
...
binding
...
is
...
declared
...
as
...
following:
Code Block |
---|
} @Requires(policy="dynamic-priority") private Hello[] m_hellos; {code} or {code: |
or
Code Block | ||||
---|---|---|---|---|
| ||||
xml} <requires field="m_hellos" policy="dynamic-priority"/> {code} |
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).
Code Block |
---|
} @Requires(policy="dynamic-priority", comparator=MyComparator.class) private Hello[] m_hellos; {code} |
or
Code Block | ||||
---|---|---|---|---|
| ||||
or {code:xml} <requires field="m_hellos" policy="dynamic-priority" comparator="great.MyComparator"/> {code} {anchor:nullable} h2. Note about nullable object & default-implementation 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 You can check if the returned object is a nullable object with the test: _"myservice instanceof Nullable"_. 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 |
Anchor | ||||
---|---|---|---|---|
|
Note about nullable object & default-implementation
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
You can check if the returned object is a nullable object with the test: "myservice instanceof Nullable".
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:
Code Block |
---|
} @Requires(optional=true, nullable=false) private LogService m_log; {code} or {code:xml |
or
Code Block | ||||
---|---|---|---|---|
| ||||
} <requires field="m_log" optional="true" nullable="false"/> {code} |
However,
...
you
...
can
...
also
...
indicate
...
a
...
default-implementation
...
for
...
your
...
optional
...
service.
...
In
...
this
...
case,
...
if
...
no
...
providers
...
are
...
found,
...
iPOJO
...
creates
...
an
...
instance
...
of
...
the
...
default-implementation
...
and
...
injects
...
it.
...
The
...
default-implementation
...
attribute
...
describes
...
the
...
class
...
name
...
of
...
your
...
implementation.
...
The
...
given
...
class
...
MUST
...
implement
...
the
...
required
...
service
...
interface.
...
For
...
example,
...
the
...
following
...
component
...
uses
...
a
...
default
...
implementation
...
for
...
a
...
Log
...
Service
...
dependency:
Code Block |
---|
}
@Requires(optional=true, default-implementation=MyLogService.class)
private LogService m_log;
|
or
Code Block | ||||
---|---|---|---|---|
| ||||
{code} or {code:xml} <requires field="m_log" optional="true" default-implementation= "org.apache.felix.ipojo.example.default.MyLogService"/> {code} |
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
...
...
messages
...
on
...
the
...
System.err
...
stream.
...
The
...
nullable
...
object
...
does
...
no
...
display
...
anything.
...
Anchor | ||||
---|---|---|---|---|
|
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
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.
The method can receive in argument the service object or the service reference (in order to obtain service properties). The bind methods are delayed since a POJO object is created.
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
The goal of the proxies is to hide the dynamism and more particularly the dynamism. So, you can gives a service dependency to another object, using the service object still supports the dynamism. For collections, you can iterate over the collection without managing the potential departures and arrivals of services. The proxy also manage that the component class and the delegate objects shared the same services is they are accessed in the same Thread.
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
.
Anchor | ||||
---|---|---|---|---|
|
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).
Include Page | ||||
---|---|---|---|---|
|