THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
...
| Include Page | |||
|---|---|---|---|
|
|
...
| HTML |
|---|
...
<div class="content">
|
The temporal dependency handler
Regular service dependencies participate to the instance lifecycle. Moreover, the injected service object is either available or not available. A temporal dependency handler is a little different and provides a different resolution pattern. Indeed, the temporal dependency does not invalidate the instance. Moreover, if not available, the temporal dependency waits (and so blocks the current thread) for a provider. Of course, the maximum waiting time can be specified. If a timeout occurs, the handler throws a Runtime Exception.
| Div | ||||||
|---|---|---|---|---|---|---|
| ||||||
|
Using the handler
First of all, you need to configure the component type to use the handler such as:
| Code Block | ||||
|---|---|---|---|---|
| ||||
{html} h1.The temporal dependency handler _Regular service dependencies participate to the instance lifecycle. Moreover, the injected service object is either available or not available. A temporal dependency handler is a little different and provides a different resolution pattern. Indeed, the temporal dependency does not invalidate the instance. Moreover, if not available, the temporal dependency waits (and so blocks the current thread) for a provider. Of course, the maximum waiting time can be specified. If a timeout occurs, the handler throws a Runtime Exception._ {div:class=toc} {toc:maxLevel=4|minLevel=2} {div} h2. Using the handler First of all, you need to configure the component type to use the handler such as: {code:xml} <iPOJO xmlns:temporal="org.apache.felix.ipojo.handler.temporal"> <component className="org.apache.felix.ipojo.example.Temporal"> <!-- Temporal dependency configuration --> <temporal:requires field="mytemporal"/> <provides/> </component> </iPOJO> {code} |
Notice
...
that,
...
this
...
handler
...
is
...
an
...
external
...
handler.
...
So,
...
it
...
uses
...
the
...
"org.apache.felix.ipojo.handler.temporal"
...
namespace.
...
Once
...
described,
...
you
...
can
...
implement
...
your
...
component.
...
The
...
specified
...
field
...
will
...
be
...
mapped
...
to
...
the
...
temporal
...
dependency.
...
As
...
for
...
regular
...
field
...
injection,
...
aggregation,
...
targeted
...
service
...
specification
...
(i.e.
...
interface)
...
is
...
discovered
...
automatically.
...
Filter,
...
comparator
...
and
...
binding
...
policy
...
are
...
also
...
supported.
...
However,
...
the
...
optional
...
attribute
...
is
...
not
...
supported.
...
In
...
fact,
...
this
...
attribute
...
is
...
meaningless
...
in
...
the
...
case
...
of
...
a
...
temporal
...
dependency.
...
Using
...
the
...
field
...
in
...
your
...
code
...
will
...
try
...
to
...
find
...
a
...
matching
...
service
...
provider.
...
If
...
a
...
provider
...
is
...
available,
...
the
...
field
...
receives
...
the
...
service
...
object
...
immediately.
...
Else,
...
the
...
thread
...
is
...
stopped
...
and
...
waits
...
for
...
a
...
provider.
...
The
...
default
...
wait
...
time
...
is
...
3s
...
(you
...
can
...
also
...
specify
...
this
...
time).
...
If
...
no
...
provider
...
is
...
available
...
after
...
this
...
time,
...
the
...
thread
...
throws
...
a
...
RuntimeException.
...
If
...
a
...
provider
...
becomes
...
available
...
during
...
this
...
time,
...
the
...
field
...
receives
...
immediately
...
the
...
value
...
and
...
the
...
execution
...
can
...
continue.
...
You
...
can
...
also
...
use
...
annotations:
| Code Block |
|---|
} @Component public class Temporal { @Temporal // was org.apache.felix.ipojo.handler.temporal.Requires before the 1.7.0 private FooService mytemporal; } {code} h2. Configuration The handler has only one mandatory attributes: * Field: the implementation field supporting the dependency (not needed with annotations) The handler supports on specific optional attributes: * Timeout: the maximum time waited in order to find a provider (default: 3s). For an infinite timeout, the timeout value is either "infinite" or "-1". * OnTimeout: specifies the action to do when the timeout occurs. Four actions are supported: null, nullable, empty-array, default-implementation. By default, no action is specified, and an exception occurs when the timeout is reached. The attributes from "regular" dependencies are also supported (like filter). OnTimeout actions When a timeout occurs, you can specify what the handler must do. By default, it throws a runtime exception. However, four others actions can be set in the 'onTimeout' attribute. * The null action |
Configuration
The handler has only one mandatory attributes:
- Field: the implementation field supporting the dependency (not needed with annotations)
The handler supports on specific optional attributes:
- Timeout: the maximum time waited in order to find a provider (default: 3s). For an infinite timeout, the timeout value is either "infinite" or "-1".
- OnTimeout: specifies the action to do when the timeout occurs. Four actions are supported: null, nullable, empty-array, default-implementation. By default, no action is specified, and an exception occurs when the timeout is reached.
The attributes from "regular" dependencies are also supported (like filter).
OnTimeout actions
When a timeout occurs, you can specify what the handler must do. By default, it throws a runtime exception. However, four others actions can be set in the 'onTimeout' attribute.
- The null action (onTimeout="null")
...
- will
...
- return
...
- "null"
...
- instead
...
- of
...
- the
...
- service
...
- object.
...
- The
...
- "nullable"
...
- action
...
- (onTimeout="nullable")
...
- will
...
- return
...
- a
...
- "Nullable"
...
- object
...
- instead
...
- of
...
- the
...
- service
...
- object.
...
- This
...
- object
...
- is
...
- a
...
- fake
...
- but
...
- can
...
- be
...
- used
...
- a
...
- regular
...
- service
...
- object.
...
- However,
...
- invoking
...
- actions
...
- on
...
- this
...
- object
...
- will
...
- do
...
- nothing.
...
- In
...
- the
...
- case
...
- of
...
- aggregate
...
- dependency,
...
- an
...
- array
...
- containing
...
- a
...
- "nullable"
...
- object
...
- is
...
- returned.
...
- The
...
- empty
...
- action
...
- is
...
- only
...
- supported
...
- for
...
- aggregate
...
- dependency
...
- (the
...
- field
...
- must
...
- be
...
- an
...
- array).
...
- In
...
- this
...
- case,
...
- an
...
- empty-array
...
- is
...
- returned.
...
- (In
...
- the
...
- 1.2.0
...
- version,
...
- the
...
empty-array
...
- attribute
...
- became
...
empty
...
- )
...
- The
...
- default-implementation
...
- action
...
- is
...
- a
...
- little
...
- different.
...
- Instead
...
- of
...
- specifying
...
- the
...
- action,
...
- you
...
- need
...
- to
...
- specify
...
- the
...
- default-implementation
...
- (the
...
- qualified
...
- class
...
- name)
...
- that
...
- you
...
- want
...
- to
...
- use.
...
- For
...
- example
...
- onTimeout="o.a.f.i.MyDefaultLogServiceImpl".
...
- In
...
- this
...
- case,
...
- the
...
- handler
...
- will
...
- inject
...
- an
...
- instance
...
- of
...
- this
...
- object
...
- instead
...
- of
...
- a
...
- real
...
- service
...
- object.
...
- On
...
- aggregate
...
- dependency,
...
- an
...
- array
...
- with
...
- one
...
- default-implementation
...
- object
...
- is
...
- returned.
| Code Block | ||||
|---|---|---|---|---|
| ||||
{code:xml} <iPOJO xmlns:temporal="org.apache.felix.ipojo.handler.temporal"> <component className="org.apache.felix.ipojo.example.Temporal"> <!-- Temporal dependency configuration --> <temporal:requires field="fs" timeout="300" ontimeout="nullable"/> <provides/> </component> </iPOJO> {code} |
This
...
is
...
equivalent
...
to:
| Code Block |
|---|
} @Component public class Temporal { @Temporal(timeout=300, ontimeout="nullable") private FooService mytemporal; } {code} h2. Collection injection Temporal dependencies can also be injected inside Collection. To achieve this, the 'specification' attribute must indicates the looked specification, and the field must be a Collection. {code:xml} |
Collection injection
Temporal dependencies can also be injected inside Collection. To achieve this, the 'specification' attribute must indicates the looked specification, and the field must be a Collection.
| Code Block | ||||
|---|---|---|---|---|
| ||||
<iPOJO xmlns:temporal="org.apache.felix.ipojo.handler.temporal">
<component
className="org.apache.felix.ipojo.example.Temporal">
<!-- Temporal dependency configuration -->
<temporal:requires field="mycollection" specification="my.service.specification"/>
<provides/>
</component>
</iPOJO>
{code}
|
This
...
is
...
equivalent
...
to:
| Code Block |
|---|
} @Component public class Temporal { @Temporal(specification="my.service.specification") private List<FooService> mycollection; } {code} h2. Proxy injection Temporal dependencies can also be injected as proxies. So it is possible to give the temporal dependency to helper object. On 'scalar' dependencies, the service lookup is executed during an operation invocation. Timeout policies are also executed is the lookup failed. On aggregate dependencies (necessary Collection), the service lookup is executed when the iterator(), and |
Proxy injection
Temporal dependencies can also be injected as proxies. So it is possible to give the temporal dependency to helper object.
On 'scalar' dependencies, the service lookup is executed during an operation invocation. Timeout policies are also executed is the lookup failed.
On aggregate dependencies (necessary Collection), the service lookup is executed when the iterator(), and toArray(...)
...
methods
...
are
...
invoked.
...
Timeout
...
policies
...
are
...
also
...
executed
...
if
...
the
...
lookup
...
failed.
...
Proxies
...
are
...
enabled
...
by
...
default
...
since
...
the
...
1.7.0
...
version.
...
To
...
set
...
a
...
temporal
...
dependency
...
as
...
a
...
proxy,
...
just
...
add
...
the
...
proxy
...
attribute
...
as
...
follows:
| Code Block | ||||
|---|---|---|---|---|
| ||||
{code:xml} <iPOJO xmlns:temporal="org.apache.felix.ipojo.handler.temporal"> <component className="org.apache.felix.ipojo.example.Temporal"> <!-- Temporal dependencies configuration --> <temporal:requires proxy="true" field="fs"/> <temporal:requires proxy="true" field="mycollection" specification="my.service.specification"/> <provides/> </component> </iPOJO> {code} |
By
...
default,
...
proxies
...
are
...
enabled
...
.
...
Setting
...
proxy
...
to
...
false
...
disables
...
them.
...
Download
The handler is available on the download page.
Sources are available on the Felix trunk at the following location: http://svn.apache.org/repos/asf/felix/trunk/ipojo/handler/temporal
...
.
| Include Page | ||||
|---|---|---|---|---|
|
...