| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE- 2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <head> |
| <title>Apache Felix - How to use iPOJO Annotations</title> |
| <link rel="icon" href="/res/favicon.ico"> |
| |
| <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <meta name="description" content="The most powerful component model for OSGi"> |
| |
| |
| <link href="/ipojo/web/bootstrap/css/bootstrap-cerulean.css" rel="stylesheet"> |
| <link href="/ipojo/web/bootstrap/css/bootstrap-responsive.css" rel="stylesheet"> |
| <link href="/ipojo/web/bootstrap/css/font-awesome.min.css" rel="stylesheet"> |
| <link href="/ipojo/web/style.css" rel="stylesheet"> |
| |
| <!-- Overide alert's colors --> |
| <link href="/ipojo/web/bootstrap/css/alert.css" rel="stylesheet"> |
| |
| <link rel="stylesheet" href="/ipojo/web/github.css" type="text/css" media="all"> |
| |
| |
| <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script> |
| <script src="/ipojo/web/bootstrap/js/bootstrap.min.js"></script> |
| |
| </head> |
| |
| <body data-spy="scroll" data-target=".subnav"> |
| <div class="navbar navbar-fixed-top navbar-inverse"> |
| <div class="navbar-inner"> |
| <div class="container"> |
| <a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse"> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| </a> |
| <a class="brand" href="/documentation/subprojects/apache-felix-ipojo.html">Apache Felix iPOJO</a> |
| |
| <div class="nav-collapse" id="main-menu"> |
| <ul class="nav" id="main-menu-left"> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/ipojo-news.html">News</a></li> |
| <li><a href="http://felix.apache.org/downloads.cgi">Downloads</a></li> |
| |
| <li class="dropdown"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">Tutorials <b class="caret"></b></a> |
| <ul class="dropdown-menu" id="tutorials-menu"> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-why-choose-ipojo.html">Why choose iPOJO</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-successstories.html">Success stories</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-feature-overview.html">Features</a></li> |
| <li class="divider"></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-in-10-minutes.html">iPOJO in 10 minutes</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/how-to-use-ipojo-annotations.html">Using Annotations</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-hello-word-maven-based-tutorial.html">Maven tutorial</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-advanced-tutorial.html">Advanced tutorial</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/apache-felix-ipojo-dosgi.html">Using Distributed OSGi</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-gettingstarted/ipojo-composition-tutorial.html">Application Composition</a></li> |
| </ul> |
| </li> |
| |
| <li class="dropdown"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">Documentation <b class="caret"></b></a> |
| <ul class="dropdown-menu" id="user-guide-menu"> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/service-requirement-handler.html">Requiring a service</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/providing-osgi-services.html">Providing a service</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/lifecycle-callback-handler.html">Lifecycle management</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/configuration-handler.html">Configuration</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/architecture-handler.html">Introspection</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/controller-lifecycle-handler.html">Impacting the lifecycle</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/injecting-bundle-context.html">Accessing the Bundle Context</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/apache-felix-ipojo-instances.html">Creating instances</a></li> |
| <li class="divider"></li> |
| <li class="dropdown-submenu"> |
| <a tabindex="-1" href="#">External <em>handlers</em></a> |
| <ul class="dropdown-menu"> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/event-admin-handlers.html">Asynchronous communication</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/ipojo-jmx-handler.html">JMX management</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/extender-pattern-handler.html">Extender pattern</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/white-board-pattern-handler.html">Whiteboard pattern</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/describing-components/temporal-service-dependency.html">Temporal dependencies</a></li> |
| </ul> |
| </li> |
| <li class="dropdown-submenu"> |
| <a tabindex="-1" href="#">Configuration Admin & Factories</a> |
| <ul class="dropdown-menu"> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/combining-ipojo-and-configuration-admin.html">iPOJO and config admin</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/ipojo-factory-service.html">Using the iPOJO Factory service</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/how-to-use-ipojo-factories.html">Factories and Instances</a></li> |
| </ul> |
| </li> |
| <li class="divider"></li> |
| <li class="dropdown-submenu"> |
| <a tabindex="-1" href="#">Advanced topics</a> |
| <ul class="dropdown-menu"> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/instance-vs-service-controller.html">Instance vs. Service Controllers</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/service-binding-interceptors.html">Service Binding Interceptors</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/using-xml-schemas.html">XML Schemas</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/apache-felix-ipojo-api.html">Using the iPOJO API</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/constructing-pojo-objects-with-factory-methods.html">Constructing service objects with factory methods</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/using-ipojo-introspection-api.html">Using the introspection API</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-testing-components.html">Testing components</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/using-stereotypes.html">Using @Stereotypes</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-eclipse-integration.html">Eclipse Integration</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/ipojo-extender-configuration.html">Configuring iPOJO's Extender</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-faq.html">FAQ</a></li> |
| <li class="divider"></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/how-to-write-your-own-handler.html">Handler development</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/how-to-use-ipojo-manipulation-metadata.html">Manipulation Metadata </a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-devguide/dive-into-the-ipojo-manipulation-depths.html">Dive into the iPOJO Manipulation depths</a></li> |
| <li><a href="http://felix.apache.org/ipojo/api/1.12.1">Javadoc</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| |
| <li class="dropdown" id="tools-menu"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">Tools <b class="caret"></b></a> |
| <ul class="dropdown-menu" id="swatch-menu"> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-ant-task.html">Ant Task</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-maven-plug-in.html">Maven Plugin</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-arch-command.html">Architecture commands</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/apache-felix-ipojo-online-manipulator.html">Online Manipulator</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-webconsole-plugin.html">Webconsole plugin</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-tools/ipojo-karaf-feature.html">Apache Karaf Features</a></li> |
| </ul> |
| </li> |
| |
| <li class="dropdown" id="community-menu"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">Community <b class="caret"></b></a> |
| <ul class="dropdown-menu" id="swatch-menu"> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/ipojo-support.html">Support</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> |
| |
| <li class="dropdown" id="misc-menu"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">Misc <b class="caret"></b></a> |
| <ul class="dropdown-menu" id="swatch-menu"> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-supportedvms.html">Supported JVMs</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-supportedosgi.html">Supported OSGi Implementations</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/articles-and-presentations.html">Article & Presentations</a></li> |
| <li><a href="/documentation/subprojects/apache-felix-ipojo/developing-camel-mediators-with-ipojo.html">Developping Camel mediators with iPOJO</a></li> |
| </ul> |
| </li> |
| </ul> |
| <ul class="nav pull-right" id="main-menu-right"> |
| <li><a rel="tooltip" target="_blank" href="http://felix.apache.org">Apache Felix <i class="icon-share-alt"></i></a></li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| |
| <div class="container"> |
| <div class="content"> |
| <style type="text/css"> |
| /* The following code is added by mdx_elementid.py |
| It was originally lifted from http://subversion.apache.org/style/site.css */ |
| /* |
| * Hide class="elementid-permalink", except when an enclosing heading |
| * has the :hover property. |
| */ |
| .headerlink, .elementid-permalink { |
| visibility: hidden; |
| } |
| h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink, h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink, dt:hover > .elementid-permalink { visibility: visible }</style> |
| <h1 id="how-to-use-ipojo-annotations">How to use iPOJO annotations<a class="headerlink" href="#how-to-use-ipojo-annotations" title="Permanent link">¶</a></h1> |
| <p><em>You can use annotations to define your component types. This page presents supported annotations.</em></p> |
| <div class="toc"> |
| <ul> |
| <li><a href="#how-to-use-ipojo-annotations">How to use iPOJO annotations</a><ul> |
| <li><a href="#getting-ipojo-annotations">Getting iPOJO Annotations:</a><ul> |
| <li><a href="#with-eclipse-or-any-other-ide">With Eclipse (or any other IDE)</a></li> |
| <li><a href="#with-maven">With Maven</a></li> |
| <li><a href="#with-ant">With Ant</a></li> |
| </ul> |
| </li> |
| <li><a href="#an-example-of-usage">An example of usage</a><ul> |
| <li><a href="#hello-service-provider">Hello Service Provider</a></li> |
| <li><a href="#hello-service-consumer">Hello Service Consumer</a></li> |
| </ul> |
| </li> |
| <li><a href="#defined-annotations">Defined Annotations</a><ul> |
| <li><a href="#component">@Component</a></li> |
| <li><a href="#provides">@Provides</a></li> |
| <li><a href="#requires">@Requires</a></li> |
| <li><a href="#serviceproperty">@ServiceProperty</a></li> |
| <li><a href="#servicecontroller">@ServiceController</a></li> |
| <li><a href="#property">@Property</a></li> |
| <li><a href="#updated">@Updated</a></li> |
| <li><a href="#bind">@Bind</a></li> |
| <li><a href="#unbind">@Unbind</a></li> |
| <li><a href="#modified">@Modified</a></li> |
| <li><a href="#validate">@Validate</a></li> |
| <li><a href="#invalidate">@Invalidate</a></li> |
| <li><a href="#postregistration">@PostRegistration</a></li> |
| <li><a href="#postunregistration">@PostUnregistration</a></li> |
| <li><a href="#instantiate">@Instantiate</a></li> |
| <li><a href="#temporal-dependencies-external-handler">Temporal Dependencies (external handler)</a></li> |
| <li><a href="#exposing-instances-as-a-jmx-mbean-external-handler">Exposing instances as a JMX MBean (external handler)</a></li> |
| </ul> |
| </li> |
| <li><a href="#advanced-topics-and-faq">Advanced topics and FAQ</a><ul> |
| <li><a href="#metadata-file-and-annotation-merge">Metadata file and annotation merge</a></li> |
| <li><a href="#instance-creation">Instance creation</a></li> |
| <li><a href="#using-custom-annotations">Using Custom Annotations</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </div> |
| <h2 id="getting-ipojo-annotations">Getting iPOJO Annotations:<a class="headerlink" href="#getting-ipojo-annotations" title="Permanent link">¶</a></h2> |
| <p>iPOJO Annotations are defines inside the <code>org.apache.felix.ipojo.annotations project</code>. You can download the Jar file of this project from the <a href="/documentation/subprojects/apache-felix-ipojo/download.html">download</a> page. Sources are available on the [Felix trunk|http://felix.apache.org/site/sourcecode.html]. |
| 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, and do <strong>not</strong> need to be deployed at runtime.</p> |
| <h3 id="with-eclipse-or-any-other-ide">With Eclipse (or any other IDE)<a class="headerlink" href="#with-eclipse-or-any-other-ide" title="Permanent link">¶</a></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 id="with-maven">With Maven<a class="headerlink" href="#with-maven" title="Permanent link">¶</a></h3> |
| <p>Add the following dependency:</p> |
| <div class="codehilite"><pre><span class="nt"><dependency></span> |
| <span class="nt"><groupId></span>org.apache.felix<span class="nt"></groupId></span> |
| <span class="nt"><artifactId></span>org.apache.felix.ipojo.annotations<span class="nt"></artifactId></span> |
| <span class="nt"><version></span>1.12.1<span class="nt"></version></span> |
| <span class="nt"></dependency></span> |
| </pre></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="codehilite"><pre><span class="nt"><plugin></span> |
| <span class="nt"><groupId></span>org.apache.maven.plugins<span class="nt"></groupId></span> |
| <span class="nt"><artifactId></span>maven-compiler-plugin<span class="nt"></artifactId></span> |
| <span class="nt"><configuration></span> |
| <span class="nt"><source></span>1.5<span class="nt"></source></span> |
| <span class="nt"><target></span>1.5<span class="nt"></target></span> |
| <span class="nt"></configuration></span> |
| <span class="nt"></plugin></span> |
| </pre></div> |
| |
| |
| <h3 id="with-ant">With Ant<a class="headerlink" href="#with-ant" title="Permanent link">¶</a></h3> |
| <p>Just add the org.apache.felix.ipojo.annotations jar file in your class path.</p> |
| <h2 id="an-example-of-usage">An example of usage<a class="headerlink" href="#an-example-of-usage" title="Permanent link">¶</a></h2> |
| <p>To illustrate annotations usage, let taking the tutorial example. In this tutorial, there are two components: |
| <em> The first one provides the hello service |
| </em> The second one uses the provided hello service |
| 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">here</a>.</p> |
| <h3 id="hello-service-provider">Hello Service Provider<a class="headerlink" href="#hello-service-provider" title="Permanent link">¶</a></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="codehilite"><pre><span class="kn">package</span> <span class="n">ipojo</span><span class="o">.</span><span class="na">example</span><span class="o">.</span><span class="na">hello</span><span class="o">.</span><span class="na">impl</span><span class="o">;</span> |
| |
| <span class="kn">import</span> <span class="nn">ipojo.example.hello.Hello</span><span class="o">;</span> |
| |
| <span class="kn">import</span> <span class="nn">org.apache.felix.ipojo.annotations.Component</span><span class="o">;</span> |
| <span class="kn">import</span> <span class="nn">org.apache.felix.ipojo.annotations.Provides</span><span class="o">;</span> |
| |
| <span class="cm">/**</span> |
| <span class="cm"> * Component implementing the Hello service.</span> |
| <span class="cm"> **/</span> |
| <span class="nd">@Component</span> |
| <span class="nd">@Provides</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">HelloImpl</span> <span class="kd">implements</span> <span class="n">Hello</span> <span class="o">{</span> |
| <span class="kd">public</span> <span class="n">String</span> <span class="nf">sayHello</span><span class="o">(</span><span class="n">String</span> <span class="n">name</span><span class="o">)</span> <span class="o">{</span> |
| <span class="k">return</span> <span class="s">"hello "</span> <span class="o">+</span> <span class="n">name</span><span class="o">;</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <h3 id="hello-service-consumer">Hello Service Consumer<a class="headerlink" href="#hello-service-consumer" title="Permanent link">¶</a></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. |
| 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="codehilite"><pre><span class="kn">package</span> <span class="n">ipojo</span><span class="o">.</span><span class="na">example</span><span class="o">.</span><span class="na">hello</span><span class="o">.</span><span class="na">client</span><span class="o">;</span> |
| |
| <span class="kn">import</span> <span class="nn">org.apache.felix.ipojo.annotations.Component</span><span class="o">;</span> |
| <span class="kn">import</span> <span class="nn">org.apache.felix.ipojo.annotations.Invalidate</span><span class="o">;</span> |
| <span class="kn">import</span> <span class="nn">org.apache.felix.ipojo.annotations.Requires</span><span class="o">;</span> |
| <span class="kn">import</span> <span class="nn">org.apache.felix.ipojo.annotations.Validate</span><span class="o">;</span> |
| |
| <span class="kn">import</span> <span class="nn">ipojo.example.hello.Hello</span><span class="o">;</span> |
| |
| <span class="nd">@Component</span><span class="o">(</span><span class="n">name</span><span class="o">=</span><span class="s">"AnnotatedHelloClient"</span><span class="o">,</span> <span class="n">immediate</span><span class="o">=</span><span class="kc">true</span><span class="o">)</span> |
| <span class="nd">@Instantiate</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">HelloClient</span> <span class="kd">implements</span> <span class="n">Runnable</span> <span class="o">{</span> |
| |
| <span class="nd">@Requires</span> |
| <span class="kd">private</span> <span class="n">Hello</span><span class="o">[]</span> <span class="n">m_hello</span><span class="o">;</span> |
| |
| <span class="kd">private</span> <span class="kd">final</span> <span class="kd">static</span> <span class="kt">int</span> <span class="n">DELAY</span><span class="o">=</span><span class="mi">10000</span><span class="o">;</span> |
| <span class="kd">private</span> <span class="kt">boolean</span> <span class="n">end</span><span class="o">;</span> |
| |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">run</span><span class="o">()</span> <span class="o">{</span> |
| <span class="k">while</span> <span class="o">(!</span><span class="n">end</span><span class="o">)</span> <span class="o">{</span> |
| <span class="k">try</span> <span class="o">{</span> |
| <span class="n">invoke</span><span class="o">();</span> |
| <span class="n">Thread</span><span class="o">.</span><span class="na">sleep</span><span class="o">(</span><span class="n">DELAY</span><span class="o">);</span> |
| <span class="o">}</span> <span class="k">catch</span> <span class="o">(</span><span class="n">InterruptedException</span> <span class="n">ie</span><span class="o">)</span> <span class="o">{</span> <span class="o">}</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">invoke</span><span class="o">()</span> <span class="o">{</span> |
| <span class="k">for</span> <span class="o">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="o">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">m_hello</span><span class="o">.</span><span class="na">length</span><span class="o">;</span> <span class="n">i</span><span class="o">++)</span> <span class="o">{</span> |
| <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="n">m_hello</span><span class="o">[</span><span class="n">i</span><span class="o">].</span> |
| <span class="n">sayHello</span><span class="o">(</span><span class="s">"iPOJO"</span><span class="o">));</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| |
| <span class="nd">@Validate</span> |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">starting</span><span class="o">()</span> <span class="o">{</span> |
| <span class="n">Thread</span> <span class="n">thread</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Thread</span><span class="o">(</span><span class="k">this</span><span class="o">);</span> |
| <span class="n">end</span> <span class="o">=</span> <span class="kc">false</span><span class="o">;</span> |
| <span class="n">thread</span><span class="o">.</span><span class="na">start</span><span class="o">();</span> |
| <span class="o">}</span> |
| |
| <span class="nd">@Invalidate</span> |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">stopping</span><span class="o">()</span> <span class="o">{</span> |
| <span class="n">end</span> <span class="o">=</span> <span class="kc">true</span><span class="o">;</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <h2 id="defined-annotations">Defined Annotations<a class="headerlink" href="#defined-annotations" title="Permanent link">¶</a></h2> |
| <p>This section lists defined annotations and how to use them.</p> |
| <h3 id="component">@Component<a class="headerlink" href="#component" title="Permanent link">¶</a></h3> |
| <p><em>Goal:</em> Defines a component type |
| <em>Target:</em> The component implementation class |
| <em>Attributes:</em></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>factoryMethod : 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>publicFactory : set if the component type is public. (optional, default = true). </li> |
| </ul> |
| <h3 id="provides">@Provides<a class="headerlink" href="#provides" title="Permanent link">¶</a></h3> |
| <p><em>Goal:</em> Defines that the component type provide services |
| <em>Target:</em> The component implementation class |
| <em>Attributes:</em></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> |
| <li>properties : array containing <code>@StaticServiceProperties</code> defining service properties not attached to fields.</li> |
| </ul> |
| <div class="alert alert-warning"> |
| <strong>OSGi Service Factory</strong> |
| <br/> |
| The <tt>SERVICE</tt> strategy refers to the OSGi service factory. So, one service object per asking bundle will be created. |
| </div> |
| |
| <h3 id="requires">@Requires<a class="headerlink" href="#requires" title="Permanent link">¶</a></h3> |
| <p><em>Goal:</em> Defines a service dependency |
| <em>Target:</em> Field, Constructor Parameter |
| <em>Attributes:</em></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 & 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>defaultimplementation: set the Default-Implmentation (optional, by default iPOJO uses a Null object)</li> |
| <li>exception : the class of the runtime exception to throw when no service providers are available </li> |
| <li>policy: defines the binding policy (optional)</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> |
| <li>timeout : the timeout ins millisecond to wait before applying the <em>no service action</em></li> |
| </ul> |
| <h3 id="serviceproperty">@ServiceProperty<a class="headerlink" href="#serviceproperty" title="Permanent link">¶</a></h3> |
| <p><em>Goal:</em> Defines a service property |
| <em>Target:</em> Field |
| <em>Attributes:</em></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="alert alert-warning"> |
| <strong>Mandatory property</strong> |
| <br/> |
| A mandatory property must receive a value either from the component type description (<tt>value</tt> attribute), or the instance configuration. |
| </div> |
| |
| <h3 id="servicecontroller">@ServiceController<a class="headerlink" href="#servicecontroller" title="Permanent link">¶</a></h3> |
| <p><em>Goal:</em> Control the service exposition |
| <em>Target:</em> Field (Boolean) |
| <em>Attributes:</em></p> |
| <ul> |
| <li>value : the default value. If set to false, it disables the initial exposition</li> |
| <li>specification : set the target of the controller, must be an exposed service interface. By default, the controller targets all services.</li> |
| </ul> |
| <h3 id="property">@Property<a class="headerlink" href="#property" title="Permanent link">¶</a></h3> |
| <p><em>Goal:</em> Defines a property |
| <em>Target:</em> Field, Method, Constructor Parameter |
| <em>Attributes:</em></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), the argument name for constructor injection)</li> |
| <li>value: property value (optional, default=no value)</li> |
| <li>mandatory : is the property mandatory? (optional, default=false)</li> |
| </ul> |
| <div class="alert alert-warning"> |
| <strong>Field, Method, Constructor</strong> |
| <br/> |
| If another property with the same name is defined, the method or field or constructor argument is added to the existing property. |
| </div> |
| |
| <h3 id="updated">@Updated<a class="headerlink" href="#updated" title="Permanent link">¶</a></h3> |
| <p><em>Goal:</em> Defines method called when a reconfiguration is completed. |
| <em>Target:</em> a method (receiving a dictionary in argument)</p> |
| <h3 id="bind">@Bind<a class="headerlink" href="#bind" title="Permanent link">¶</a></h3> |
| <p><em>Goal:</em> Defines a bind method |
| <em>Target:</em> Method |
| <em>Attributes:</em></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 (optional)</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 id="unbind">@Unbind<a class="headerlink" href="#unbind" title="Permanent link">¶</a></h3> |
| <p><em>Goal:</em> Defines an unbind method |
| <em>Target:</em> Method |
| <em>Attributes:</em></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 (optional)</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 id="modified">@Modified<a class="headerlink" href="#modified" title="Permanent link">¶</a></h3> |
| <p><em>Goal:</em> Defines an <code>modified</code> method, called when a bound service is udpated. |
| <em>Target:</em> Method |
| <em>Attributes:</em></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 (optional)</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 id="validate">@Validate<a class="headerlink" href="#validate" title="Permanent link">¶</a></h3> |
| <p><em>Goal:</em> defines a validate lifecycle callback |
| <em>Target:</em> method</p> |
| <h3 id="invalidate">@Invalidate<a class="headerlink" href="#invalidate" title="Permanent link">¶</a></h3> |
| <p><em>Goal:</em> defines a validate lifecycle callback |
| <em>Target:</em> method</p> |
| <h3 id="postregistration">@PostRegistration<a class="headerlink" href="#postregistration" title="Permanent link">¶</a></h3> |
| <p><em>Goal:</em> defines a callback invoked after service registration. The callback must have the following signature : <code>public void name(ServiceReference ref)</code> |
| <em>Target:</em> method</p> |
| <h3 id="postunregistration">@PostUnregistration<a class="headerlink" href="#postunregistration" title="Permanent link">¶</a></h3> |
| <p><em>Goal:</em> defines a callback invoked after service unregistration. The callback must have the following signature : <code>public void name(ServiceReference ref)</code> |
| <em>Target:</em> method</p> |
| <h3 id="instantiate">@Instantiate<a class="headerlink" href="#instantiate" title="Permanent link">¶</a></h3> |
| <p><em>Goal:</em> declare a simple instance (this is equivalent to <code><instance component="..."></instance></code> |
| <em>Target:</em> class |
| <em>Attribute:</em></p> |
| <ul> |
| <li>name: the instance name (optional)</li> |
| </ul> |
| <h3 id="temporal-dependencies-external-handler">Temporal Dependencies (external handler)<a class="headerlink" href="#temporal-dependencies-external-handler" title="Permanent link">¶</a></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. |
| The annotation is <code>org.apache.felix.ipojo.handler.temporal.Requires</code> and targets a field. |
| <em>Attributes:</em></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 id="exposing-instances-as-a-jmx-mbean-external-handler">Exposing instances as a JMX MBean (external handler)<a class="headerlink" href="#exposing-instances-as-a-jmx-mbean-external-handler" title="Permanent link">¶</a></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 <code>org.apache.felix.ipojo.handlers.jmx</code> package</p> |
| <p>The <code>@org.apache.felix.ipojo.handlers.jmx.Config</code> (<code>@Config</code> if the package it correctly imported) annotation is a type annotation (so placed on the <code>class</code> element. This annotation indicates that the instance will be exposed as an MBean. This annotation supports:</p> |
| <ul> |
| <li>usesMOSGi: set to <code>true</code> to use MOSGi. Otherwise, the MBean will be exposed in the MBean Platform Server (default: <code>false</code>).</li> |
| <li>objectname: set the MBean objectname. The objectname must follow JMX specification. (default: <code>package-name:factory-name:instance-name</code>)</li> |
| <li>domain: set the MBean domain. (default: <code>package-name</code>)</li> |
| <li>name: set the MBean name. (default: <code>instance-name</code>).</li> |
| </ul> |
| <p>The <code>@org.apache.felix.ipojo.handlers.jmx.Property</code> (<code>@Property</code>) 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 <code>r</code> (read only) and <code>w</code> (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 <code>@org.apache.felix.ipojo.handlers.jmx.Method</code> (<code>@Method</code>) 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 id="advanced-topics-and-faq">Advanced topics and FAQ<a class="headerlink" href="#advanced-topics-and-faq" title="Permanent link">¶</a></h2> |
| <h3 id="metadata-file-and-annotation-merge">Metadata file and annotation merge<a class="headerlink" href="#metadata-file-and-annotation-merge" title="Permanent link">¶</a></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 id="instance-creation">Instance creation<a class="headerlink" href="#instance-creation" title="Permanent link">¶</a></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="codehilite"><pre><span class="nt"><instance</span> <span class="na">component=</span><span class="s">"ipojo.example.hello.impl.HelloImpl"</span><span class="nt">/></span> |
| <span class="nt"><instance</span> <span class="na">component=</span><span class="s">"AnnotedHelloClient"</span><span class="nt">/></span> |
| </pre></div> |
| |
| |
| <h3 id="using-custom-annotations">Using Custom Annotations<a class="headerlink" href="#using-custom-annotations" title="Permanent link">¶</a></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.</p> |
| </div> |
| </div> |
| |
| <hr/> |
| |
| <div class="container"> |
| <footer id="footer"> |
| <div class="row"> |
| <div class="trademarkFooter span7"> |
| Apache Felix, Felix, Apache, the Apache feather logo, and the Apache Felix project |
| logo are trademarks of The Apache Software Foundation. All other marks mentioned |
| may be trademarks or registered trademarks of their respective owners. |
| </div> |
| <div class="timestamp span3 offset2"> |
| Rev. 1700393 by cziegeler on Tue, 1 Sep 2015 06:04:06 +0000 |
| </div> |
| </div> |
| </footer> |
| </div> |
| </body> |
| |
| <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> |
| |
| </html> |
