| <!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 - iPOJO Factory Service</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="using-the-factory-service-interface">Using the Factory service interface<a class="headerlink" href="#using-the-factory-service-interface" title="Permanent link">¶</a></h1> |
| <div class="toc"> |
| <ul> |
| <li><a href="#using-the-factory-service-interface">Using the Factory service interface</a><ul> |
| <li><a href="#private-vs-public-factories">Private vs. Public factories</a></li> |
| <li><a href="#the-factory-service">The Factory service</a><ul> |
| <li><a href="#finding-and-using-a-factory-service">Finding and using a Factory service</a></li> |
| <li><a href="#retrieving-factory-information">Retrieving factory information</a></li> |
| <li><a href="#creating-an-instance">Creating an instance</a></li> |
| <li><a href="#getting-created-instances">Getting created instances</a></li> |
| <li><a href="#deleting-instances">Deleting instances</a></li> |
| <li><a href="#observing-the-factory-state">Observing the factory state</a></li> |
| </ul> |
| </li> |
| <li><a href="#declaration-publication-vs-programmatic-creation">Declaration publication vs. Programmatic creation</a></li> |
| </ul> |
| </li> |
| </ul> |
| </div> |
| <p>When you declare a component either with <code>@Component</code> or <code><component></code>, you are instructing iPOJO to create a <em>factory</em>.</p> |
| <p>A factory is an entity managed by iPOJO and responsible for the instance creation and management. Indeed, every time you declare an instance with <code>@Instantiate</code>, <code><instance></code> or the configuration admin, you are asking the appropriate factory to create the instance an manage the instance.</p> |
| <h2 id="private-vs-public-factories">Private vs. Public factories<a class="headerlink" href="#private-vs-public-factories" title="Permanent link">¶</a></h2> |
| <p>When you are declaring the component (type), you have the choice between making this factory public or private. Private factories are not accessible, and can only create instances declared from the same bundle. Public factories are accessible from anywhere, and so are able to create instances declared by anyone. They also expose the <code>org.apache.felix.ipojo.Factory</code> service.</p> |
| <p>By default, factories are public. However, you can hide them with:</p> |
| <div class="codehilite"><pre><span class="nd">@Component</span><span class="o">(</span><span class="n">publicFactory</span><span class="o">=</span><span class="kc">false</span><span class="o">)</span> |
| </pre></div> |
| |
| |
| <h2 id="the-factory-service">The Factory service<a class="headerlink" href="#the-factory-service" title="Permanent link">¶</a></h2> |
| <p>Every public factory is exposed as an OSGi service. The |
| <a href="http://felix.apache.org/ipojo/api/1.12.1/org/apache/felix/ipojo/Factory.html">org.apache.felix.ipojo.Factory</a> service interface allows you to create and manage instance programmatically.</p> |
| <h3 id="finding-and-using-a-factory-service">Finding and using a Factory service<a class="headerlink" href="#finding-and-using-a-factory-service" title="Permanent link">¶</a></h3> |
| <p>Let's imagine you have the following class:</p> |
| <div class="codehilite"><pre><span class="nd">@Component</span><span class="o">(</span><span class="n">name</span><span class="o">=</span><span class="s">"my-factory"</span><span class="o">)</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyImplementation</span> <span class="o">{</span> |
| |
| <span class="kd">public</span> <span class="nf">MyImplementation</span><span class="o">(</span><span class="nd">@Property</span> <span class="n">String</span> <span class="n">message</span><span class="o">)</span> <span class="o">{</span> |
| <span class="c1">//...</span> |
| <span class="o">}</span> |
| |
| <span class="c1">//...</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>Once packaged and deployed, iPOJO finds it and creates the factory object and registers it in the OSGi service registry (because this factory is public). However, to find the right Factory service from within the OSGi service registry, you must a filter to distinguish this factory from the other ones. Fortunately, iPOJO exposed a service property allowing this distinction: <code>factory.name</code>. In the previous example you can retrieve the factory service with:</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">"(factory.name=my-factory)"</span><span class="o">)</span> |
| <span class="kd">private</span> <span class="n">Factory</span> <span class="n">factory</span><span class="o">;</span> |
| </pre></div> |
| |
| |
| <p>When no name is provided (in the <code>@Component</code> annotation), the qualified class name is used as factory name.</p> |
| <h3 id="retrieving-factory-information">Retrieving factory information<a class="headerlink" href="#retrieving-factory-information" title="Permanent link">¶</a></h3> |
| <p>Once you have the <code>factory</code> object, you can get a couple of additional metadata. The factory name can be retrieved with <code>getName</code>. Additionally, the factory version is retrieved with the <code>getVersion</code> method.</p> |
| <p>The current factory state is accessible with the <code>getState</code> method. A factory can either be <code>VALID</code> or <code>INVALID</code>. A factory is valid only and only if all the required <em>handlers</em> are available (don't worry, you don't really need to know this definition). In other words, when a factory is not valid, it just means that a <em>handler</em> is not there (the bundle is not deployed).</p> |
| <p>By using the <code>getComponentDescription()</code> method, you can retrieve additional information about the factory. Check the <a href="http://felix.apache.org/ipojo/api/1.12.1/org/apache/felix/ipojo/architecture/ComponentTypeDescription.html">ComponentTypeDescription |
| API</a> for more information.</p> |
| <p>To illustrate factory's state retrieval, let's look at the following code displaying the name, version and state of all the available factories.</p> |
| <div class="codehilite"><pre><span class="nd">@Requires</span> |
| <span class="kd">private</span> <span class="n">Factory</span><span class="o">[]</span> <span class="n">factories</span><span class="o">;</span> |
| |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">dump</span><span class="o">()</span> <span class="o">{</span> |
| <span class="k">for</span> <span class="o">(</span><span class="n">Factory</span> <span class="n">factory</span> <span class="o">:</span> <span class="n">factories</span><span class="o">)</span> <span class="o">{</span> |
| <span class="n">String</span> <span class="n">version</span> <span class="o">=</span> <span class="n">factory</span><span class="o">.</span><span class="na">getVersion</span><span class="o">()</span> <span class="o">!=</span> <span class="kc">null</span> <span class="o">?</span> <span class="n">factory</span><span class="o">.</span><span class="na">getVersion</span><span class="o">()</span> <span class="o">:</span> <span class="s">""</span><span class="o">;</span> |
| <span class="n">String</span> <span class="n">state</span> <span class="o">=</span> <span class="n">factory</span><span class="o">.</span><span class="na">getState</span><span class="o">()</span> <span class="o">==</span> <span class="n">Factory</span><span class="o">.</span><span class="na">VALID</span> <span class="o">?</span> <span class="s">"valid"</span> <span class="o">:</span> <span class="s">"invalid"</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">"Factory "</span> <span class="o">+</span> <span class="n">factory</span><span class="o">.</span><span class="na">getName</span><span class="o">()</span> <span class="o">+</span> <span class="s">" "</span> <span class="o">+</span> <span class="n">version</span> <span class="o">+</span> <span class="s">" "</span> <span class="o">+</span> <span class="n">state</span><span class="o">);</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <h3 id="creating-an-instance">Creating an instance<a class="headerlink" href="#creating-an-instance" title="Permanent link">¶</a></h3> |
| <p>Factory services are generally used to create instances. The <code>createComponentInstance</code> method let you create instances. It receives a configuration object (potentially <code>null</code>):</p> |
| <div class="codehilite"><pre><span class="kd">public</span> <span class="kt">void</span> <span class="nf">createMyInstance</span><span class="o">()</span> <span class="kd">throws</span> <span class="n">Exception</span> <span class="o">{</span> |
| <span class="n">ComponentInstance</span> <span class="n">instance</span> <span class="o">=</span> <span class="n">factory</span><span class="o">.</span><span class="na">createComponentInstance</span><span class="o">(</span><span class="kc">null</span><span class="o">);</span> |
| <span class="c1">//...</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>The <code>createComponentInstance</code> method returns a <a href="http://felix.apache.org/ipojo/api/1.12.1/org/apache/felix/ipojo/architecture/ComponentInstance.html">ComponentInstance</a> object. This object is representing the created instance, and let you manage it (to reconfigure it or to dispose it).</p> |
| <p>The configuration you can pass to the <code>createComponentInstance</code> method let you configure the instance properties. For example, you can gives a value to the <code>message</code> property (From the component example):</p> |
| <div class="codehilite"><pre><span class="kd">public</span> <span class="kt">void</span> <span class="nf">createMyInstance</span><span class="o">()</span> <span class="kd">throws</span> <span class="n">Exception</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">configuration</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Hashtable</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">configuration</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"message"</span><span class="o">,</span> <span class="s">"hello"</span><span class="o">);</span> |
| <span class="n">ComponentInstance</span> <span class="n">instance</span> <span class="o">=</span> <span class="n">factory</span><span class="o">.</span><span class="na">createComponentInstance</span><span class="o">(</span><span class="n">configuration</span><span class="o">);</span> |
| <span class="c1">//...</span> |
| </pre></div> |
| |
| |
| <p>}</p> |
| <p>To give a name to your instance, set the <code>instance.name</code> property.</p> |
| <h3 id="getting-created-instances">Getting created instances<a class="headerlink" href="#getting-created-instances" title="Permanent link">¶</a></h3> |
| <p>The Factory service also allows you to retrieve the created instances:</p> |
| <div class="codehilite"><pre><span class="kd">public</span> <span class="kt">void</span> <span class="nf">listInstancesFromFactory</span><span class="o">(</span><span class="n">Factory</span> <span class="n">factory</span><span class="o">)</span> <span class="o">{</span> |
| <span class="k">for</span> <span class="o">(</span><span class="n">ComponentInstance</span> <span class="n">instance</span> <span class="o">:</span> <span class="n">factory</span><span class="o">.</span><span class="na">getInstances</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">instance</span><span class="o">.</span><span class="na">getInstanceName</span><span class="o">());</span> |
| <span class="o">}</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <h3 id="deleting-instances">Deleting instances<a class="headerlink" href="#deleting-instances" title="Permanent link">¶</a></h3> |
| <p>You can't delete an instance directly from the factory object. However, you can from the <code>ComponentInstance</code> object. In the case you already have this object, just call the <code>dispose()</code> method. Otherwise, retrieve the component instance from the factory object and then call the <code>dispose()</code> method.</p> |
| <h3 id="observing-the-factory-state">Observing the factory state<a class="headerlink" href="#observing-the-factory-state" title="Permanent link">¶</a></h3> |
| <p>As stated above, factory objects have a state. We already saw how to retrieve the current state of the factory. You can also register a <a href="http://felix.apache.org/ipojo/api/1.12.1/org/apache/felix/ipojo/architecture/FactoryStateListener.html">FactoryStateListener</a> to be notified when the state changes. The methods <code>addFactoryStateListener</code> and <code>removeFactoryStateListener</code> let you respectively register and unregister the listener.</p> |
| <h2 id="declaration-publication-vs-programmatic-creation">Declaration publication vs. Programmatic creation<a class="headerlink" href="#declaration-publication-vs-programmatic-creation" title="Permanent link">¶</a></h2> |
| <p>This page has explained how to create an instance from the Factory service. However, when the factory leaves or become invalid your instance is disposed. The instance is <strong>not</strong> recreated when the factory comes back or is revalidated.</p> |
| <p>To avoid to have to listen and manage these events, you can use an <a href="http://felix.apache.org/ipojo/api/1.12.1/org/apache/felix/ipojo/architecture/InstanceDeclaration.html">InstanceDeclaration</a>. |
| An instance declaration is a service you publish to instruct iPOJO to create an instance |
| and manage its lifecycle. <code>InstanceDeclaration</code> are created through the <code>DeclarationBuilderService</code> |
| (since 1.12):</p> |
| <div class="codehilite"><pre><span class="c1">// Obtain the service through the service registry</span> |
| <span class="n">DeclarationBuilderService</span> <span class="n">service</span> <span class="o">=</span> <span class="o">...</span> |
| |
| <span class="c1">// Get a fresh instance builder</span> |
| <span class="n">InstanceBuilder</span> <span class="n">builder</span> <span class="o">=</span> <span class="n">service</span><span class="o">.</span><span class="na">newInstance</span><span class="o">(</span><span class="s">"my-factory"</span><span class="o">);</span> |
| |
| <span class="n">DeclarationHandle</span> <span class="n">handle</span> <span class="o">=</span> <span class="n">builder</span><span class="o">.</span><span class="na">name</span><span class="o">(</span><span class="s">"a-unique-name"</span><span class="o">)</span> <span class="c1">// Make sure name is unique for the expected type</span> |
| <span class="o">.</span><span class="na">configure</span><span class="o">()</span> |
| <span class="o">.</span><span class="na">property</span><span class="o">(</span><span class="s">"a-property"</span><span class="o">,</span> <span class="s">"a-value"</span><span class="o">)</span> |
| <span class="o">.</span><span class="na">property</span><span class="o">(</span><span class="s">"another-property"</span><span class="o">,</span> <span class="s">"another-value"</span><span class="o">)</span> |
| <span class="o">.</span><span class="na">build</span><span class="o">();</span> |
| |
| <span class="c1">// Push the InstanceDeclaration service in the registry</span> |
| <span class="n">handle</span><span class="o">.</span><span class="na">publish</span><span class="o">();</span> |
| </pre></div> |
| |
| |
| <p>In this snippet, we've registered a named <code>InstanceDeclaration</code> service for the <code>my-factory</code> component type, we've |
| created a handle though an <code>InstanceBuilder</code> object. The builder helps to configure and produce an |
| InstanceDeclaration that is controllable through the handle. By default, the declaration service will be registered with |
| the BundleContext of the user (this is configurable with the <code>context(BundleContext)</code> method). Once |
| created, call the <code>publish</code> method to register the declaration service and let iPOJO do its usual work.</p> |
| <p>Call the <code>retract</code> method on the handle to dispose the service.</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. 1571278 by guillaume on Mon, 24 Feb 2014 13:20:49 +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> |
