felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Felix > How to use iPOJO Annotations
Date Thu, 29 Apr 2010 18:50:00 GMT
<html>
<head>
    <base href="http://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1810/5/1/_/styles/combined.css?spaceKey=FELIX&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="http://cwiki.apache.org/confluence/display/FELIX/How+to+use+iPOJO+Annotations">How
to use iPOJO Annotations</a></h2>
    <h4>Page <b>edited</b> by             <a href="http://cwiki.apache.org/confluence/display/~clement.escoffier">Clement
Escoffier</a>
    </h4>
        <br/>
                         <h4>Changes (4)</h4>
                                 
    
<div id="page-diffs">
            <table class="diff" cellpadding="0" cellspacing="0">
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >* From : defines the specific provider
to use <br>* Specification : the required service specification. This attribute is required
for Collection field. (optional, default = annotated field type).  <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">*
Proxy : enables / disables the proxy injection (enabled by default) <br></td></tr>
            <tr><td class="diff-unchanged" > <br>h3. @ServiceProperty <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >{html} <br> <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h3.
@ServiceController <br> <br>*Goal:* Control the service exposition <br>*Target:*
Field (Boolean) <br>*Attributes:* <br>* value : the default value. If set to false,
it disables the initial exposition <br> <br> <br></td></tr>
            <tr><td class="diff-unchanged" >h3. @Property <br> <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >h3. @Instantiate <br> <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">*_Note_:
New in the 1.5.0-SNAPSHOT* <br> <br></td></tr>
            <tr><td class="diff-unchanged" >*Goal:* declare a simple instance
