| <!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 - Service Requirement Handler</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="requiring-services">Requiring services<a class="headerlink" href="#requiring-services" title="Permanent link">¶</a></h1> |
| <p><em>One of the main iPOJO feature is the service injection. So, a component can consume a service without managing the service discovery, tracking and binding. iPOJO manages all these interactions and injects required service into the component. This page explains how to use services.</em></p> |
| <div class="toc"> |
| <ul> |
| <li><a href="#requiring-services">Requiring services</a><ul> |
| <li><a href="#service-dependency">Service Dependency</a><ul> |
| <li><a href="#whats-a-service-dependency">What's a service dependency?</a></li> |
| <li><a href="#dynamism-resilience-instance-lifecycle">Dynamism, Resilience & Instance Lifecycle</a></li> |
| </ul> |
| </li> |
| <li><a href="#service-requirement-injection-mechanisms">Service Requirement Injection Mechanisms</a><ul> |
| <li><a href="#field-injection">Field injection</a></li> |
| <li><a href="#method-invocation">Method invocation</a></li> |
| <li><a href="#using-constructor-injection-170-snapshot">Using constructor injection (1.7.0-SNAPSHOT)</a></li> |
| <li><a href="#mixing-injections-types">Mixing injections types</a></li> |
| <li><a href="#injection-mechanisms-lazy-object-creation">Injection mechanisms & lazy object creation</a></li> |
| </ul> |
| </li> |
| <li><a href="#examples">Examples</a><ul> |
| <li><a href="#simple-requirement">Simple Requirement</a></li> |
| <li><a href="#aggregate-requirement">Aggregate Requirement</a><ul> |
| <li><a href="#aggregate-dependency-with-field-injection">Aggregate Dependency with field injection</a></li> |
| <li><a href="#aggregate-dependency-with-field-injection-list-vector-collection-and-set">Aggregate Dependency with field injection: list, vector, collection and set</a></li> |
| <li><a href="#aggregate-dependency-with-callbacks">Aggregate Dependency with callbacks</a></li> |
| </ul> |
| </li> |
| <li><a href="#optional-requirement-scalar">Optional Requirement (Scalar)</a><ul> |
| <li><a href="#optional-requirement-with-field-injection">Optional Requirement with field injection</a></li> |
| <li><a href="#optional-dependency-with-callbacks-invocation">Optional Dependency with callbacks invocation</a></li> |
| </ul> |
| </li> |
| <li><a href="#aggregate-optional-requirement">Aggregate & Optional Requirement</a><ul> |
| <li><a href="#aggregate-optional-dependency-with-field-injection">Aggregate & Optional Dependency with field injection</a></li> |
| <li><a href="#aggregate-optional-requirement-with-callbacks">Aggregate & Optional Requirement with callbacks</a></li> |
| </ul> |
| </li> |
| <li><a href="#filtered-requirement">Filtered Requirement</a></li> |
| <li><a href="#targeting-a-specific-provider">Targeting a specific provider</a></li> |
| </ul> |
| </li> |
| <li><a href="#managing-resilience-to-dynamism-binding-policies">Managing resilience to dynamism - Binding Policies</a></li> |
| <li><a href="#optional-scalar-dependencies-no-service-actions">Optional Scalar Dependencies - No Service actions</a></li> |
| <li><a href="#wait-for-service-the-timeout-option">Wait for service : the timeout option</a></li> |
| <li><a href="#note-about-callbacks">Note about Callbacks</a></li> |
| <li><a href="#proxies">Proxies</a></li> |
| <li><a href="#note-on-service-interface-discovery">Note on service interface discovery</a></li> |
| </ul> |
| </li> |
| </ul> |
| </div> |
| <h2 id="service-dependency">Service Dependency<a class="headerlink" href="#service-dependency" title="Permanent link">¶</a></h2> |
| <h3 id="whats-a-service-dependency">What's a service dependency?<a class="headerlink" href="#whats-a-service-dependency" title="Permanent link">¶</a></h3> |
| <p>A required service is described by a service dependency. The dependency defines what kind of service is required, how to select the it, the resilience to its dynamism... iPOJO handles all these aspects for you, just tell, iPOJO tracks, selects, binds and injects the matching services directly in your code. Service dependencies can be:</p> |
| <ul> |
| <li>Scalar or Aggregate : the component can require one or several service providers</li> |
| <li>Mandatory or Optional : a component can declare an optional dependency, and defined what should be done when no services are available</li> |
| <li>Filtered : a component can filter available providers, and even choose a specific provider</li> |
| <li>Resilient to dynamism : iPOJO supports three binding policy depending on your reaction to dynamism</li> |
| </ul> |
| <h3 id="dynamism-resilience-instance-lifecycle">Dynamism, Resilience & Instance Lifecycle<a class="headerlink" href="#dynamism-resilience-instance-lifecycle" title="Permanent link">¶</a></h3> |
| <p>In OSGi™, services can appear and disappear dynamically. This implies dependencies can target a provider which can appear or disappear dynamically. So, dependencies need to manage this dynamism by tracking every time available services. At any moment, a dependency can be unresolved (i.e. no more provider can fulfill the requirement). In the case of a mandatory requirement, the instance becomes invalid (an invalid instance is no more accessible externally, for example provided services are unpublished). If a service, resolving the unfilled dependency appears, the instance becomes valid. In consequence, dependencies affect directly the instance state, and must manage correctly OSGi dynamism to allow a complete unloading when a service goes away. As soon a mandatory dependency cannot be fulfilled, the instance is invalidated.</p> |
| <p>By default, dependencies are managed dynamically (as previously explained). However, iPOJO supports two other types of binding policies:</p> |
| <ul> |
| <li>Static : if a bound service disappears, the instance is invalidated and cannot be revalidated (binding broken forever)</li> |
| <li>Dynamic-Priority: at each injection, the <em>best</em> provider is injected, or the providers array is sorted according to the OSGi Ranking policy or to a specified sorting algorithm.</li> |
| </ul> |
| <h2 id="service-requirement-injection-mechanisms">Service Requirement Injection Mechanisms<a class="headerlink" href="#service-requirement-injection-mechanisms" title="Permanent link">¶</a></h2> |
| <p>iPOJO support several types of injections:</p> |
| <p><strong>Field injection</strong>: a field contains the service object. As soon as the field is used, a consistent service object is injected. This injection type fully hides the dynamism</p> |
| <div class="codehilite"><pre><span class="nd">@Requires</span> |
| <span class="kd">private</span> <span class="n">LogService</span> <span class="n">log</span><span class="o">;</span> |
| </pre></div> |
| |
| |
| <p><strong>Method invocation</strong>: when a service appears, or disappears a method in the component is invoked. For each dependency, bind / unbind / modified methods are invoked to notify the component of the event.</p> |
| <div class="codehilite"><pre><span class="nd">@Bind</span> |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">bindLogService</span><span class="o">(</span><span class="n">LogService</span> <span class="n">log</span><span class="o">)</span> <span class="o">{</span> <span class="cm">/*...*/</span> <span class="o">}</span> |
| <span class="nd">@Unbind</span> |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">unbindLogService</span><span class="o">(</span><span class="n">LogService</span> <span class="n">log</span><span class="o">)</span> <span class="o">{</span> <span class="cm">/*...*/</span> <span class="o">}</span> |
| <span class="nd">@Modified</span> |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">modifiedLogService</span><span class="o">(</span><span class="n">LogService</span> <span class="n">log</span><span class="o">)</span> <span class="o">{</span> <span class="cm">/*...*/</span> <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p><strong>Constructor injection</strong>: services can also be injected as constructor parameter (only if proxies are enabled). <em>1.7.0-SNAPSHOT</em></p> |
| <div class="codehilite"><pre><span class="kd">public</span> <span class="nf">MyComponent</span><span class="o">(</span><span class="nd">@Requires</span> <span class="n">LogService</span> <span class="n">log</span><span class="o">)</span> <span class="o">{</span> <span class="cm">/*...*/</span> <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>Moreover, the injections types can be mixed. A component can declare a requirement containing both a field and 'binding' methods.</p> |
| <h3 id="field-injection">Field injection<a class="headerlink" href="#field-injection" title="Permanent link">¶</a></h3> |
| <p>Let's imagine a Hello service with one method 'getMessage' returning a "Hello Message". The following component implementation can use this service by attaching this service to a field and by using the field:</p> |
| <div class="codehilite"><pre><span class="nd">@Component</span> |
| <span class="nd">@Instantiate</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">HelloConsumer</span> <span class="o">{</span> |
| <span class="nd">@Requires</span> |
| <span class="kd">private</span> <span class="n">Hello</span> <span class="n">m_hello</span><span class="o">;</span> |
| |
| <span class="kd">public</span> <span class="nf">doSomething</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="na">getMesage</span><span class="o">());</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>You can also use XML to describe this component type:</p> |
| <div class="codehilite"><pre><span class="nt"><component</span> <span class="na">classname=</span><span class="s">"...HelloConsumer"</span><span class="nt">></span> |
| <span class="nt"><requires</span> <span class="na">field=</span><span class="s">"m_hello"</span><span class="nt">/></span> |
| ... |
| <span class="nt"></component></span> |
| </pre></div> |
| |
| |
| <p>The metadata contains a 'requires' element (representing the service dependency) and specify a field used to inject the service. The implementation uses the field as a normal field without managing service interactions.</p> |
| <h3 id="method-invocation">Method invocation<a class="headerlink" href="#method-invocation" title="Permanent link">¶</a></h3> |
| <p>The second injection mechanism uses methods in the implementation class. By this way, the dynamics can be managed directly by the developer. Each dependency can declare three methods:</p> |
| <ul> |
| <li>A bind method called when a service appears</li> |
| <li>An unbind method called when a service disappears</li> |
| <li>A modified method called when a service is modified (the service properties have changed, but the service still matches the requirement)</li> |
| </ul> |
| <p>Moreover, callbacks can be in the component super class (in this case methods must be public). These methods can have one of these signatures:</p> |
| <ul> |
| <li> |
| <p>Without any argument: the method is just a notification</p> |
| <div class="codehilite"><pre><span class="kd">public</span> <span class="kt">void</span> <span class="nf">bindService</span><span class="o">()</span> <span class="o">{</span> |
| <span class="c1">// ...</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| </li> |
| <li> |
| <p>With the service object: the object is the implicated service object. Service dependency type is inferred from the parameter's type.</p> |
| <div class="codehilite"><pre><span class="kd">public</span> <span class="kt">void</span> <span class="nf">bindService</span><span class="o">(</span><span class="n">HelloService</span> <span class="n">hello</span><span class="o">)</span> <span class="o">{</span> |
| <span class="n">m_hello</span> <span class="o">=</span> <span class="n">hello</span><span class="o">;</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| </li> |
| <li> |
| <p>With an OSGi service reference: the service reference appearing or disappearing.</p> |
| <div class="codehilite"><pre><span class="kd">public</span> <span class="kt">void</span> <span class="nf">bindService</span><span class="o">(</span><span class="n">ServiceReference</span><span class="o"><</span><span class="n">HelloService</span><span class="o">></span> <span class="n">reference</span><span class="o">)</span> <span class="o">{</span> |
| <span class="c1">// ...</span> |
| <span class="o">}</span> |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">bindService</span><span class="o">(</span><span class="n">ServiceReference</span> <span class="n">reference</span><span class="o">)</span> <span class="o">{</span> |
| <span class="c1">// ...</span> |
| <span class="o">}</span> |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">bindService</span><span class="o">(</span><span class="n">ServiceReference</span> <span class="n">reference</span><span class="o">)</span> <span class="o">{</span> |
| <span class="c1">// ...</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| </li> |
| <li> |
| <p>With the service object and the OSGi service reference.</p> |
| <div class="codehilite"><pre><span class="kd">public</span> <span class="kt">void</span> <span class="nf">bindService</span><span class="o">(</span><span class="n">HelloService</span> <span class="n">hello</span><span class="o">,</span> <span class="n">ServiceReference</span><span class="o"><</span><span class="n">HelloService</span><span class="o">></span> <span class="n">reference</span><span class="o">)</span> <span class="o">{</span> |
| <span class="c1">// ...</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| </li> |
| <li> |
| <p>With the service object and the service properties inside a Map (no adherence to OSGi APIs).</p> |
| <div class="codehilite"><pre><span class="kd">public</span> <span class="kt">void</span> <span class="nf">bindService</span><span class="o">(</span><span class="n">HelloService</span> <span class="n">hello</span><span class="o">,</span> <span class="n">Map</span><span class="o"><</span><span class="n">String</span><span class="o">,</span> <span class="n">Object</span><span class="o">></span> <span class="n">properties</span><span class="o">)</span> <span class="o">{</span> |
| <span class="c1">// ...</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| </li> |
| <li> |
| <p>With the service object and the service properties inside a Dictionary (no adherence to OSGi APIs).</p> |
| <div class="codehilite"><pre><span class="kd">public</span> <span class="kt">void</span> <span class="nf">bindService</span><span class="o">(</span><span class="n">HelloService</span> <span class="n">hello</span><span class="o">,</span> <span class="n">Dictionary</span><span class="o"><</span><span class="n">String</span><span class="o">,</span> <span class="n">Object</span><span class="o">></span> <span class="n">properties</span><span class="o">)</span> <span class="o">{</span> |
| <span class="c1">// ...</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| </li> |
| </ul> |
| <div class="alert alert-info info" markdown="1"> |
| <h4>Important</h4> |
| <p>Notice that, when missing (typically no interface can be inferred from the code) dependency information must be supplied to iPOJO in some way |
| <ul> |
| <li> <code>@Bind</code> with <code>specification</code> and/or <code>filter</code> attribute</li> |
| <li> Using XML metadata declaration</li> |
| </ul> |
| </p> |
| </div> |
| |
| <p>The following component implementation shows an example of implementation using this mechanism:</p> |
| <div class="codehilite"><pre><span class="nd">@Component</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">HelloConsumer</span> <span class="o">{</span> |
| <span class="kd">private</span> <span class="n">Hello</span> <span class="n">m_hello</span><span class="o">;</span> |
| |
| <span class="nd">@Bind</span> |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">bindHello</span><span class="o">(</span><span class="n">Hello</span> <span class="n">h</span><span class="o">)</span> <span class="o">{</span> <span class="n">m_hello</span> <span class="o">=</span> <span class="n">h</span><span class="o">;</span> <span class="o">}</span> |
| <span class="nd">@Unbind</span> |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">unbindHello</span><span class="o">()</span> <span class="o">{</span> <span class="n">m_hello</span> <span class="o">=</span> <span class="kc">null</span><span class="o">;</span> <span class="o">}</span> |
| <span class="kd">public</span> <span class="nf">doSomething</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="na">getMesage</span><span class="o">());</span> <span class="o">}</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>The <code>modified</code> callback is not mandatory. The following XML metadata are describing the same component type:</p> |
| <div class="codehilite"><pre><span class="nt"><component</span> <span class="na">classname=</span><span class="s">"...HelloConsumer"</span><span class="nt">></span> |
| <span class="nt"><requires></span> |
| <span class="nt"><callback</span> <span class="na">type=</span><span class="s">"bind"</span> <span class="na">method=</span><span class="s">"bindHello"</span><span class="nt">/></span> |
| <span class="nt"><callback</span> <span class="na">type=</span><span class="s">"unbind"</span> <span class="na">method=</span><span class="s">"unbindHello"</span><span class="nt">/></span> |
| <span class="nt"></requires></span> |
| ... |
| <span class="nt"></component></span> |
| </pre></div> |
| |
| |
| <p>Note, that the different callbacks can be have different signatures. By using this mechanism, you need to be sure to manage the dynamism correctly. |
| (<a href="#note-on-service-interface-discovery">See note on type discovery</a></p> |
| <p>Using the <code>@Modified</code> callback is also quite simple:</p> |
| <div class="codehilite"><pre><span class="nd">@Component</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">HelloConsumer</span> <span class="o">{</span> |
| <span class="kd">private</span> <span class="n">Hello</span> <span class="n">m_hello</span><span class="o">;</span> |
| |
| <span class="nd">@Bind</span> |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">bindHello</span><span class="o">(</span><span class="n">Hello</span> <span class="n">h</span><span class="o">)</span> <span class="o">{</span> <span class="n">m_hello</span> <span class="o">=</span> <span class="n">h</span><span class="o">;</span> <span class="o">}</span> |
| <span class="nd">@Unbind</span> |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">unbindHello</span><span class="o">()</span> <span class="o">{</span> <span class="n">m_hello</span> <span class="o">=</span> <span class="kc">null</span><span class="o">;</span> <span class="o">}</span> |
| <span class="nd">@Modified</span> |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">modifiedHello</span><span class="o">()</span> <span class="o">{</span> <span class="cm">/* ... */</span> <span class="o">}</span> |
| <span class="kd">public</span> <span class="nf">doSomething</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="na">getMesage</span><span class="o">());</span> <span class="o">}</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <h3 id="using-constructor-injection-170-snapshot">Using constructor injection (<em>1.7.0-SNAPSHOT</em>)<a class="headerlink" href="#using-constructor-injection-170-snapshot" title="Permanent link">¶</a></h3> |
| <p>Services can also be injected using constructor parameters:</p> |
| <div class="codehilite"><pre><span class="nd">@Component</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyComponent</span> <span class="o">{</span> |
| <span class="kd">private</span> <span class="n">LogService</span> <span class="n">log</span><span class="o">;</span> |
| |
| <span class="kd">public</span> <span class="nf">MyComponent</span><span class="o">(</span><span class="nd">@Requires</span> <span class="n">LogService</span> <span class="n">log</span><span class="o">)</span> <span class="o">{</span> |
| <span class="k">this</span><span class="o">.</span><span class="na">log</span> <span class="o">=</span> <span class="n">log</span><span class="o">;</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <h3 id="mixing-injections-types">Mixing injections types<a class="headerlink" href="#mixing-injections-types" title="Permanent link">¶</a></h3> |
| <p>The different mechanisms can be used together. In this case, the field receives the value before the bind method invocation. Constructor parameters get their values during the constructor invocation. So, if the field is used in the method, the returned value will be up to date. The following component implementation uses this mechanism:</p> |
| <div class="codehilite"><pre><span class="kd">public</span> <span class="kd">class</span> <span class="nc">HelloConsumer</span> <span class="o">{</span> |
| <span class="nd">@Requires</span><span class="o">(</span><span class="n">id</span><span class="o">=</span><span class="s">"hello"</span><span class="o">)</span> |
| <span class="kd">private</span> <span class="n">Hello</span> <span class="n">m_hello</span><span class="o">;</span> <span class="c1">// Injected Field</span> |
| |
| <span class="nd">@Bind</span><span class="o">(</span><span class="n">id</span><span class="o">=</span><span class="s">"hello"</span><span class="o">)</span> |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">bindHello</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="s">"Hello appears"</span><span class="o">);</span> <span class="o">}</span> |
| <span class="nd">@Unbind</span><span class="o">(</span><span class="n">id</span><span class="o">=</span><span class="s">"hello"</span><span class="o">)</span> |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">unbindHello</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="s">"Hello disapears"</span><span class="o">);</span> <span class="o">}</span> |
| |
| <span class="kd">public</span> <span class="nf">doSomething</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="na">getMesage</span><span class="o">());</span> <span class="o">}</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>In XML, it results in:</p> |
| <div class="codehilite"><pre><span class="nt"><component</span> <span class="na">classname=</span><span class="s">"...HelloConsumer"</span><span class="nt">></span> |
| <span class="nt"><requires</span> <span class="na">field=</span><span class="s">"m_hello"</span><span class="nt">></span> |
| <span class="nt"><callback</span> <span class="na">type=</span><span class="s">"bind"</span> <span class="na">method=</span><span class="s">"bindHello"</span><span class="nt">/></span> |
| <span class="nt"><callback</span> <span class="na">type=</span><span class="s">"unbind"</span> <span class="na">method=</span><span class="s">"unbindHello"</span><span class="nt">/></span> |
| <span class="nt"></requires></span> |
| ... |
| <span class="nt"></component></span> |
| </pre></div> |
| |
| |
| <p>The <code>id</code> attribute is used to determine which callbacks / fields go together. If ommitted, it is computed automaticcally:</p> |
| <ul> |
| <li>for field it uses the field type.</li> |
| <li>for method starting with <code>bind</code> / <code>unbind</code> / <code>modified</code>, it extract the end of the method name (<code>bindFoo => Foo</code>)</li> |
| <li>for constructor parameter, it uses the parameter index</li> |
| </ul> |
| <p>So, it is strongly recommended to specify the id manually. </p> |
| <h3 id="injection-mechanisms-lazy-object-creation">Injection mechanisms & lazy object creation<a class="headerlink" href="#injection-mechanisms-lazy-object-creation" title="Permanent link">¶</a></h3> |
| <p>iPOJO creates objects only when required. When needed, iPOJO invokes the constructor of the implementation class. The implementation class can use field requirement because values are already injected and obviously constructor parameters. However, method dependencies are called <em>after</em> the constructor. If the service is available before the constructor call, the invocation of the bind methods is delayed until the a component class object is created.</p> |
| <h2 id="examples">Examples<a class="headerlink" href="#examples" title="Permanent link">¶</a></h2> |
| <p>For all examples both annotations and XML forms are given. Just choose what you'd like to use.</p> |
| <h3 id="simple-requirement">Simple Requirement<a class="headerlink" href="#simple-requirement" title="Permanent link">¶</a></h3> |
| <p>By default, a requirement is mandatory, non-filtered and simple (non-aggregate). The previous examples illustrate this kind of dependency. When services goes away and appears, the service substitution is hidden. Fields attached to simple requirement point always a consistent service object. For a simple dependency, the bind method is called once time when the service appears or just after the POJO constructor invocation is the service is available. When the service disappears the unbind method is called. The bind method is re-invoked as soon as another service provider is available. This invocation occurs immediately if another service provider if available. In this case, the instance is not invalidated.</p> |
| <h3 id="aggregate-requirement">Aggregate Requirement<a class="headerlink" href="#aggregate-requirement" title="Permanent link">¶</a></h3> |
| <p>When a component requires several providers of the same service, it declares an aggregate dependency.</p> |
| <h4 id="aggregate-dependency-with-field-injection">Aggregate Dependency with field injection<a class="headerlink" href="#aggregate-dependency-with-field-injection" title="Permanent link">¶</a></h4> |
| <div class="codehilite"><pre><span class="nd">@Component</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">HelloConsumer</span> <span class="o">{</span> |
| <span class="nd">@Requires</span> |
| <span class="kd">private</span> <span class="n">Hello</span> <span class="n">m_hellos</span><span class="o">[];</span> <span class="c1">// Array => Aggregate</span> |
| <span class="kd">public</span> <span class="nf">doSomething</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_hellos</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_hellos</span><span class="o">[</span><span class="n">i</span><span class="o">].</span><span class="na">getMessage</span><span class="o">());</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>For this component, XML metadata could be:</p> |
| <div class="codehilite"><pre><span class="nt"><component</span> <span class="na">classname=</span><span class="s">"...HelloConsumer"</span><span class="nt">></span> |
| <span class="nt"><requires</span> <span class="na">field=</span><span class="s">"m_hellos"</span><span class="nt">/></span> |
| ... |
| <span class="nt"></component></span> |
| </pre></div> |
| |
| |
| <p>To declare an aggregate field for field requirement, you only need to declare an array (instead of a scalar type). iPOJO will create and inject the service object array. iPOJO discover that the dependency is aggregate during the bytecode introspection.</p> |
| <p>Array types cannot be 'proxied'. Moreover array dependencies cannot be injected as constructor parameter.</p> |
| <div class="alert alert-info info" markdown="1"> |
| <h4>Synchronization</h4> |
| <p>The synchronization is managed by iPOJO. As soon as you are 'touching' a dependency in a method, iPOJO ensure that you will keep these objects until the end of the method. Nested methods will share the same service object set.</p> |
| </div> |
| |
| <h4 id="aggregate-dependency-with-field-injection-list-vector-collection-and-set">Aggregate Dependency with field injection: list, vector, collection and set<a class="headerlink" href="#aggregate-dependency-with-field-injection-list-vector-collection-and-set" title="Permanent link">¶</a></h4> |
| <p>It is also possible to inject service objects inside fields of the type:</p> |
| <ul> |
| <li>list</li> |
| <li>vector</li> |
| <li>collection</li> |
| <li> |
| <p>set</p> |
| <p>:::java |
| @Component |
| public class HelloConsumer { |
| @Requires(specification="org.apache.felix.ipojo.example.Hello") |
| private List<Hello> m_hellos; |
| public doSomething() { |
| for(Hello h : m_hellos) { |
| System.out.println(h).getMessage()); |
| } |
| } |
| }</p> |
| </li> |
| </ul> |
| <p>For this component, XML metadata could be:</p> |
| <div class="codehilite"><pre><span class="nt"><component</span> <span class="na">classname=</span><span class="s">"...HelloConsumer"</span><span class="nt">></span> |
| <span class="nt"><requires</span> <span class="na">field=</span><span class="s">"m_hellos"</span> <span class="na">specification=</span><span class="s">"org.apache.felix.ipojo.example.Hello"</span><span class="nt">/></span> |
| ... |
| <span class="nt"></component></span> |
| </pre></div> |
| |
| |
| <p>In this case, just use the supported type that you want. iPOJO will automatically understand that it is an aggregate dependency, and will create the collection object containing service objects. However, you must specify the service specification. Indeed, generics types cannot be discovered at runtime reliably. </p> |
| <div class="alert alert-info info" markdown="1"> |
| <h4>Service specification discovery</h4> |
| <p>The service specification (i.e. interface) cannot be discovered when using these types as the bytecode does not provide enough information. So, you have to indicate the required service interface (with the 'specification' attribute) in the requirement description.</p> |
| </div> |
| |
| <div class="alert alert-info info" markdown="1"> |
| <h4>How iPOJO manage the synchronization for you</h4> |
| <p>As in the previous case, the synchronization is managed by iPOJO. As soon as you are *touching* a dependency in a method, iPOJO ensure that you will keep these objects until the end of the method. Nested methods will share the same service object set.</p> |
| </div> |
| |
| <h4 id="aggregate-dependency-with-callbacks">Aggregate Dependency with callbacks<a class="headerlink" href="#aggregate-dependency-with-callbacks" title="Permanent link">¶</a></h4> |
| <div class="codehilite"><pre><span class="kd">public</span> <span class="kd">class</span> <span class="nc">HelloConsumer</span> <span class="o">{</span> |
| <span class="kd">private</span> <span class="n">List</span> <span class="n">m_hellos</span> <span class="o">=</span> <span class="k">new</span> <span class="n">ArrayList</span><span class="o">();</span> |
| <span class="nd">@Bind</span><span class="o">(</span><span class="n">aggregate</span><span class="o">=</span><span class="kc">true</span><span class="o">)</span> |
| <span class="kd">private</span> <span class="kt">void</span> <span class="nf">bindHello</span><span class="o">(</span><span class="n">Hello</span> <span class="n">h</span><span class="o">)</span> <span class="o">{</span> <span class="n">m_hellos</span><span class="o">.</span><span class="na">add</span><span class="o">(</span><span class="n">h</span><span class="o">);</span> <span class="o">}</span> |
| <span class="nd">@Unbind</span> |
| <span class="kd">private</span> <span class="kt">void</span> <span class="nf">unbindHello</span><span class="o">(</span><span class="n">Hello</span> <span class="n">h</span><span class="o">)</span> <span class="o">{</span> <span class="n">m_hellos</span><span class="o">.</span><span class="na">remove</span><span class="o">(</span><span class="n">h</span><span class="o">);</span> <span class="o">}</span> |
| <span class="kd">public</span> <span class="kd">synchronized</span> <span class="nf">doSomething</span><span class="o">()</span> <span class="o">{</span> |
| <span class="k">for</span><span class="o">(</span><span class="n">Hello</span> <span class="n">h</span> <span class="o">:</span> <span class="n">m_hellos</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">h</span><span class="o">.</span><span class="na">getMessage</span><span class="o">());</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>This dependency can also be described in XML as follow:</p> |
| <div class="codehilite"><pre><span class="nt"><requires</span> <span class="na">aggregate=</span><span class="s">"true"</span><span class="nt">></span> |
| <span class="nt"><callback</span> <span class="na">type=</span><span class="s">"bind"</span> <span class="na">method=</span><span class="s">"bindHello"</span><span class="nt">/></span> |
| <span class="nt"><callback</span> <span class="na">type=</span><span class="s">"unbind"</span> <span class="na">method=</span><span class="s">"unbindHello"</span><span class="nt">/></span> |
| <span class="nt"></requires></span> |
| </pre></div> |
| |
| |
| <p>In this case, iPOJO cannot detect if the dependency is aggregate or not. So, you need to add the '<em>aggregate</em>' attribute. The bindHello and unbindHello will be called each time a Hello service appears or disappears.</p> |
| <div class="alert alert-info info" markdown="1"> |
| <h4>Synchronization</h4> |
| <p>To avoid the list modification during the loop, you need synchronized the block. Indeed, as the field is not an iPOJO requirement, iPOJO will not manage the synchronization.</p> |
| </div> |
| |
| <h3 id="optional-requirement-scalar">Optional Requirement (Scalar)<a class="headerlink" href="#optional-requirement-scalar" title="Permanent link">¶</a></h3> |
| <p>An optional requirement does not invalidate the instance despite no providers are available. Moreover, it is possible to inject a default service implementation when no <em>real</em> providers are available.</p> |
| <h4 id="optional-requirement-with-field-injection">Optional Requirement with field injection<a class="headerlink" href="#optional-requirement-with-field-injection" title="Permanent link">¶</a></h4> |
| <div class="codehilite"><pre><span class="nd">@Component</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">HelloConsumer</span> <span class="o">{</span> |
| <span class="nd">@Requires</span><span class="o">(</span><span class="n">optional</span><span class="o">=</span><span class="kc">true</span><span class="o">)</span> |
| <span class="kd">private</span> <span class="n">Hello</span> <span class="n">m_hello</span><span class="o">;</span> |
| |
| <span class="kd">public</span> <span class="nf">doSomething</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="na">getMesage</span><span class="o">());</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>For this component, equivalent XML metadata could be:</p> |
| <div class="codehilite"><pre><span class="nt"><component</span> <span class="na">classname=</span><span class="s">"...HelloConsumer"</span><span class="nt">></span> |
| <span class="nt"><requires</span> <span class="na">field=</span><span class="s">"m_hello"</span> <span class="na">optional=</span><span class="s">"true"</span><span class="nt">/></span> |
| ... |
| <span class="nt"></component></span> |
| </pre></div> |
| |
| |
| <p>To declare an optional requirement, you need to add the <em>'optional'</em> attribute. To avoid <code>null</code> pointer exception, iPOJO injects a <code>Nullable</code> object in the field when no service provider is available. The <em>nullable</em> object implements the service interface, but does nothing. Moreover, it is possible to set a <em>default-implementation</em> for the service. A default-implementation is a class implementing the service but used only when no others service providers are available. The default-implementation object will be injected instead of the <em>Nullable</em> objet. For further information <a href="#note-about-nullable-object-default-implementation">refer to the note about nullable object</a>.</p> |
| <h4 id="optional-dependency-with-callbacks-invocation">Optional Dependency with callbacks invocation<a class="headerlink" href="#optional-dependency-with-callbacks-invocation" title="Permanent link">¶</a></h4> |
| <div class="codehilite"><pre><span class="nd">@Component</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">HelloConsumer</span> <span class="o">{</span> |
| <span class="kd">private</span> <span class="n">Hello</span> <span class="n">m_hello</span><span class="o">;</span> |
| |
| <span class="nd">@Bind</span><span class="o">(</span><span class="n">optional</span><span class="o">=</span><span class="kc">true</span><span class="o">)</span> |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">bindHello</span><span class="o">(</span><span class="n">Hello</span> <span class="n">h</span><span class="o">)</span> <span class="o">{</span> <span class="n">m_hello</span> <span class="o">=</span> <span class="n">h</span><span class="o">;</span> <span class="o">}</span> |
| |
| <span class="nd">@Unbind</span> |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">unbindHello</span><span class="o">()</span> <span class="o">{</span> <span class="n">m_hello</span> <span class="o">=</span> <span class="kc">null</span><span class="o">;</span> <span class="o">}</span> |
| |
| <span class="kd">public</span> <span class="nf">doSomething</span><span class="o">()</span> <span class="o">{</span> |
| <span class="k">if</span><span class="o">(</span><span class="n">m_hello</span> <span class="o">!=</span> <span class="kc">null</span><span class="o">)</span> <span class="o">{</span> <span class="c1">// Must be checked</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="na">getMesage</span><span class="o">());</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>For this component, XML metadata could be:</p> |
| <div class="codehilite"><pre><span class="nt"><component</span> <span class="na">classname=</span><span class="s">"...HelloConsumer"</span><span class="nt">></span> |
| <span class="nt"><requires</span> <span class="na">optional=</span><span class="s">"true"</span><span class="nt">></span> |
| <span class="nt"><callback</span> <span class="na">type=</span><span class="s">"bind"</span> <span class="na">method=</span><span class="s">"bindHello"</span><span class="nt">/></span> |
| <span class="nt"><callback</span> <span class="na">type=</span><span class="s">"unbind"</span> <span class="na">method=</span><span class="s">"unbindHello"</span><span class="nt">/></span> |
| <span class="nt"></requires></span> |
| ... |
| <span class="nt"></component></span> |
| </pre></div> |
| |
| |
| <p>As for field requirement, the dependency metadata needs to contain the optional attribute. iPOJO invokes the method only when a 'real' service is available, so you need to test if <code>m_hello</code> is <code>null</code> before to use it.</p> |
| <h3 id="aggregate-optional-requirement">Aggregate & Optional Requirement<a class="headerlink" href="#aggregate-optional-requirement" title="Permanent link">¶</a></h3> |
| <p>A dependency can be both aggregate and optional.</p> |
| <h4 id="aggregate-optional-dependency-with-field-injection">Aggregate & Optional Dependency with field injection<a class="headerlink" href="#aggregate-optional-dependency-with-field-injection" title="Permanent link">¶</a></h4> |
| <div class="codehilite"><pre><span class="nd">@Component</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">HelloConsumer</span> <span class="o">{</span> |
| <span class="nd">@Requires</span><span class="o">(</span><span class="n">optional</span><span class="o">=</span><span class="kc">true</span><span class="o">)</span> |
| <span class="kd">private</span> <span class="n">Hello</span> <span class="n">m_hellos</span><span class="o">[];</span> |
| |
| <span class="kd">public</span> <span class="nf">doSomething</span><span class="o">()</span> <span class="o">{</span> |
| <span class="k">for</span><span class="o">(</span><span class="n">Hello</span> <span class="n">h</span> <span class="o">:</span> <span class="n">m_hellos</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">h</span><span class="o">.</span><span class="na">getMessage</span><span class="o">());</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>For this component, XML metadata could be:</p> |
| <div class="codehilite"><pre><span class="nt"><component</span> <span class="na">classname=</span><span class="s">"...HelloConsumer"</span><span class="nt">></span> |
| <span class="nt"><requires</span> <span class="na">field=</span><span class="s">"m_hellos"</span> <span class="na">optional=</span><span class="s">"true"</span><span class="nt">/></span> |
| ... |
| <span class="nt"></component></span> |
| </pre></div> |
| |
| |
| <p>To declare an optional & aggregate field requirement you need to write the optional attribute in the dependency metadata and to point on a field array. If no service available, iPOJO injects an empty array.</p> |
| <h4 id="aggregate-optional-requirement-with-callbacks">Aggregate & Optional Requirement with callbacks<a class="headerlink" href="#aggregate-optional-requirement-with-callbacks" title="Permanent link">¶</a></h4> |
| <div class="codehilite"><pre><span class="nd">@Component</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">HelloConsumer</span> <span class="o">{</span> |
| |
| <span class="kd">private</span> <span class="n">List</span> <span class="n">m_hellos</span><span class="o"><</span><span class="n">Hello</span><span class="o">></span> <span class="o">=</span> <span class="k">new</span> <span class="n">ArrayList</span><span class="o"><</span><span class="n">Hello</span><span class="o">>();</span> |
| |
| <span class="nd">@Bind</span><span class="o">(</span><span class="n">aggregate</span><span class="o">=</span><span class="kc">true</span><span class="o">,</span> <span class="n">optional</span><span class="o">=</span><span class="kc">true</span><span class="o">)</span> |
| <span class="kd">private</span> <span class="kt">void</span> <span class="nf">bindHello</span><span class="o">(</span><span class="n">Hello</span> <span class="n">h</span><span class="o">)</span> <span class="o">{</span> <span class="n">m_hellos</span><span class="o">.</span><span class="na">add</span><span class="o">(</span><span class="n">h</span><span class="o">);</span> <span class="o">}</span> |
| |
| <span class="nd">@Unbind</span> |
| <span class="kd">private</span> <span class="kt">void</span> <span class="nf">unbindHello</span><span class="o">(</span><span class="n">Hello</span> <span class="n">h</span><span class="o">)</span> <span class="o">{</span> <span class="n">m_hellos</span><span class="o">.</span><span class="na">remove</span><span class="o">(</span><span class="n">h</span><span class="o">);</span> <span class="o">}</span> |
| |
| <span class="kd">public</span> <span class="kd">synchronized</span> <span class="nf">doSomething</span><span class="o">()</span> <span class="o">{</span> |
| <span class="k">for</span><span class="o">(</span><span class="n">Hello</span> <span class="n">h</span> <span class="o">:</span> <span class="n">m_hellos</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">h</span><span class="o">.</span><span class="na">getMessage</span><span class="o">());</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>For this component, XML metadata could be:</p> |
| <div class="codehilite"><pre><span class="nt"><requires</span> <span class="na">aggregate=</span><span class="s">"true"</span> <span class="na">optional=</span><span class="s">"true"</span><span class="nt">></span> |
| <span class="nt"><callback</span> <span class="na">type=</span><span class="s">"bind"</span> <span class="na">method=</span><span class="s">"bindHello"</span><span class="nt">/></span> |
| <span class="nt"><callback</span> <span class="na">type=</span><span class="s">"unbind"</span> <span class="na">method=</span><span class="s">"unbindHello"</span><span class="nt">/></span> |
| <span class="nt"></requires></span> |
| </pre></div> |
| |
| |
| <p>In this case, you need to add the <em>'aggregate'</em> attribute and the <em>'optional'</em>attribute. The <code>bindHello</code> and <code>unbindHello</code> will be called each time a Hello service appears or disappears. These bind / unbind methods are not called when binding / unbinding a Nullable object (when both field and method are used).</p> |
| <h3 id="filtered-requirement">Filtered Requirement<a class="headerlink" href="#filtered-requirement" title="Permanent link">¶</a></h3> |
| <p>A filtered dependency applies an LDAP filter on service provider. iPOJO reuses OSGi LDAP filter ability. The following metadata illustrates how to use filters:</p> |
| <div class="codehilite"><pre><span class="nd">@Requires</span><span class="o">(</span><span class="n">filter</span><span class="o">=</span><span class="s">"(language=fr)"</span><span class="o">)</span> |
| <span class="kd">private</span> <span class="n">String</span> <span class="n">DictionaryService</span> <span class="n">dict</span><span class="o">;</span> |
| </pre></div> |
| |
| |
| <p> </p> |
| <div class="codehilite"><pre><span class="nt"><requires</span> <span class="na">filter=</span><span class="s">"(language=fr)"</span> <span class="na">field=</span><span class="s">"dict"</span><span class="nt">/></span> |
| </pre></div> |
| |
| |
| <p>To add a filter, just add a 'filter' attribute in your dependency containing the LDAP filter. iPOJO will select only provider matching with this filter.</p> |
| <p>When using a filter, you can also use the <code>modified</code> callback invoked when a matching service is <em>modified</em> but still matches the filter:</p> |
| <div class="codehilite"><pre><span class="nd">@Component</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyComponent</span> <span class="o">{</span> |
| |
| <span class="nd">@Bind</span><span class="o">(</span><span class="n">filter</span><span class="o">=</span><span class="s">"(langage=en)"</span><span class="o">)</span> |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">bindHDictionary</span><span class="o">(</span><span class="n">DictionaryService</span> <span class="n">svc</span><span class="o">)</span> <span class="o">{</span> <span class="o">...</span> <span class="o">}</span> |
| |
| <span class="nd">@Unbind</span> |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">unbindDictionary</span><span class="o">()</span> <span class="o">{</span> <span class="o">...}</span> |
| |
| <span class="nd">@Modified</span> |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">modifiedDictionary</span><span class="o">()</span> <span class="o">{</span> <span class="o">...</span> <span class="o">}</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>Moreover, filters can be customized instance by instance. It is possible to specialize / change / add the filter of a component in the instance description. It is useful when you want to create different instances of the same component, with different filter. To achieve this customization, you have to identify your dependency with the 'id' attribute. Then, you can adapt the filter of the dependency in the instance description by using the property "requires.filters". In this property you can specify each dependency identified by its id and the new value of the filter.</p> |
| <div class="codehilite"><pre><span class="nt"><component</span> |
| <span class="na">className=</span><span class="s">"org.apache.felix.ipojo.example.FilteredDependency"</span><span class="nt">></span> |
| <span class="nt"><requires</span> <span class="na">field=</span><span class="s">"m_foo"</span> <span class="na">fiter=</span><span class="s">"(foo.property=FOO)"</span> <span class="na">id=</span><span class="s">"id1"</span><span class="nt">></span> |
| <span class="nt"><callback</span> <span class="na">type=</span><span class="s">"bind"</span> <span class="na">method=</span><span class="s">"bind"</span><span class="nt">/></span> |
| <span class="nt"><callback</span> <span class="na">type=</span><span class="s">"unbind"</span> <span class="na">method=</span><span class="s">"unbind"</span><span class="nt">/></span> |
| <span class="nt"></requires></span> |
| <span class="nt"></component></span> |
| |
| <span class="nt"><instance</span> <span class="na">name=</span><span class="s">"FOO1"</span> <span class="na">component=</span><span class="s">"FOO"</span><span class="nt">/></span> |
| |
| <span class="nt"><instance</span> <span class="na">name=</span><span class="s">"FOO2"</span> <span class="na">component=</span><span class="s">"FOO"</span><span class="nt">></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"requires.filters"</span><span class="nt">></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"id1"</span> <span class="na">value=</span><span class="s">"(foo.property=BAR)"</span><span class="nt">/></span> |
| <span class="nt"></property></span> |
| <span class="nt"></instance></span> |
| |
| <span class="nt"><instance</span> <span class="na">name=</span><span class="s">"FOO3"</span> <span class="na">component=</span><span class="s">"FOO"</span><span class="nt">></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"requires.filters"</span><span class="nt">></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"id1"</span> <span class="na">value=</span><span class="s">"(foo.property=BAZ)"</span><span class="nt">/></span> |
| <span class="nt"></property></span> |
| <span class="nt"></instance></span> |
| </pre></div> |
| |
| |
| <p>The component type declares a service dependency with the 'id1' id. This dependency has no filter by default. The first instance is just an instance of the FOO component type and does not modify the dependency. The second one adds a filter to the declared dependency to target providers with foo.property = BAR. The last one adds another filter to the declared dependency. By using instance filter customization, it is possible to create complex applications where you avoid binding problems by filtering dependencies instance by instance.</p> |
| <h3 id="targeting-a-specific-provider">Targeting a specific provider<a class="headerlink" href="#targeting-a-specific-provider" title="Permanent link">¶</a></h3> |
| <p>A service dependency can choose a specific provider. To achieve this, add a 'from' attribute in your requirement description such as in:</p> |
| <div class="codehilite"><pre><span class="nd">@Requires</span><span class="o">(</span><span class="n">from</span><span class="o">=</span><span class="s">"MyHelloProvider"</span><span class="o">)</span> |
| <span class="kd">private</span> <span class="n">Hello</span> <span class="n">m_hello</span><span class="o">;</span> |
| </pre></div> |
| |
| |
| <p>or in XML:</p> |
| <div class="codehilite"><pre><span class="nt"><requires</span> <span class="na">from=</span><span class="s">"MyHelloProvider"</span> <span class="na">field=</span><span class="s">"m_hello"</span><span class="nt">/></span> |
| </pre></div> |
| |
| |
| <p>iPOJO maps the <code>from</code> attribute to a specific filter : <code>|(instance.name=MyHelloProvider)(service.pid=MyHelloProvider)</code>. Then the dependency can only be fulfilled by a service matching this filter.</p> |
| <p>Moreover, from attributes can be customized instance by instance. It is possible to specialize / change / add a 'from' attribute of a component in the instance configuration. It is useful when you want to create different instances of the same component, with different 'from' clauses. To do it, you have to identify your dependency with an 'id' attribute. Then, you can adapt the 'from' of the dependency in the instance configuration by using the property "requires.from". In this property you can specify each dependency identified by its id and the 'from' value.</p> |
| <div class="codehilite"><pre><span class="nt"><component</span> |
| <span class="na">className=</span><span class="s">"org.apache.felix.ipojo.example.FilteredDependency"</span> |
| <span class="na">name=</span><span class="s">"FOO"</span><span class="nt">></span> |
| <span class="nt"><requires</span> <span class="na">field=</span><span class="s">"m_foo"</span> <span class="na">id=</span><span class="s">"id1"</span><span class="nt">></span> |
| <span class="nt"><callback</span> <span class="na">type=</span><span class="s">"bind"</span> <span class="na">method=</span><span class="s">"bind"</span><span class="nt">/></span> |
| <span class="nt"><callback</span> <span class="na">type=</span><span class="s">"unbind"</span> <span class="na">method=</span><span class="s">"unbind"</span><span class="nt">/></span> |
| <span class="nt"></requires></span> |
| <span class="nt"></component></span> |
| |
| <span class="nt"><instance</span> <span class="na">name=</span><span class="s">"FOO1"</span> <span class="na">component=</span><span class="s">"FOO"</span><span class="nt">/></span> |
| |
| <span class="nt"><instance</span> <span class="na">name=</span><span class="s">"FOO2"</span> <span class="na">component=</span><span class="s">"FOO"</span><span class="nt">></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"requires.from"</span><span class="nt">></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"id1"</span> <span class="na">value=</span><span class="s">"myprovider"</span><span class="nt">/></span> |
| <span class="nt"></property></span> |
| <span class="nt"></instance></span> |
| |
| <span class="nt"><instance</span> <span class="na">name=</span><span class="s">"FOO3"</span> <span class="na">component=</span><span class="s">"FOO"</span><span class="nt">></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"requires.from"</span><span class="nt">></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"id1"</span> <span class="na">value=</span><span class="s">"myotherprovider"</span><span class="nt">/></span> |
| <span class="nt"></property></span> |
| <span class="nt"></instance></span> |
| </pre></div> |
| |
| |
| <p>The FOO component type declares a service dependency with the 'id1' id. This dependency has no 'from' attribute by default. The first instance is just an instance of the FOO component type and does not modify the dependency. The second one adds a 'from' attribute to the declared dependency to target the 'myprovider' provider. The last one adds another 'from' clause to the declared dependency.</p> |
| <h2 id="managing-resilience-to-dynamism-binding-policies">Managing resilience to dynamism - Binding Policies<a class="headerlink" href="#managing-resilience-to-dynamism-binding-policies" title="Permanent link">¶</a></h2> |
| <p>Three binding policies are supported inside iPOJO.</p> |
| <ul> |
| <li>Dynamic policy (default): the binding are managed dynamically. At each injection, the same provider is injected if the provider is always available. Else a new one is chosen. For aggregate dependency, the array order does not change; new providers are placed at the end of the array.</li> |
| <li>Static policy: the binding is static. So, once bound a provider cannot disappear. If it disappears, the instance is invalidated and cannot be revalidated without stopping and restarting the instance.</li> |
| <li>Dynamic-priority policy: the binding is managed dynamically but the injected provider is selected by using a ranking policy. Two injections can return two different providers, is a new provider is 'better' than the previous one, despite the first one is always available. For aggregate dependency, the array is sorted.</li> |
| </ul> |
| <p>A static binding is declared as following:</p> |
| <div class="codehilite"><pre><span class="nd">@Requires</span><span class="o">(</span><span class="n">policy</span><span class="o">=</span><span class="n">BindingPolicy</span><span class="o">.</span><span class="na">STATIC</span><span class="o">)</span> |
| <span class="kd">private</span> <span class="n">Hello</span><span class="o">[]</span> <span class="n">m_hellos</span><span class="o">;</span> |
| </pre></div> |
| |
| |
| <p>or</p> |
| <div class="codehilite"><pre><span class="nt"><requires</span> <span class="na">field=</span><span class="s">"m_hellos"</span> <span class="na">policy=</span><span class="s">"static"</span><span class="nt">/></span> |
| </pre></div> |
| |
| |
| <p>A dynamic-priority binding is declared as following:</p> |
| <div class="codehilite"><pre><span class="nd">@Requires</span><span class="o">(</span><span class="n">policy</span><span class="o">=</span><span class="n">BindingPolicy</span><span class="o">.</span><span class="na">DYNAMIC_PRIORITY</span><span class="o">)</span> |
| <span class="kd">private</span> <span class="n">Hello</span><span class="o">[]</span> <span class="n">m_hellos</span><span class="o">;</span> |
| </pre></div> |
| |
| |
| <p>or</p> |
| <div class="codehilite"><pre><span class="nt"><requires</span> <span class="na">field=</span><span class="s">"m_hellos"</span> <span class="na">policy=</span><span class="s">"dynamic-priority"</span><span class="nt">/></span> |
| </pre></div> |
| |
| |
| <p>By default, the dynamic-priority policy uses the OSGi service ranking policy. However, it is possible to customize the policy by adding the '<em>comparator</em>' attribute. This attribute indicates the class name of a class implementing the <code>java.util.Comparator</code> interface. iPOJO creates an instance of your comparator and uses it to sort service references (so your customized comparator needs to be able to sort OSGi Service Reference).</p> |
| <div class="codehilite"><pre><span class="nd">@Requires</span><span class="o">(</span><span class="n">policy</span><span class="o">=</span><span class="n">BindingPolicy</span><span class="o">.</span><span class="na">DYNAMIC_PRIORITY</span><span class="o">,</span> <span class="n">comparator</span><span class="o">=</span><span class="n">MyComparator</span><span class="o">.</span><span class="na">class</span><span class="o">)</span> |
| <span class="kd">private</span> <span class="n">Hello</span><span class="o">[]</span> <span class="n">m_hellos</span><span class="o">;</span> |
| </pre></div> |
| |
| |
| <p>or</p> |
| <div class="codehilite"><pre><span class="nt"><requires</span> <span class="na">field=</span><span class="s">"m_hellos"</span> <span class="na">policy=</span><span class="s">"dynamic-priority"</span> <span class="na">comparator=</span><span class="s">"great.MyComparator"</span><span class="nt">/></span> |
| </pre></div> |
| |
| |
| <h2 id="optional-scalar-dependencies-no-service-actions">Optional Scalar Dependencies - No Service actions<a class="headerlink" href="#optional-scalar-dependencies-no-service-actions" title="Permanent link">¶</a></h2> |
| <p>When using optional dependencies a special case needs to be handled for field and contructor injection: what happen when there are no service providers available. By default, iPOJO uses <code>nullable</code> objects. It has the advantage to not require any additional code. However, iPOJO supports other options:</p> |
| <ul> |
| <li><code>null</code> : injects <code>null</code> instead of a nullable object, it requires <code>null</code> check before using the inject service</li> |
| <li><code>default-implementation</code> : injects a specific implementation of the service that you provide. It must implement the same service interface.</li> |
| <li><code>exception</code> : throws a runtime exception (that you specify), it requires a <code>try-catch</code> block for specific management.</li> |
| </ul> |
| <p>By default, scalar optional dependencies injects a <code>nullable</code> object, i.e. a mock implementing the service interface but does not implement any behavior. A nullable object returns:</p> |
| <ul> |
| <li><code>null</code> when the method returns an object</li> |
| <li><code>0</code> when the method returns an int, log, byte, short, char, float or a double</li> |
| <li><code>false</code> when the method return a boolean</li> |
| </ul> |
| <p>To inject <code>null</code> instead of a <code>nullable</code> object, just set the <code>nullable</code> attribute to <code>false</code>. </p> |
| <div class="codehilite"><pre><span class="nd">@Requires</span><span class="o">(</span><span class="n">optional</span><span class="o">=</span><span class="kc">true</span><span class="o">,</span> <span class="n">nullable</span><span class="o">=</span><span class="kc">false</span><span class="o">)</span> |
| <span class="kd">private</span> <span class="n">LogService</span> <span class="n">m_log</span><span class="o">;</span> |
| </pre></div> |
| |
| |
| <p>or</p> |
| <div class="codehilite"><pre> <span class="nt"><requires</span> <span class="na">field=</span><span class="s">"m_log"</span> <span class="na">optional=</span><span class="s">"true"</span> <span class="na">nullable=</span><span class="s">"false"</span><span class="nt">/></span> |
| </pre></div> |
| |
| |
| <p>However be aware that in this case, you must check for <code>null</code> before using the service:</p> |
| <div class="codehilite"><pre><span class="k">if</span> <span class="o">(</span><span class="n">m_log</span> <span class="o">!=</span> <span class="kc">null</span><span class="o">)</span> <span class="o">{</span> |
| <span class="n">m_log</span><span class="o">.</span><span class="na">log</span><span class="o">(</span><span class="n">LogService</span><span class="o">.</span><span class="na">INFO</span><span class="o">,</span> <span class="s">"an important message"</span><span class="o">);</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>Don't worry about the synchronization, iPOJO keep the injected object consistent on the entire method flow.</p> |
| <p>Sometimes you need to customize the behavior when a service is not available. You can do this directly in your code, but this can be very cumbersome. <code>default-implementation</code> let you inject a fake service when no providers are present. It's like a <code>nullable</code> object, but you can implement your own behavior. The given class <em>MUST</em> implement the required service interface.</p> |
| <p>For example, the following component uses a <code>default-implementation</code> for a Log Service dependency:</p> |
| <div class="codehilite"><pre><span class="nd">@Requires</span><span class="o">(</span><span class="n">optional</span><span class="o">=</span><span class="kc">true</span><span class="o">,</span> <span class="k">default</span><span class="o">-</span><span class="n">implementation</span><span class="o">=</span><span class="n">MyLogService</span><span class="o">.</span><span class="na">class</span><span class="o">)</span> |
| <span class="kd">private</span> <span class="n">LogService</span> <span class="n">m_log</span><span class="o">;</span> |
| </pre></div> |
| |
| |
| <p>or </p> |
| <div class="codehilite"><pre><span class="nt"><requires</span> <span class="na">field=</span><span class="s">"m_log"</span> <span class="na">optional=</span><span class="s">"true"</span> |
| <span class="na">default-implementation=</span> |
| <span class="s">"org.apache.felix.ipojo.example.default.MyLogService"</span><span class="nt">/></span> |
| </pre></div> |
| |
| |
| <p>If the log service is not available, iPOJO creates an instance of the <code>org.apache.felix.ipojo.example.default.MyLogService</code>. This object is injected instead of the <code>Nullable</code> object. In the example, the default implementation can print messages on the <code>System.err</code>. In comparison, the <code>nullable</code> object would have done nothing.</p> |
| <p>Finally, you can also instructs iPOJO to throw a runtime exception when there are no service providers available. This option is often use in combination with the <code>timeout</code> option, that delay the decision. To throw an exception, use the <code>exception</code> attribute specifying the exception class to use. It must be a subclass of <code>RuntimeException</code>. Obvisouly, you can use <code>java.lang.RuntimeException</code> directly.</p> |
| <div class="codehilite"><pre><span class="nd">@Requires</span><span class="o">(</span><span class="n">optional</span><span class="o">=</span><span class="kc">true</span><span class="o">,</span> <span class="n">exception</span><span class="o">=</span><span class="n">NoServiceException</span><span class="o">.</span><span class="na">class</span><span class="o">)</span> |
| <span class="kd">private</span> <span class="n">LogService</span> <span class="n">m_log</span><span class="o">;</span> |
| </pre></div> |
| |
| |
| <p>or </p> |
| <div class="codehilite"><pre><span class="nt"><requires</span> <span class="na">field=</span><span class="s">"m_log"</span> <span class="na">optional=</span><span class="s">"true"</span> |
| <span class="na">exception=</span> |
| <span class="s">"org.apache.felix.ipojo.example.default.NoServiceException"</span><span class="nt">/></span> |
| </pre></div> |
| |
| |
| <h2 id="wait-for-service-the-timeout-option">Wait for service : the timeout option<a class="headerlink" href="#wait-for-service-the-timeout-option" title="Permanent link">¶</a></h2> |
| <p>For scalar optional dependencies injected inside fields or constructors, you may want to wait for a service to arrive before injecting a <em>stub</em> (<code>nullable</code>, <code>null</code>, <code>default-implementation</code> or <code>exception</code>). The <code>timeout</code> attribute let you specify the amount of time (in milliseconds) to wait. If there are still no services available when the timeout is reached, then the no service action is applied.</p> |
| <p>In the following example, the <code>AuthenticationService</code> is essential, but also may be subjected to updates. When the service is not there, you don't want to fail immediately, but give it a chance to re-appear <em>soon</em>:</p> |
| <div class="codehilite"><pre><span class="nd">@Requires</span><span class="o">(</span><span class="n">optional</span><span class="o">=</span><span class="kc">true</span><span class="o">,</span> <span class="n">exception</span><span class="o">=</span><span class="n">UpdateInProgessException</span><span class="o">.</span><span class="na">class</span><span class="o">,</span> <span class="n">timeout</span><span class="o">=</span><span class="mi">1000</span><span class="o">)</span> |
| <span class="kd">private</span> <span class="n">AuthenticationService</span> <span class="n">m_auth</span><span class="o">;</span> |
| </pre></div> |
| |
| |
| <h2 id="note-about-callbacks">Note about Callbacks<a class="headerlink" href="#note-about-callbacks" title="Permanent link">¶</a></h2> |
| <p>Dependency manages two type of callback: bind and unbind. A callback with a type "bind" is called each type that a service provider arrives and the binding is necessary. According to the cardinality of the dependency it means:</p> |
| <ul> |
| <li>Simple dependency : at the firs binding and at each rebinding to another service provider</li> |
| <li>Aggregate dependencies: each time that a service provider arrives</li> |
| </ul> |
| <p>An unbind callback is called each time that a <em>used</em> service provider goes away. For a simple dependency this method is called each time that the used service provider goes away. For a multiple dependency this method is called each time that a service provider goes away.</p> |
| <p>The method can receive in argument the service object or the service reference (in order to obtain service properties). The bind methods are delayed since a POJO object is created.</p> |
| <h2 id="proxies">Proxies<a class="headerlink" href="#proxies" title="Permanent link">¶</a></h2> |
| <p>Since iPOJO 1.6, iPOJO injects proxy objects. Those proxies are by default smart proxies and are design to be lightweight:</p> |
| <ul> |
| <li>for scalar requirement : the service object is a proxy</li> |
| <li>for aggregate dependencies : iPOJO injects a smart collections</li> |
| </ul> |
| <p>The goal of the proxies is to hide the dynamism and more particularly the dynamism. So, you can gives a service dependency to another object, using the service object still supports the dynamism. For collections, you can iterate over the collection without managing the potential departures and arrivals of services. The proxy also manage that the component class and the delegate objects shared the same services is they are accessed in the same Thread.</p> |
| <p>By default iPOJO injects proxy except for arrays. Moreover, it is possible to disable the proxy injection by adding <code>proxy=false</code> to the <code>requires</code> element (or to the <code>@Requires</code> and <code>@Bind</code> annotations). It is also possible to inject dynamic proxies (if the platform does not support dynamically generated classes). To enable dynamic proxies, set the system or bundle property <code>ipojo.proxy.type</code> to <code>dynamic-proxy</code>. You can also disable completely the proxy injection by setting the system property <code>ipojo.proxy</code> to <code>disabled</code>.</p> |
| <h2 id="note-on-service-interface-discovery">Note on service interface discovery<a class="headerlink" href="#note-on-service-interface-discovery" title="Permanent link">¶</a></h2> |
| <p>The <code>specification</code> attribute is generally optional except when iPOJO cannot discover the type of the service. iPOJO cannot deduce the servce specification when the dependency has no field and callbacks do not receive the service object in parameters. In this case, you must the service specification (i.e. interface).</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> |
