Versions Compared

Old Version 17

changes.mady.by.user Clement Escoffier

Saved on

compared with

New Version 18

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}

...

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.
 Wiki Markup
_

{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 Block
xml
xml

{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
xml
xml


{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
xml
xml
<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
xml
xml

{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
apache-felix-ipojo-footer
apache-felix-ipojo-footer
...