| <!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 - Providing OSGi services</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="providing-osgi-services">Providing OSGi services<a class="headerlink" href="#providing-osgi-services" title="Permanent link">¶</a></h1> |
| <p><em>This pages explains how to publish OSGi services with iPOJO. It presents:</em></p> |
| <ul> |
| <li><em>service publication</em></li> |
| <li><em>service properties publication and management</em></li> |
| <li><em>service object creation and creation strategies</em></li> |
| <li><em>service un-registration</em></li> |
| <li><em>configuration property propagation</em></li> |
| <li><em>the management of the exposition from the implementation class</em></li> |
| </ul> |
| <div class="toc"> |
| <ul> |
| <li><a href="#providing-osgi-services">Providing OSGi services</a><ul> |
| <li><a href="#a-simple-example">A simple example</a></li> |
| <li><a href="#service-publication">Service Publication</a></li> |
| <li><a href="#service-properties">Service Properties</a></li> |
| <li><a href="#advanced-features">Advanced features</a><ul> |
| <li><a href="#service-serving-object-creation">Service Serving & Object Creation</a></li> |
| <li><a href="#providing-several-services-xml-only">Providing Several Services (XML only)</a></li> |
| <li><a href="#service-property-propagation">Service Property Propagation</a></li> |
| <li><a href="#instance-reconfiguration">Instance reconfiguration</a></li> |
| <li><a href="#publishing-an-abstract-or-concrete-class-as-a-service">Publishing an abstract or concrete class as a Service</a></li> |
| <li><a href="#controlling-the-service-exposition-from-the-implementation-class">Controlling the service exposition from the implementation class</a></li> |
| <li><a href="#being-notified-of-the-service-registration-and-unregistration">Being notified of the service registration and unregistration</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </div> |
| <h2 id="a-simple-example">A simple example<a class="headerlink" href="#a-simple-example" title="Permanent link">¶</a></h2> |
| <p>The following code snippet shows a simple class implementing the <code>FooService</code> interface:</p> |
| <div class="codehilite"><pre><span class="nd">@Component</span> |
| <span class="nd">@Provides</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">FooProviderType1</span> <span class="kd">implements</span> <span class="n">FooService</span> <span class="o">{</span> |
| <span class="kd">private</span> <span class="n">String</span> <span class="n">m_foo</span> <span class="o">=</span> <span class="s">"foo"</span><span class="o">;</span> |
| |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">foo</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">"foo "</span> <span class="o">+</span> <span class="n">m_foo</span><span class="o">);</span> |
| <span class="o">}</span> |
| |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>To provide a service, the implementation class <em>MUST</em> implement the service interface. </p> |
| <p>In XML, to provide the service, the component type needs to contain the <code><provides/></code> element:</p> |
| <div class="codehilite"><pre><span class="nt"><component</span> <span class="na">className=</span><span class="s">"...FooProviderType1"</span><span class="nt">></span> |
| <span class="nt"><provides/></span> |
| <span class="nt"></component></span> |
| </pre></div> |
| |
| |
| <p><img src="ps-foo.png"></p> |
| <p>The <code><provides/></code> or <code>@Provides</code> suffice to declare that each instance of this type will provide the FooService (for more info about instances see '<a href="/documentation/subprojects/apache-felix-ipojo/apache-felix-ipojo-userguide/ipojo-advanced-topics/how-to-use-ipojo-factories.html">How to use iPOJO factories</a>`). The provided specifications can be discovered by analyzing the implementation class. By default, all implemented interface are published in the same service registration. iPOJO looks down the entire inheritance tree.</p> |
| <h2 id="service-publication">Service Publication<a class="headerlink" href="#service-publication" title="Permanent link">¶</a></h2> |
| <p>The provided service handler manages service publication. For each declared <code><provides/></code>, the handler registers a service. Since the <code>@Provides</code> annotation can be used only once, only one service is registered that provides all interfaces. The service is published as long as the instance is valid. If the instance becomes invalid, the service is removed from the service registry.</p> |
| <p>By default, it publishes all interfaces implemented by the implementation class of the component class. It collects all super-interfaces (interfaces implemented by implemented interfaces and by the super class). However, it is possible to explicitly declare which service specifications are published with the <code>specifications</code> attribute, such as:</p> |
| <div class="codehilite"><pre><span class="nd">@Component</span> |
| <span class="nd">@Provides</span><span class="o">(</span><span class="n">specifications</span><span class="o">={</span><span class="n">FooService</span><span class="o">.</span><span class="na">class</span><span class="o">})</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">FooProviderType1</span> <span class="kd">implements</span> <span class="n">FooService</span><span class="o">,</span> <span class="n">Runnable</span> <span class="o">{</span> |
| <span class="c1">// ...</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <div class="alert alert-warning info"> |
| <h4>Specification checking</h4> |
| <p>If you use the <code>specifications</code> attribute, the handler checks that all declared interfaces are really implemented by the implementation class. If an interface is not implemented, the handler logs a warning.</p> |
| </div> |
| |
| <div class="alert alert-warning info"> |
| <h4>No service</h4> |
| <p>If the implementation class does not implement any interface, you cannot provide a service. In this case, the handler throws an error.</p> |
| </div> |
| |
| <h2 id="service-properties">Service Properties<a class="headerlink" href="#service-properties" title="Permanent link">¶</a></h2> |
| <p>You can also attach properties to a service registration. Service properties are attached to published service and allow consumer filtering/selecting providers. A property can be attached to a field (contained in the component implementation class), and so can be handle dynamically.</p> |
| <p>Let's take a new example very closed of the last one:</p> |
| <div class="codehilite"><pre><span class="nd">@Component</span> |
| <span class="nd">@Provides</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">FooProviderType1</span> <span class="kd">implements</span> <span class="n">FooService</span> <span class="o">{</span> |
| |
| <span class="nd">@ServiceProperty</span><span class="o">(</span><span class="n">name</span><span class="o">=</span><span class="s">"foo"</span><span class="o">,</span> <span class="n">value</span><span class="o">=</span><span class="s">"Foo"</span><span class="o">)</span> |
| <span class="kd">private</span> <span class="n">String</span> <span class="n">m_foo</span><span class="o">;</span> |
| |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">foo</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">"foo "</span> <span class="o">+</span> <span class="n">m_foo</span><span class="o">);</span> |
| <span class="n">m_foo</span> <span class="o">=</span> <span class="s">"bar"</span><span class="o">;</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>Using XML, it gives:</p> |
| <div class="codehilite"><pre><span class="nt"><component</span> <span class="na">classname=</span><span class="s">"...FooProviderType1"</span><span class="nt">></span> |
| <span class="nt"><provides></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"foo"</span> <span class="na">field=</span><span class="s">"m_foo"</span> <span class="na">value=</span><span class="s">"Foo"</span><span class="nt">/></span> |
| <span class="nt"></provides></span> |
| <span class="nt"></component></span> |
| </pre></div> |
| |
| |
| <p>The declared property is attached to the <code>m_foo</code> field. This property is published with the name <code>foo</code>. This property has a default value "Foo". This value will be injected into the <code>m*foo</code> field, when this field asks for a value. A property with a field attribute does not need to declare a type (the type can be discovered by analyzing the implementation class).</p> |
| <p>The implementation class set a new value to the <code>m_foo</code> field in the code. When this action occurs, the service publication is updated. If a published property value becomes <code>null</code>, the property is unpublished since it has a new value.</p> |
| <p>You can also publish 'static' properties (not attached to a field):</p> |
| <div class="codehilite"><pre><span class="nd">@Component</span> |
| <span class="nd">@Provides</span><span class="o">(</span><span class="n">properties</span><span class="o">=</span> <span class="o">{</span> |
| <span class="nd">@StaticServiceProperty</span><span class="o">(</span><span class="n">name</span><span class="o">=</span><span class="s">"static"</span><span class="o">,</span> <span class="n">type</span><span class="o">=</span><span class="s">"java.lang.String"</span><span class="o">,</span> <span class="n">value</span><span class="o">=</span><span class="s">"this is a static property"</span><span class="o">)</span> |
| <span class="o">})</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">FooProviderType1</span> <span class="kd">implements</span> <span class="n">FooService</span> <span class="o">{</span> |
| |
| <span class="nd">@ServiceProperty</span><span class="o">(</span><span class="n">name</span><span class="o">=</span><span class="s">"foo"</span><span class="o">,</span> <span class="n">value</span><span class="o">=</span><span class="s">"Foo"</span><span class="o">)</span> |
| <span class="kd">private</span> <span class="n">String</span> <span class="n">m_foo</span><span class="o">;</span> |
| |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">foo</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">"foo "</span> <span class="o">+</span> <span class="n">m_foo</span><span class="o">);</span> |
| <span class="n">m_foo</span> <span class="o">=</span> <span class="s">"bar"</span><span class="o">;</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>The second property (<code>Static</code>) is published as a static property. This property is not attached to a field, so, we need to declare the property type. All primitive types or objects can be used has property type (for object, the qualified name of the class is used as java.lang.String).</p> |
| <p>In XML, this can also be done:</p> |
| <div class="codehilite"><pre><span class="nt"><component</span> <span class="na">classname=</span><span class="s">"...FooProviderType1"</span><span class="nt">></span> |
| <span class="nt"><provides></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"foo"</span> <span class="na">field=</span><span class="s">"m_foo"</span> <span class="na">value=</span><span class="s">"Foo"</span><span class="nt">/></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"static"</span> <span class="na">type=</span><span class="s">"java.lang.String"</span> <span class="na">value=</span><span class="s">"this is a static property"</span><span class="nt">/></span> |
| <span class="nt"></provides></span> |
| <span class="nt"></component></span> |
| </pre></div> |
| |
| |
| <p>Properties may have a default value (set using the <code>value</code> attribute). This value will be used as initial value. The value can be given in the instance configuration. The default value will be overridden in this case:</p> |
| <div class="codehilite"><pre><span class="nt"><instance</span> <span class="na">component=</span><span class="s">"...FooProviderType1"</span><span class="nt">></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"foo"</span> <span class="na">value=</span><span class="s">"My New Foo Value"</span><span class="nt">/></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"static"</span> <span class="na">value=</span><span class="s">"My Value For Static"</span><span class="nt">/></span> |
| <span class="nt"></instance></span> |
| </pre></div> |
| |
| |
| <p>Properties can also be 'mandatory'. Mandatories properties must receive a value from the instance configuration. If the instance configuration <em>forgets</em> a mandatory properties, the configuration is rejected. Mandatory attribute let you be sure to receive the complete set of initialization values:</p> |
| <div class="codehilite"><pre><span class="nd">@Component</span> |
| <span class="nd">@Provides</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyComponent</span> <span class="kd">implements</span> <span class="n">MyService</span> <span class="o">{</span> |
| |
| <span class="nd">@ServiceProperty</span><span class="o">(</span><span class="n">name</span><span class="o">=</span><span class="s">"username"</span><span class="o">,</span> <span class="n">mandatory</span><span class="o">=</span><span class="kc">true</span><span class="o">)</span> |
| <span class="kd">private</span> <span class="n">String</span> <span class="n">m_username</span><span class="o">;</span> |
| |
| <span class="nd">@Property</span><span class="o">(</span><span class="n">name</span><span class="o">=</span><span class="s">"password"</span><span class="o">,</span> <span class="n">mandatory</span><span class="o">=</span><span class="kc">true</span><span class="o">)</span> |
| <span class="kd">private</span> <span class="n">String</span> <span class="n">m_password</span><span class="o">;</span> |
| |
| <span class="c1">//...</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>For the previous components:</p> |
| <ul> |
| <li><code>(name=myname, password=****)</code> is a valid configuration</li> |
| <li><code>(password=****)</code> is an invalid configuration that will be rejected by iPOJO</li> |
| </ul> |
| <h2 id="advanced-features">Advanced features<a class="headerlink" href="#advanced-features" title="Permanent link">¶</a></h2> |
| <h3 id="service-serving-object-creation">Service Serving & Object Creation<a class="headerlink" href="#service-serving-object-creation" title="Permanent link">¶</a></h3> |
| <p>When a consumer requires the published service, the handler sends an object (from the component class) of the implementation class. By default, it is always the same POJO object. If no objects already exists, an instance is created.</p> |
| <p>However, the handler supports the OSGi <em>Service Factory</em>. In this case, for each requester bundle, the handler sends a new object. To activate this policy, add the <code>strategy</code> attribute in the <code>provides</code> element:</p> |
| <div class="codehilite"><pre><span class="nd">@Component</span> |
| <span class="nd">@Provides</span><span class="o">(</span><span class="n">strategy</span><span class="o">=</span><span class="s">"SERVICE"</span><span class="o">)</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyComponent</span> <span class="kd">implements</span> <span class="n">MyService</span> <span class="o">{</span> |
| <span class="c1">//...</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>or:</p> |
| <div class="codehilite"><pre><span class="nt"><provides</span> <span class="na">strategy=</span><span class="s">"SERVICE"</span><span class="nt">/></span> |
| </pre></div> |
| |
| |
| <p>Other strategies are available: |
| * <code>strategy="instance"</code> allows creating one service object per iPOJO instance using the service |
| * it is possible to create your own creation strategy by extending the <code>org.apache.felix.ipojo.handlers.providedservice.CreationStrategy</code> class and by indicating the qualified class name in the <code>strategy</code> attribute:</p> |
| <div class="codehilite"><pre><span class="nd">@Component</span> |
| <span class="nd">@Provides</span><span class="o">(</span><span class="n">strategy</span><span class="o">=</span><span class="s">"org.acme.foo.MyCreationStrategy"</span><span class="o">)</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyComponent</span> <span class="kd">implements</span> <span class="n">MyService</span> <span class="o">{</span> |
| <span class="c1">//...</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <h3 id="providing-several-services-xml-only">Providing Several Services (XML only)<a class="headerlink" href="#providing-several-services-xml-only" title="Permanent link">¶</a></h3> |
| <p>In XML, you can declare several <code>provides</code> inside the same component. All those provided services will be managed individually, so will be published using several publication (i.e. <code>org.osgi.frameowrk.ServiceRegistration</code>). This case is useful when service properties are different for the different services.</p> |
| <div class="codehilite"><pre><span class="nt"><component</span> <span class="na">classname=</span><span class="s">"...FooProviderType1"</span><span class="nt">></span> |
| <span class="nt"><provides</span> <span class="na">specifications=</span><span class="s">"...Foo"</span><span class="nt">/></span> |
| <span class="nt"><provides</span> <span class="na">specifications=</span><span class="s">"...Bar"</span><span class="nt">></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"foo"</span> <span class="na">value=</span><span class="s">"baz"</span><span class="nt">/></span> |
| <span class="nt"></provides></span> |
| <span class="nt"></component></span> |
| </pre></div> |
| |
| |
| <p><img src="ps-foobar2.png"></p> |
| <h3 id="service-property-propagation">Service Property Propagation<a class="headerlink" href="#service-property-propagation" title="Permanent link">¶</a></h3> |
| <p>The configuration handler has the possibility to propagate received properties to service publication. So, when the propagation is activated (on the <code>properties</code> element or on the <code>@Component</code> annotation), all properties received by the configuration handler will be propagated to all published services. If some properties are mapped on methods, these methods are invoked with the new value in argument.</p> |
| <p><img src="ps-propagation.png"></p> |
| <p>If an instance configuration contains properties starting with <code>service.</code>, they are automatically propagated. In the following example, the <code>service.pid</code> is automatically propagated.</p> |
| <div class="codehilite"><pre><span class="nt"><instance</span> <span class="na">component=</span><span class="s">"..."</span><span class="nt">></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"service.pid"</span> <span class="na">value=</span><span class="s">"my.pid"</span><span class="nt">/></span> |
| <span class="nt"></instance></span> |
| </pre></div> |
| |
| |
| <h3 id="instance-reconfiguration">Instance reconfiguration<a class="headerlink" href="#instance-reconfiguration" title="Permanent link">¶</a></h3> |
| <p>iPOJO supports instance reconfiguration. When an instance is dynamically reconfigured and if the instance published service properties, the values are updated with the new configuration. For example, let's take the following component.</p> |
| <div class="codehilite"><pre><span class="nd">@Component</span> |
| <span class="nd">@Instantiate</span> |
| <span class="nd">@Provides</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyComponent</span> <span class="kd">implements</span> <span class="n">MyService</span> <span class="o">{</span> |
| |
| <span class="nd">@ServiceProperty</span><span class="o">(</span><span class="n">name</span><span class="o">=</span><span class="s">"prop"</span><span class="o">,</span> <span class="n">value</span><span class="o">=</span><span class="s">"initial"</span><span class="o">)</span> |
| <span class="kd">private</span> <span class="n">String</span> <span class="n">myProp</span><span class="o">;</span> |
| |
| <span class="c1">//...</span> |
| |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>The previous code also declares an instance (created without any configuration). This instance registers <code>MyService</code> with the service property <code>prop=initial</code>. If this instance is reconfigured using a configuration like: <code>{prop="my value"}</code>, the published properties will be updated with the new value, so <code>prop=my value</code>.</p> |
| <h3 id="publishing-an-abstract-or-concrete-class-as-a-service">Publishing an abstract or concrete class as a Service<a class="headerlink" href="#publishing-an-abstract-or-concrete-class-as-a-service" title="Permanent link">¶</a></h3> |
| <p>It is also possible to expose an abstract or concrete class as a service. To to this, just specify the published class in the <code>specifications</code> attribute:</p> |
| <div class="codehilite"><pre><span class="nd">@Component</span> |
| <span class="nd">@Provides</span><span class="o">(</span><span class="n">specifications</span><span class="o">=</span><span class="n">MyComponent</span><span class="o">.</span><span class="na">class</span><span class="o">)</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyComponent</span> <span class="o">{</span> |
| <span class="c1">// ...</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>or in XML:</p> |
| <div class="codehilite"><pre><span class="nt"><component</span> <span class="na">classname=</span><span class="s">"...FooProviderType1"</span><span class="nt">></span> |
| <span class="nt"><provides</span> <span class="na">specifications=</span><span class="s">"...AbstractFoo"</span><span class="nt">/></span> |
| <span class="nt"></component></span> |
| <span class="nt"><component</span> <span class="na">classname=</span><span class="s">"...FooBarProviderType1"</span><span class="nt">></span> |
| <span class="nt"><provides</span> <span class="na">specifications=</span><span class="s">"[...AbstractFoo, ...Bar]"</span><span class="nt">/></span> |
| <span class="nt"></component></span> |
| </pre></div> |
| |
| |
| <p>As illustrated with the example using annotation, the component can also publish itself as a service. However, such practice is not recommended.</p> |
| <h3 id="controlling-the-service-exposition-from-the-implementation-class">Controlling the service exposition from the implementation class<a class="headerlink" href="#controlling-the-service-exposition-from-the-implementation-class" title="Permanent link">¶</a></h3> |
| <p>To control the exposition of the published service, you can use a <code>service controller</code>. A service controller is a boolean field of the component class. The injected boolean field allows the code to impact the service publication. Setting the field to <code>false</code> unregisters the service from the service registry. Setting it back to <code>true</code> re-publishes the service.</p> |
| <div class="codehilite"><pre><span class="nd">@Component</span> |
| <span class="nd">@Provides</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">ControllerCheckService</span> <span class="kd">implements</span> <span class="n">FooService</span><span class="o">,</span> <span class="n">CheckService</span> <span class="o">{</span> |
| |
| <span class="nd">@ServiceController</span> |
| <span class="kd">private</span> <span class="kt">boolean</span> <span class="n">controller</span><span class="o">;</span> <span class="c1">// Service Controller</span> |
| |
| <span class="kd">public</span> <span class="kt">boolean</span> <span class="nf">foo</span><span class="o">()</span> <span class="o">{</span> |
| <span class="k">return</span> <span class="n">controller</span><span class="o">;</span> |
| <span class="o">}</span> |
| |
| <span class="kd">public</span> <span class="kt">boolean</span> <span class="nf">check</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">"Before : "</span> <span class="o">+</span> <span class="n">controller</span><span class="o">);</span> |
| <span class="n">controller</span> <span class="o">=</span> <span class="o">!</span> <span class="n">controller</span><span class="o">;</span> <span class="c1">// Change the publication</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">"After : "</span> <span class="o">+</span> <span class="n">controller</span><span class="o">);</span> |
| <span class="k">return</span> <span class="n">controller</span><span class="o">;</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>Using XML, the previous component description is:</p> |
| <div class="codehilite"><pre><span class="nt"><component</span> <span class="na">classname=</span><span class="s">"org.apache.felix.ipojo.test.scenarios.component.controller.ControllerCheckService"</span> |
| <span class="na">name=</span><span class="s">"PS-Controller-1-default"</span><span class="nt">></span> |
| <span class="nt"><provides></span> |
| <span class="nt"><controller</span> <span class="na">field=</span><span class="s">"controller"</span><span class="nt">/></span> |
| <span class="nt"></provides></span> |
| <span class="nt"></component></span> |
| </pre></div> |
| |
| |
| <p>The <code>controller</code> may have a value attribute setting the initial value. Setting this value to <code>false</code> disables the initial service registration:</p> |
| <div class="codehilite"><pre><span class="nd">@Component</span> |
| <span class="nd">@Provides</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">ControllerCheckService</span> <span class="kd">implements</span> <span class="n">FooService</span><span class="o">,</span> <span class="n">CheckService</span> <span class="o">{</span> |
| |
| <span class="nd">@ServiceController</span><span class="o">(</span><span class="n">value</span><span class="o">=</span><span class="kc">false</span><span class="o">)</span> |
| <span class="kd">private</span> <span class="kt">boolean</span> <span class="n">controller</span><span class="o">;</span> <span class="c1">// Service Controller</span> |
| |
| <span class="kd">public</span> <span class="kt">boolean</span> <span class="nf">foo</span><span class="o">()</span> <span class="o">{</span> |
| <span class="k">return</span> <span class="n">controller</span><span class="o">;</span> |
| <span class="o">}</span> |
| |
| <span class="kd">public</span> <span class="kt">boolean</span> <span class="nf">check</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">"Before : "</span> <span class="o">+</span> <span class="n">controller</span><span class="o">);</span> |
| <span class="n">controller</span> <span class="o">=</span> <span class="o">!</span> <span class="n">controller</span><span class="o">;</span> <span class="c1">// Change the publication</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">"After : "</span> <span class="o">+</span> <span class="n">controller</span><span class="o">);</span> |
| <span class="k">return</span> <span class="n">controller</span><span class="o">;</span> |
| <span class="o">}</span> |
| |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>If several interfaces are exposed, the controller may have a <code>specification</code> attribute indicating the impacted service:</p> |
| <div class="codehilite"><pre><span class="nd">@Component</span> |
| <span class="nd">@Provides</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">ControllerCheckService</span> <span class="kd">implements</span> <span class="n">FooService</span><span class="o">,</span> <span class="n">CheckService</span> <span class="o">{</span> |
| |
| <span class="nd">@ServiceController</span><span class="o">(</span><span class="n">value</span><span class="o">=</span><span class="kc">false</span><span class="o">,</span> <span class="n">specification</span><span class="o">=</span><span class="n">FooService</span><span class="o">.</span><span class="na">class</span><span class="o">)</span> |
| <span class="kd">private</span> <span class="kt">boolean</span> <span class="n">controller</span><span class="o">;</span> <span class="c1">// Service Controller</span> |
| |
| <span class="kd">public</span> <span class="kt">boolean</span> <span class="nf">foo</span><span class="o">()</span> <span class="o">{</span> |
| <span class="k">return</span> <span class="n">controller</span><span class="o">;</span> |
| <span class="o">}</span> |
| |
| <span class="kd">public</span> <span class="kt">boolean</span> <span class="nf">check</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">"Before : "</span> <span class="o">+</span> <span class="n">controller</span><span class="o">);</span> |
| <span class="n">controller</span> <span class="o">=</span> <span class="o">!</span> <span class="n">controller</span><span class="o">;</span> <span class="c1">// Change the publication</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">"After : "</span> <span class="o">+</span> <span class="n">controller</span><span class="o">);</span> |
| <span class="k">return</span> <span class="n">controller</span><span class="o">;</span> |
| <span class="o">}</span> |
| |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>In XML, each <code>provides</code> can have one <code>controller</code> element.</p> |
| <div class="codehilite"><pre><span class="nt"><component</span> <span class="na">classname=</span><span class="s">"org.apache.felix.ipojo.test.scenarios.component.controller.ControllerCheckService"</span> |
| <span class="na">name=</span><span class="s">"PS-Controller-1-false"</span><span class="nt">></span> |
| <span class="nt"><provides></span> |
| <span class="nt"><controller</span> <span class="na">field=</span><span class="s">"controller"</span> <span class="na">value=</span><span class="s">"false"</span><span class="nt">/></span> |
| <span class="nt"></provides></span> |
| <span class="nt"></component></span>} |
| </pre></div> |
| |
| |
| <h3 id="being-notified-of-the-service-registration-and-unregistration">Being notified of the service registration and unregistration<a class="headerlink" href="#being-notified-of-the-service-registration-and-unregistration" title="Permanent link">¶</a></h3> |
| <p>You can also be notified when the service is published and unpublished. This is done by specifying the two callbacks in the <code><provides/></code> element:</p> |
| <div class="codehilite"><pre><span class="nt"><component</span> |
| <span class="na">classname=</span><span class="s">"org.apache.felix.ipojo.test.scenarios.component.callbacks.CallbacksCheckService"</span> |
| <span class="na">name=</span><span class="s">"PS-Callbacks-both-1"</span><span class="nt">></span> |
| <span class="nt"><provides</span> |
| <span class="na">specifications=</span><span class="s">"org.apache.felix.ipojo.test.scenarios.ps.service.FooService"</span> |
| <span class="na">post-unregistration=</span><span class="s">"unregistered"</span> <span class="na">post-registration=</span><span class="s">"registered"</span><span class="nt">/></span> |
| <span class="nt"><provides</span> |
| <span class="na">specifications=</span><span class="s">"org.apache.felix.ipojo.test.scenarios.ps.service.CheckService"</span> |
| <span class="na">post-unregistration=</span><span class="s">"unregistered"</span> <span class="na">post-registration=</span><span class="s">"registered"</span><span class="nt">/></span> |
| <span class="nt"></component></span> |
| </pre></div> |
| |
| |
| <p>Or by using the <code>@PostRegistration</code> and <code>@PostUnregistration</code> annotations:</p> |
| <div class="codehilite"><pre><span class="nd">@PostRegistration</span> |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">registered</span><span class="o">(</span><span class="n">ServiceReference</span> <span class="n">ref</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">"Registered"</span><span class="o">);</span> |
| <span class="o">}</span> |
| |
| <span class="nd">@PostUnregistration</span> |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">unregistered</span><span class="o">(</span><span class="n">ServiceReference</span> <span class="n">ref</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">"Unregistered"</span><span class="o">);</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <ul> |
| <li>The <code>post-registration</code> callback is called after the service publication</li> |
| <li>The <code>post-unregistration</code> callback is called after the service unpublication</li> |
| </ul> |
| <p>Those callback methods must have the following signature: <code>public void name(ServiceReference ref)</code>. So they receive the published / unpublished service reference. The callbacks are called in the <em>same thread</em> as the publication / unpublication itself. </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> |