(this is equivalent to {{&lt;instance component=&quot;...&quot;&gt;&lt;/instance&gt;}}
<br>*Target:* class <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" > * onTimeout : specify the onTimeout
action (null, nullable, empty-array, default-implementation (specify the class name in this
case) (optional). <br> * specification : the required service specification. This attribute
is required for Collection field. (optional, default = annotated field type).  <br></td></tr>
            <tr><td class="diff-changed-lines" >* <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">
Proxy</span> <span class="diff-added-words"style="background-color: #dfd;">proxy</span>
:  Inject a proxy instead of the real object. This allows passing this reference to collaborators.
(Default = false) <br></td></tr>
            <tr><td class="diff-unchanged" > <br> <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
        </table>
</div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <style type="text/css">
 @import url(http://felix.apache.org/ipojo/site/superfish.css); 
</style>

<style type="text/css">
 @import url(http://felix.apache.org/ipojo/site/style.css); 
</style>

<p>
<script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shCore.js"></script>
<script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shBrushCSharp.js"></script>
<script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shBrushPhp.js"></script>
<script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shBrushJScript.js"></script>
<script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shBrushVb.js"></script>
<script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shBrushSql.js"></script>
<script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shBrushXml.js"></script>
<script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shBrushShell.js"></script>
<script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shBrushDelphi.js"></script>
<script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shBrushPython.js"></script>
<script class="javascript" src="http://cwiki.apache.org/confluence/download/resources/confluence.ext.code:code/shBrushJava.js"></script>

<script type="text/javascript" src="http://felix.apache.org/ipojo/site/jquery-1.js"></script>
<script type="text/javascript" src="http://felix.apache.org/ipojo/site/hoverIntent.js"></script>
<script type="text/javascript" src="http://felix.apache.org/ipojo/site/superfish.js"></script>

<script type="text/javascript" src="http://felix.apache.org/ipojo/site/supersubs.js"></script>


<script type="text/javascript"> 
 
    $(document).ready(function(){ 
        $("ul.sf-menu").supersubs({ 
            minWidth:    14,   // minimum width of sub-menus in em units 
            maxWidth:    30,   // maximum width of sub-menus in em units 
            extraWidth:  1     // extra width can ensure lines don't sometimes turn over 
                               // due to slight rounding differences and font-family 
        }).superfish();  // call supersubs first, then superfish, so that subs are 
                         // not display:none when measuring. Call before initialising 
                         // containing tabs for same reason. 
    }); 
 
</script>
<div class="main">
<div class="page-header"/>
<img src="http://felix.apache.org/ipojo/site/header.png" class="header">
<a href="http://ipojo.org"><img src="http://felix.apache.org/ipojo/site/ipojo.png"
width="225" class="header-logo"></a>
<ul class="sf-menu sf-js-enabled sf-shadow" id="ipojo-menu">
<li class="current">
<!-- Menu Overview -->
<a href="#" class="sf-with-ul">Overview<span class="sf-sub-indicator"> »</span><span
class="sf-sub-indicator"> »</span></a>
<ul>
	<li>
	<a href="/confluence/display/FELIX/Apache+Felix+iPOJO" title="Apache Felix iPOJO">Home</a>
						
	</li>
	<li>
	<a href="/confluence/display/FELIX/apache-felix-ipojo-why-choose-ipojo" title="apache-felix-ipojo-why-choose-ipojo">Why
choose iPOJO</a>
	</li>
	<li>
	<a href="/confluence/display/FELIX/apache-felix-ipojo-successstories" title="apache-felix-ipojo-successstories">Success
stories</a>
	</li>
	<li>
	<a href="/confluence/display/FELIX/Apache+Felix+iPOJO+Feature+Overview" title="Apache
Felix iPOJO Feature Overview">Features</a>
	</li>
</ul>
</li>	

<li class="">			
<!-- Menu download -->
<li>
<a href="/confluence/display/FELIX/Download" title="Download">Download </a>
</li>

<li class="">					
<!-- Menu Documentation -->
<a href="#" class="sf-with-ul">Documentation<span class="sf-sub-indicator"> »</span><span
class="sf-sub-indicator"> »</span></a>
<ul>
    <!-- sub-menu : getting started -->
    <li class="">
    <a href="#" class="sf-with-ul">Getting Started<span class="sf-sub-indicator">
»</span><span class="sf-sub-indicator"> »</span></a>
    <ul>
     <li><a href="/confluence/display/FELIX/iPOJO+in+10+minutes" title="iPOJO in
10 minutes">iPOJO in 10 minutes</a></li>
     <li><a href="/confluence/display/FELIX/How+to+use+iPOJO+Annotations" title="How
to use iPOJO Annotations">Using Annotations</a></li>
     <li><a href="/confluence/display/FELIX/iPOJO+Hello+Word+%28Maven-Based%29+tutorial"
title="iPOJO Hello Word (Maven-Based) tutorial">Maven tutorial</a></li>
     <li><a href="/confluence/display/FELIX/iPOJO+Advanced+Tutorial" title="iPOJO
Advanced Tutorial">Advanced tutorial</a></li>
     <li><a href="/confluence/display/FELIX/apache-felix-ipojo-dosgi" title="apache-felix-ipojo-dosgi">Using
Distributed OSGi</a></li>
     <li><a href="/confluence/display/FELIX/iPOJO+Composition+Tutorial" title="iPOJO
Composition Tutorial">Application Composition</a></li>
    </ul>
    </li> <!-- end of getting started -->
    <!-- sub menu : Describing Components -->
     <li class="">
        <a href="http://felix.apache.org/site/describing-components.html" class="sf-with-ul">Describing
components<span class="sf-sub-indicator"> »</span><span class="sf-sub-indicator">
»</span></a>
        <ul>
        <li><a href="/confluence/display/FELIX/Service+Requirement+Handler" title="Service
Requirement Handler">Requiring a service</a></li>
        <li><a href="/confluence/display/FELIX/Providing+OSGi+services" title="Providing
OSGi services">Providing a service</a></li>
        <li><a href="/confluence/display/FELIX/Lifecycle+Callback+Handler" title="Lifecycle
Callback Handler">Lifecycle management</a></li>
        <li><a href="/confluence/display/FELIX/Configuration+Handler" title="Configuration
Handler">Configuration</a></li>
        <li><a href="/confluence/display/FELIX/Architecture+Handler" title="Architecture
Handler">Introspection</a></li>
        <li><a href="/confluence/display/FELIX/Controller+Lifecycle+Handler" title="Controller
Lifecycle Handler">Impacting the lifecycle</a></li>
        <li><a href="/confluence/display/FELIX/Event+Admin+Handlers" title="Event
Admin Handlers">Asynchronous communication</a></li>
        <li><a href="/confluence/display/FELIX/iPOJO+JMX+Handler" title="iPOJO JMX
Handler">JMX management</a></li>
        <li><a href="/confluence/display/FELIX/Extender+Pattern+Handler" title="Extender
Pattern Handler">Extender pattern</a></li>
        <li><a href="/confluence/display/FELIX/White+Board+Pattern+Handler" title="White
Board Pattern Handler">Whiteboard pattern</a></li>
        <li><a href="/confluence/display/FELIX/Temporal+Service+Dependency" title="Temporal
Service Dependency">Temporal dependencies</a></li>
        </ul>
     </li> <!-- End of describing components -->
    <!-- sub-menu : User Guide -->
    <li class="">
    <a href="" class="sf-with-ul">User Guide<span class="sf-sub-indicator"> »</span><span
class="sf-sub-indicator"> »</span></a>
        <ul>
        <li><a href="/confluence/display/FELIX/Combining+iPOJO+and+Configuration+Admin"
title="Combining iPOJO and Configuration Admin">iPOJO and config admin</a></li>
        <li><a href="/confluence/display/FELIX/How-to+use+iPOJO+factories" title="How-to
use iPOJO factories">Factories and Instances</a></li>
        <li><a href="/confluence/display/FELIX/Using+XML+Schemas" title="Using XML
Schemas">XML Schemas</a></li>
        <li><a href="/confluence/display/FELIX/apache-felix-ipojo-api" title="apache-felix-ipojo-api">API</a></li>
        <li><a href="/confluence/display/FELIX/apache-felix-ipojo-testing-components"
title="apache-felix-ipojo-testing-components">Testing components</a></li>
        <li><a href="/confluence/display/FELIX/apache-felix-ipojo-eclipse-integration"
title="apache-felix-ipojo-eclipse-integration">Eclipse Integration</a></li>
        <li><a href="/confluence/display/FELIX/iPOJO+FAQ" title="iPOJO FAQ">FAQ</a></li>
        <li><a href="/confluence/display/FELIX/iPOJO-Reference-Card" title="iPOJO-Reference-Card">Reference
Card</a></li>
        </ul>
    </li> <!-- end of user guide -->
    <!-- sub-menu : Dev Guide -->
    <li> 
    <a href="#" class="sf-with-ul">Advanced Topics<span class="sf-sub-indicator">
»</span><span class="sf-sub-indicator"> »</span></a>
       <ul>
        <li><a href="http://felix.apache.org/ipojo/api/1.6.0" class="external-link"
rel="nofollow">Javadoc</a></li>
        <li><a href="/confluence/display/FELIX/How+to+write+your+own+handler" title="How
to write your own handler">Handler development</a></li>
        <li><a href="/confluence/display/FELIX/How+to+use+iPOJO+Manipulation+Metadata"
title="How to use iPOJO Manipulation Metadata">Manipulation Metadata </a></li>
        <li><a href="/confluence/display/FELIX/Dive+into+the+iPOJO+Manipulation+depths"
title="Dive into the iPOJO Manipulation depths">Dive into the iPOJO Manipulation depths</a></li>
       </ul>
    </li> <!-- End of Dev guide -->
</ul> 
</li> <!-- End of doc -->
<!-- Menu 4 : Tools -->
<li class="">
<a href="#" class="sf-with-ul">Tools<span class="sf-sub-indicator"> »</span><span
class="sf-sub-indicator"> »</span></a>
<ul>
   <li><a href="/confluence/display/FELIX/iPOJO+Ant+Task" title="iPOJO Ant Task">Ant
Task</a></li>
   <li><a href="/confluence/display/FELIX/iPOJO+Eclipse+Plug-in" title="iPOJO Eclipse
Plug-in">Eclipse Plugin</a></li>
   <li><a href="/confluence/display/FELIX/iPOJO+Maven+Plug-in" title="iPOJO Maven
Plug-in">Maven Plugin</a></li>
   <li><a href="/confluence/display/FELIX/iPOJO-Arch-Command" title="iPOJO-Arch-Command"><tt>arch</tt>
shell command</a></li>
   <li><a href="/confluence/display/FELIX/apache-felix-ipojo-online-manipulator"
title="apache-felix-ipojo-online-manipulator">Online Manipulator</a></li>
   <li><a href="/confluence/display/FELIX/iPOJO+Webconsole+Plugin" title="iPOJO Webconsole
Plugin">Webconsole plugin</a></li>
   <li><a href="/confluence/display/FELIX/apache-felix-ipojo-junit4osgi" title="apache-felix-ipojo-junit4osgi">Junit4OSGi</a></li>
</ul>   
</li><!-- End of tools -->	
<!-- Menu 5 : Support -->
<li>
<a href="/confluence/display/FELIX/ipojo-support" title="ipojo-support">Support </a>
</li>
<!-- End of the menu 5 -->			
<!-- Menu 6 : Misc -->
<li class="">
<a href="#" class="sf-with-ul">Misc<span class="sf-sub-indicator"> »</span><span
class="sf-sub-indicator"> »</span></a>
<ul>
   <li><a href="/confluence/display/FELIX/apache-felix-ipojo-supportedVMs" title="apache-felix-ipojo-supportedVMs">Supported
JVMs</a></li>
   <li><a href="/confluence/display/FELIX/apache-felix-ipojo-supportedOSGi" title="apache-felix-ipojo-supportedOSGi">Supported
OSGi Implementations</a></li>
   <li><a href="http://ipojo-dark-side.blogspot.com" class="external-link" rel="nofollow">iPOJO's
Dark Side Blog</a></li>
   <li><a href="/confluence/pages/viewpage.action?pageId=54954" title="Article &amp;
Presentations">Article &amp; Presentations</a></li>
   <li><a href="http://www.apache.org/">ASF</a></li>
   <li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
   <li><a href="http://www.apache.org/foundation/thanks.html">Sponsors</a></li>
</ul>
</li><!-- End of misc -->
</ul> <!-- End of the menu -->
</div> <!-- Page header -->
</p>

<div class="content">

<h1><a name="HowtouseiPOJOAnnotations-HowtouseiPOJOannotations"></a>How
to use iPOJO annotations</h1>

<p><em>You can use annotations to define your component types. This page presents
supported annotations.</em></p>

<div class="toc"><div>
<ul>
    <li><a href='#HowtouseiPOJOAnnotations-GettingiPOJOAnnotations%3A'>Getting
iPOJO Annotations:</a></li>
<ul>
    <li><a href='#HowtouseiPOJOAnnotations-InEclipse'>In Eclipse</a></li>
    <li><a href='#HowtouseiPOJOAnnotations-InMaven'>In Maven</a></li>
    <li><a href='#HowtouseiPOJOAnnotations-InAnt'>In Ant</a></li>
</ul>
    <li><a href='#HowtouseiPOJOAnnotations-Anexampleofusage'>An example of usage</a></li>
<ul>
    <li><a href='#HowtouseiPOJOAnnotations-HelloServiceProvider'>Hello Service
Provider</a></li>
    <li><a href='#HowtouseiPOJOAnnotations-HelloServiceConsumer'>Hello Service
Consumer</a></li>
</ul>
    <li><a href='#HowtouseiPOJOAnnotations-DefinedAnnotations'>Defined Annotations</a></li>
<ul>
    <li><a href='#HowtouseiPOJOAnnotations-@Component'>@Component</a></li>
    <li><a href='#HowtouseiPOJOAnnotations-@Provides'>@Provides</a></li>
    <li><a href='#HowtouseiPOJOAnnotations-@Requires'>@Requires</a></li>
    <li><a href='#HowtouseiPOJOAnnotations-@ServiceProperty'>@ServiceProperty</a></li>
    <li><a href='#HowtouseiPOJOAnnotations-@ServiceController'>@ServiceController</a></li>
    <li><a href='#HowtouseiPOJOAnnotations-@Property'>@Property</a></li>
    <li><a href='#HowtouseiPOJOAnnotations-@Updated'>@Updated</a></li>
    <li><a href='#HowtouseiPOJOAnnotations-@Bind'>@Bind</a></li>
    <li><a href='#HowtouseiPOJOAnnotations-@Unbind'>@Unbind</a></li>
    <li><a href='#HowtouseiPOJOAnnotations-@Validate'>@Validate</a></li>
    <li><a href='#HowtouseiPOJOAnnotations-@Invalidate'>@Invalidate</a></li>
    <li><a href='#HowtouseiPOJOAnnotations-@Instantiate'>@Instantiate</a></li>
    <li><a href='#HowtouseiPOJOAnnotations-TemporalDependencies%28externalhandler%29'>Temporal
Dependencies (external handler)</a></li>
    <li><a href='#HowtouseiPOJOAnnotations-ExposinginstancesasaJMXMBean%28externalhandler%29'>Exposing
instances as a JMX MBean (external handler)</a></li>
</ul>
    <li><a href='#HowtouseiPOJOAnnotations-AdvancedtopicsandFAQ'>Advanced topics
and FAQ</a></li>
<ul>
    <li><a href='#HowtouseiPOJOAnnotations-Metadatafileandannotationmerge'>Metadata
file and annotation merge</a></li>
    <li><a href='#HowtouseiPOJOAnnotations-Instancecreation'>Instance creation</a></li>
    <li><a href='#HowtouseiPOJOAnnotations-UsingCustomAnnotations'>Using Custom
Annotations</a></li>
</ul>
</ul></div></div>

<h2><a name="HowtouseiPOJOAnnotations-GettingiPOJOAnnotations%3A"></a>Getting
iPOJO Annotations:</h2>

<p>iPOJO Annotations are defines inside the org.apache.felix.ipojo.annotations project.
You can download the Jar file of this project from the <a href="/confluence/display/FELIX/Download"
title="Download">download</a> page. Sources are available on the <a href="http://felix.apache.org/site/sourcecode.html"
class="external-link" rel="nofollow">Felix trunk</a>.<br/>
Once added to your class path / build path / dependencies, you can use the annotations as
normal annotations. These annotations are automatically processed by the iPOJO manipulator.</p>

<h3><a name="HowtouseiPOJOAnnotations-InEclipse"></a>In Eclipse</h3>

<p>Add the org.apache.felix.ipojo.annotations jar file in your build path. Do not forget
to use a Java compiler accepting annotations (1.5 or higher).</p>

<h3><a name="HowtouseiPOJOAnnotations-InMaven"></a>In Maven</h3>

<p>Add the following dependency:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;dependency&gt;</span>
      <span class="code-tag">&lt;groupId&gt;</span>org.apache.felix<span
class="code-tag">&lt;/groupId&gt;</span>
      <span class="code-tag">&lt;artifactId&gt;</span>org.apache.felix.ipojo.annotations<span
class="code-tag">&lt;/artifactId&gt;</span>
      <span class="code-tag">&lt;version&gt;</span>1.2.0<span class="code-tag">&lt;/version&gt;</span>
<span class="code-tag">&lt;/dependency&gt;</span>
</pre>
</div></div>
<p>Moreover, you need to set that the source code and the target code are Java 1.5 code.
To achieve this, just add the following plugin in your plugins section:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;plugin&gt;</span>
        <span class="code-tag">&lt;groupId&gt;</span>org.apache.maven.plugins<span
class="code-tag">&lt;/groupId&gt;</span>
	<span class="code-tag">&lt;artifactId&gt;</span>maven-compiler-plugin<span
class="code-tag">&lt;/artifactId&gt;</span>
	<span class="code-tag">&lt;configuration&gt;</span>
	  <span class="code-tag">&lt;source&gt;</span>1.5<span class="code-tag">&lt;/source&gt;</span>
	  <span class="code-tag">&lt;target&gt;</span>1.5<span class="code-tag">&lt;/target&gt;</span>
	<span class="code-tag">&lt;/configuration&gt;</span>
<span class="code-tag">&lt;/plugin&gt;</span>
</pre>
</div></div>

<h3><a name="HowtouseiPOJOAnnotations-InAnt"></a>In Ant</h3>

<p>Just add the org.apache.felix.ipojo.annotations jar file  in your class path.</p>

<h2><a name="HowtouseiPOJOAnnotations-Anexampleofusage"></a>An example of
usage</h2>

<p>To illustrate annotations usage, let taking the tutorial example. In this tutorial,
there are two components:</p>
<ul>
	<li>The first one provides the hello service</li>
	<li>The second one uses the provided hello service<br/>
You can download the archive containing the examples and a preconfigured version of Felix
<a href="http://people.apache.org/~clement/ipojo/tutorials/annotations/annotation-tutorial.zip"
class="external-link" rel="nofollow">here</a>.</li>
</ul>


<h3><a name="HowtouseiPOJOAnnotations-HelloServiceProvider"></a>Hello Service
Provider</h3>

<p>The provider uses two annotations. The "component" annotation is mandatory and defines
that the class defines a component type. Then the "provides" annotation just declare that
the defined component type provides a service.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">package</span> ipojo.example.hello.impl;

<span class="code-keyword">import</span> ipojo.example.hello.Hello;

<span class="code-keyword">import</span> org.apache.felix.ipojo.annotations.Component;
<span class="code-keyword">import</span> org.apache.felix.ipojo.annotations.Provides;

/**
  * Component implementing the Hello service.
 **/
@Component
@Provides
<span class="code-keyword">public</span> class HelloImpl <span class="code-keyword">implements</span>
Hello {
    <span class="code-keyword">public</span> <span class="code-object">String</span>
sayHello(<span class="code-object">String</span> name) { 
     <span class="code-keyword">return</span> <span class="code-quote">"hello
"</span> + name; 
    }
}
</pre>
</div></div>

<h3><a name="HowtouseiPOJOAnnotations-HelloServiceConsumer"></a>Hello Service
Consumer</h3>

<p>The Hello Service Consumer use more annotations. First it used the component annotation.
To defines its "immediate" behavior, it add the 'immediate' attribute.<br/>
Then, it uses the requires annotation to define a service dependency. Finally, it uses the
validate and invalidate annotations to define lifecycle callbacks.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">package</span> ipojo.example.hello.client;

<span class="code-keyword">import</span> org.apache.felix.ipojo.annotations.Component;
<span class="code-keyword">import</span> org.apache.felix.ipojo.annotations.Invalidate;
<span class="code-keyword">import</span> org.apache.felix.ipojo.annotations.Requires;
<span class="code-keyword">import</span> org.apache.felix.ipojo.annotations.Validate;

<span class="code-keyword">import</span> ipojo.example.hello.Hello;

@Component(name=<span class="code-quote">"AnnotedHelloClient"</span>, immediate=<span
class="code-keyword">true</span>)
<span class="code-keyword">public</span> class HelloClient <span class="code-keyword">implements</span>
<span class="code-object">Runnable</span> {

@Requires
<span class="code-keyword">private</span> Hello[] m_hello; <span class="code-comment">//
Service Dependency
</span>
<span class="code-keyword">private</span> <span class="code-keyword">final</span>
<span class="code-keyword">static</span> <span class="code-object">int</span>
DELAY=10000;
<span class="code-keyword">private</span> <span class="code-object">boolean</span>
end;

 <span class="code-keyword">public</span> void run() {
    <span class="code-keyword">while</span> (!end) {
               <span class="code-keyword">try</span> {
		invoke();
                <span class="code-object">Thread</span>.sleep(DELAY);
              } <span class="code-keyword">catch</span> (InterruptedException
ie) { }
              /* will recheck end */
     }
}

<span class="code-keyword">public</span> void invoke() {
	<span class="code-keyword">for</span> (<span class="code-object">int</span>
i = 0; i &lt; m_hello.length; i++) { 
          <span class="code-object">System</span>.out.println(m_hello[i].
             sayHello(<span class="code-quote">"Clement"</span>)); 
        }
}

 @Validate
 <span class="code-keyword">public</span> void starting() {    
    <span class="code-object">Thread</span> T = <span class="code-keyword">new</span>
<span class="code-object">Thread</span>(<span class="code-keyword">this</span>);
    
    end = <span class="code-keyword">false</span>;     
    T.start(); 
 }

 @Invalidate
 <span class="code-keyword">public</span> void stopping() {    
     end = <span class="code-keyword">true</span>; 
 }
}
</pre>
</div></div>

<h2><a name="HowtouseiPOJOAnnotations-DefinedAnnotations"></a>Defined Annotations</h2>

<p>This section lists defined annotations and how to use them.</p>

<h3><a name="HowtouseiPOJOAnnotations-@Component"></a>@Component</h3>

<p><b>Goal:</b> Defines a component type<br/>
<b>Target:</b> The component implementation class<br/>
<b>Attributes:</b></p>
<ul>
	<li>name : defines the component type name (optional, default = the class name)</li>
	<li>immediate: defines the component type as immediate (optional, default = "false")</li>
	<li>architecture: enable the architecture exposition (optional, default = "false")</li>
	<li>propagation: enable configuration property propagation (on provided services) (optional,
default = "false")</li>
	<li>managedservice : set the Managed Service PID. (optional, default = no PID (i.e.
the managed service will not be exposed)).</li>
	<li>factory_method : set the factory-method. The specified method must be a static
method and  return a pojo object.(optional,  default = iPOJO uses the 'regular' constructor).</li>
	<li>public_factory : set if the component type is public. (optional, default = true).</li>
</ul>


<h3><a name="HowtouseiPOJOAnnotations-@Provides"></a>@Provides</h3>

<p><b>Goal:</b> Defines that the component type provide services<br/>
<b>Target:</b> The component implementation class<br/>
<b>Attributes:</b></p>
<ul>
	<li>specifications: defines the provided interface (optional, default = all implemented
interfaces)</li>
	<li>strategy : the service object creation strategy. Possible values : SINGLETON, SERVICE,
METHOD, INSTANCE or the strategy class name. With SINGLETON there is only one POJO per component
instance, SERVICE means OSGi Service factory,  METHOD delegates the creation to the factory-method
of the component, INSTANCE creates one service object per requiring instance. For other strategies,
specify the qualified name of the CreationStrategy class. (optional, default =  SINGLETON)</li>
</ul>



<div class="box">
	<div class="box-blue-header">
	<div class="box-blue-title">
		<img src="http://people.apache.org/~clement/ipojo/site/information.gif"> <b>OSGi
Service Factory</b>
	</div>
	</div>
	<div class="box-blue-content">
The <tt>SERVICE</tt> strategy refers to the OSGi service factory. So, one service
object per asking bundle will be created.
	</div>
	<div class="box-blue-footer"></div>
</div>




<div class="box">
	<div class="box-blue-header">
	<div class="box-blue-title">
		<img src="http://people.apache.org/~clement/ipojo/site/information.gif"> <b>Changes
between the 1.0.0 and the 1.2.0</b>
	</div>
	</div>
	<div class="box-blue-content">
The <tt>factory</tt> attribute became <tt>strategy</tt>. A third policy
is now available (<tt>instance</tt>) allowing to create one service object per
asking instance. Moreover, it is also possible to indicates the <tt>CreationStrategy</tt>
class name. 
	</div>
	<div class="box-blue-footer"></div>
</div>


<h3><a name="HowtouseiPOJOAnnotations-@Requires"></a>@Requires</h3>

<p><b>Goal:</b> Defines a service dependency<br/>
<b>Target:</b> Field<br/>
<b>Attributes:</b></p>
<ul>
	<li>Filter: defines the LDAP filter (optional)</li>
	<li>Optional: defines if the dependency is optional (optional, default = "false")</li>
	<li>Id: defines the dependency Id (useful to identify bind &amp; unbind methods)
(optional, default = field name) (if a dependency with the same id is already created (by
a @bind or @unbind annotation), it merges the dependencies).</li>
	<li>Nullable: enable or disable the Null Object injection when the dependency is optional
and no providers are available (optional, default = "true")</li>
	<li>Default-Implementation: set the Default-Implmentation (optional, by default iPOJO
uses a Null object)</li>
	<li>Policy: defines the binding policy (accepted value : dynamic, static, dynamic-priority)
(optional, default = "dynamic")</li>
	<li>Comparator: defines the comparator to use to sort service references (optional,
default = OSGi Service Reference Comparator)</li>
	<li>From : defines the specific provider to use</li>
	<li>Specification : the required service specification. This attribute is required
for Collection field. (optional, default = annotated field type).</li>
	<li>Proxy : enables / disables the proxy injection (enabled by default)</li>
</ul>


<h3><a name="HowtouseiPOJOAnnotations-@ServiceProperty"></a>@ServiceProperty</h3>

<p><b>Goal:</b> Defines a service property<br/>
<b>Target:</b> Field<br/>
<b>Attributes:</b></p>
<ul>
	<li>name: property name (optional, default=field name</li>
	<li>value: property value (optional, default=no value)</li>
	<li>mandatory : is the property mandatory? (optional, default=false)</li>
</ul>



<div class="box">
	<div class="box-blue-header">
	<div class="box-blue-title">
		<img src="http://people.apache.org/~clement/ipojo/site/information.gif"> <b>Mandatory
property</b>
	</div>
	</div>
	<div class="box-blue-content">
A mandatory property must receive a value either from the component type description (<tt>value</tt>
attribute, or the instance configuration.
	</div>
	<div class="box-blue-footer"></div>
</div>


<h3><a name="HowtouseiPOJOAnnotations-@ServiceController"></a>@ServiceController</h3>

<p><b>Goal:</b> Control the service exposition<br/>
<b>Target:</b> Field (Boolean)<br/>
<b>Attributes:</b></p>
<ul>
	<li>value : the default value. If set to false, it disables the initial exposition</li>
</ul>



<h3><a name="HowtouseiPOJOAnnotations-@Property"></a>@Property</h3>

<p><b>Goal:</b> Defines a property<br/>
<b>Target:</b> Field or Method<br/>
<b>Attributes:</b></p>
<ul>
	<li>name: property name (optional, default=field name computed by removing "set" from
the method name (for instance setFoo(String ff) will get the Foo name))</li>
	<li>value: property value (optional, default=no value)</li>
	<li>mandatory : is the property mandatory? (optional, default=false)</li>
</ul>



<div class="box">
	<div class="box-blue-header">
	<div class="box-blue-title">
		<img src="http://people.apache.org/~clement/ipojo/site/information.gif"> <b>Field
and Method</b>
	</div>
	</div>
	<div class="box-blue-content">
If another property with the same name is defined the method or the field is added to the
existing property.
	</div>
	<div class="box-blue-footer"></div>
</div>


<h3><a name="HowtouseiPOJOAnnotations-@Updated"></a>@Updated</h3>
<p><b>Goal:</b> Defines method called when a reconfiguration is completed.<br/>
<b>Target:</b> a method (receiving a dictionary in argument)</p>

<h3><a name="HowtouseiPOJOAnnotations-@Bind"></a>@Bind</h3>

<p><b>Goal:</b> Defines a bind method<br/>
<b>Target:</b> Method<br/>
<b>Attributes:</b></p>
<ul>
	<li>Id: Dependency Id, if the id is already defines in a "@requires " or "@unbind"
annotation, it adds this method as a bind method of the already created dependency. (optional,
default= no id, compute an id if the method name begin by "bind" (for instance "bindFoo" will
have the "Foo" id))</li>
	<li>Specification : required dependency (optional)</li>
	<li>Aggregate : is the dependency an aggregate dependency (optional, default= "false")</li>
	<li>Optional: is the dependency an optional dependency (optional, default= "false")</li>
	<li>Filter: dependency LDAP filter (optional)</li>
	<li>Policy: defines the binding policy (accepted value : dynamic, static, dynamic-priority)
(optional, default = "dynamic")</li>
	<li>Comparator: defines the comparator to use to sort service references (optional,
default = OSGi Service Reference Comparator)</li>
	<li>From : defines the specific provider to use</li>
</ul>



<h3><a name="HowtouseiPOJOAnnotations-@Unbind"></a>@Unbind</h3>

<p><b>Goal:</b> Defines an unbind method<br/>
<b>Target:</b> Method<br/>
<b>Attributes:</b></p>
<ul>
	<li>Id: Dependency Id, if the id is already defines in a "@requires" or "@bind" annotation,
it adds this method as an unbind method of the already created dependency. (optional, default=
no id, compute an id if the method name begin by "unbind" (for instance "unbindFoo" will have
the "Foo" id))</li>
	<li>Specification : required dependency (optional)</li>
	<li>Aggregate : is the dependency an aggregate dependency (optional, default= "false")</li>
	<li>Optional: is the dependency an optional dependency (optional, default= "false")</li>
	<li>Filter: dependency LDAP filter (optional)</li>
	<li>Policy: defines the binding policy (accepted value : dynamic, static, dynamic-priority)
(optional, default = "dynamic")</li>
	<li>Comparator: defines the comparator to use to sort service references (optional,
default = OSGi Service Reference Comparator)</li>
	<li>From : defines the specific provider to use</li>
</ul>


<h3><a name="HowtouseiPOJOAnnotations-@Validate"></a>@Validate</h3>

<p><b>Goal:</b> defines a validate lifecycle callback<br/>
<b>Target:</b> method</p>

<h3><a name="HowtouseiPOJOAnnotations-@Invalidate"></a>@Invalidate</h3>

<p><b>Goal:</b> defines a validate lifecycle callback<br/>
<b>Target:</b> method</p>

<h3><a name="HowtouseiPOJOAnnotations-@Instantiate"></a>@Instantiate</h3>

<p><b>Goal:</b> declare a simple instance (this is equivalent to <tt>&lt;instance
component="..."&gt;&lt;/instance&gt;</tt><br/>
<b>Target:</b> class</p>

<h3><a name="HowtouseiPOJOAnnotations-TemporalDependencies%28externalhandler%29"></a>Temporal
Dependencies (external handler)</h3>

<p>The temporal dependency handler is an external handler. However, it can be used with
an annotation defined in the iPOJO annotations jar file. <br/>
The annotation is org.apache.felix.ipojo.handler.temporal.Requires and targets a field. <br/>
<b>Attributes:</b></p>
<ul>
	<li>filter : specify the dependency filter</li>
	<li>timeout : specify the dependency timeout (optional)</li>
	<li>onTimeout : specify the onTimeout action (null, nullable, empty-array, default-implementation
(specify the class name in this case) (optional).</li>
	<li>specification : the required service specification. This attribute is required
for Collection field. (optional, default = annotated field type).</li>
	<li>proxy :  Inject a proxy instead of the real object. This allows passing this reference
to collaborators. (Default = false)</li>
</ul>




<h3><a name="HowtouseiPOJOAnnotations-ExposinginstancesasaJMXMBean%28externalhandler%29"></a>Exposing
instances as a JMX MBean (external handler)</h3>

<p>The JMX Handler allows exposing an instance as a JMX MBean. To configure the JMX
handler directly from your code, three annotations are provided. They are in the <tt>org.apache.felix.ipojo.handlers.jmx</tt>
package</p>

<p>The <tt>@org.apache.felix.ipojo.handlers.jmx.Config</tt> (<tt>@Config</tt>
if the package it correctly imported) annotation is a type annotation (so placed on the <tt>class</tt>
element. This annotation indicates that the instance will be exposed as an MBean. This annotation
supports:</p>
<ul>
	<li>usesMOSGi: set to <tt>true</tt> to use MOSGi. Otherwise, the MBean
will be exposed in the MBean Platform Server (default: <tt>false</tt>).</li>
	<li>objectname: set the MBean objectname. The objectname must follow JMX specification.
(default: <tt>package-name:factory-name:instance-name</tt>)</li>
	<li>domain: set the MBean domain. (default: <tt>package-name</tt>)</li>
	<li>name: set the MBean name. (default: <tt>instance-name</tt>).</li>
</ul>


<p>The <tt>@org.apache.felix.ipojo.handlers.jmx.Property</tt> (<tt>@Property</tt>)
annotation is a field annotation indicating that the field is exposed in the MBean. The supported
attributes are:</p>
<ul>
	<li>name: set the property name</li>
	<li>rights: set the access permission. Possible values are <tt>r</tt> (read
only) and <tt>w</tt> (read and write). By default, properties are in read-only
mode.</li>
	<li>notification: enables notification on this property. By default notifications are
disabled.</li>
</ul>


<p>The <tt>@org.apache.felix.ipojo.handlers.jmx.Method</tt> (<tt>@Method</tt>)
annotation is a method annotation indicating that the method is exposed in the MBean. Only
one attribute can be customized:</p>
<ul>
	<li>description: set the method description.</li>
</ul>



<h2><a name="HowtouseiPOJOAnnotations-AdvancedtopicsandFAQ"></a>Advanced
topics and FAQ</h2>

<h3><a name="HowtouseiPOJOAnnotations-Metadatafileandannotationmerge"></a>Metadata
file and annotation merge</h3>

<p>It is possible to defines component type both in the metadata file (in XML) and by
using annotation. However, if a component type defined by using annotations has the same name
than a type define in the XML file, the XML descriptor override the annotation defined type.
However, a warning message is launched during the manipulation.</p>

<h3><a name="HowtouseiPOJOAnnotations-Instancecreation"></a>Instance creation</h3>

<p>The @Instantiate annotation allows creating an instance, but this declaration is
limited:</p>
<ul>
	<li>it does not support configuration</li>
	<li>it does not allow naming</li>
	<li>the instance is created in the global scope (so no composition)</li>
</ul>


<p>To define instances, you should use the XML descriptor. Instance can refer to annotated
types by referring to their names.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;instance component=<span class="code-quote">"ipojo.example.hello.impl.HelloImpl"</span>/&gt;</span>
<span class="code-tag">&lt;instance component=<span class="code-quote">"AnnotedHelloClient"</span>/&gt;</span>
</pre>
</div></div>

<h3><a name="HowtouseiPOJOAnnotations-UsingCustomAnnotations"></a>Using
Custom Annotations</h3>

<p>External handlers can provides their own annotations. Using these annotations just
requires to add them to your build path. To external handlers annotations, please refer to
the external handler documentation.
<br class="atl-forced-newline" />
<br class="atl-forced-newline" /></p>

 </div>
        <img src="http://felix.apache.org/ipojo/site/footer.png" class="footer">
</div>

<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
try{
var pageTracker = _gat._getTracker("UA-1518442-4");
pageTracker._trackPageview();
} catch(err) {}
</script>

    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="http://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="http://cwiki.apache.org/confluence/display/FELIX/How+to+use+iPOJO+Annotations">View
Online</a>
        |
        <a href="http://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=63760&revisedVersion=37&originalVersion=36">View
Changes</a>
                |
        <a href="http://cwiki.apache.org/confluence/display/FELIX/How+to+use+iPOJO+Annotations?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message