| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE- 2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <head> |
| <title>Apache Felix - How-to use iPOJO factories</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="ipojo-factories-principles">iPOJO Factories Principles<a class="headerlink" href="#ipojo-factories-principles" title="Permanent link">¶</a></h1> |
| <p><em>iPOJO defines a factory for each declared component type. These factories are used to create component instances. This document presents how to declare instances and configure them. The API to create, dispose and reconfigure instances is also explained.</em></p> |
| <div class="toc"> |
| <ul> |
| <li><a href="#ipojo-factories-principles">iPOJO Factories Principles</a><ul> |
| <li><a href="#preliminary-concepts">Preliminary Concepts</a><ul> |
| <li><a href="#component-type">Component Type</a></li> |
| <li><a href="#component-instance">Component Instance</a></li> |
| </ul> |
| </li> |
| <li><a href="#how-to-declare-instances-inside-metadata-files">How-to declare instances inside metadata files</a></li> |
| <li><a href="#creating-disposing-and-reconfiguring-instances-with-the-api">Creating, disposing and reconfiguring instances with the API</a><ul> |
| <li><a href="#creating-instances">Creating instances</a></li> |
| <li><a href="#disposing-created-instance">Disposing created instance</a></li> |
| <li><a href="#reconfiguring-instance">Reconfiguring instance</a></li> |
| <li><a href="#accessing-services-exposed-by-created-instances">Accessing services exposed by created instances</a></li> |
| </ul> |
| </li> |
| <li><a href="#how-to-use-the-managedservicefactory-to-create-disposed-and-reconfigure-instances">How to use the ManagedServiceFactory to create, disposed and reconfigure instances</a></li> |
| </ul> |
| </li> |
| </ul> |
| </div> |
| <h2 id="preliminary-concepts">Preliminary Concepts<a class="headerlink" href="#preliminary-concepts" title="Permanent link">¶</a></h2> |
| <h3 id="component-type">Component Type<a class="headerlink" href="#component-type" title="Permanent link">¶</a></h3> |
| <p>A component type is a kind of instance template. If we compare component concepts with object oriented programming, component types are classes and component instances are objects. A component type is declared inside a metadata file (generally named 'metadata.xml'). The next snippet shows you a component type declaration: </p> |
| <div class="codehilite"><pre><span class="nt"><component</span> <span class="na">classname=</span><span class="s">"..."</span> <span class="na">name=</span><span class="s">"MyFactory"</span><span class="nt">></span> |
| ... |
| <span class="c"><!--component type configuration --></span> |
| ... |
| <span class="nt"></component></span> |
| </pre></div> |
| |
| |
| <p>A component type declaration begins generally by <code><component></code> and is composed by:</p> |
| <ul> |
| <li>An implementation class (<code>classname</code>, mandatory). The <code>classname</code> attribute indicates the qualified name of the class implementing the component.</li> |
| <li>A name ('name')</li> |
| <li>Handler configuration (see handler guide)</li> |
| </ul> |
| <p>The <code>name</code> attribute contains the factory name. If not specified, the <code>classname</code> attribute is used as the factory name. This factory name is used to refer to the factory (and consequently to the component type). |
| A factory can be public or private. A public factory allows creating instances dynamically and from other bundles. A private factory can only be used to create instances by declaring them in the same metadata.xml file that defines the instances' component type (i.e. in the same bundle). By default, factories are public. To set the factory to private add the 'public="false"'' attribute in the '<component>' element, such as: </p> |
| <div class="codehilite"><pre><span class="nt"><component</span> <span class="na">classname=</span><span class="s">"..."</span> <span class="na">name=</span><span class="s">"MyPrivateFactory"</span> <span class="na">public=</span><span class="s">"false"</span><span class="nt">></span> |
| ... |
| <span class="c"><!--component type configuration --></span> |
| ... |
| <span class="nt"></component></span> |
| </pre></div> |
| |
| |
| <p>Public factories offer different ways to create instances:</p> |
| <ul> |
| <li>Instances can be declared in iPOJO descriptor in any bundle (i.e. from any metadata.xml file)</li> |
| <li>Instances can be created dynamically by using the API. Two APIs are provided the iPOJO Factory API and the OSGi Configuration Admin API</li> |
| </ul> |
| <p>Indeed, iPOJO will publish two services to access the factory through the API:</p> |
| <ul> |
| <li><code>org.apache.felix.ipojo.Factory</code> : iPOJO Factory Interface</li> |
| </ul> |
| <p>The factory name will be used as the <code>service.pid</code> property for those services. The <code>service.pid</code> is unique and persists between framework restarts. The <code>service.pid</code> of the factory equals the factory name. This allows identifying factories exposed in the service registry. |
| Factories are either valid or invalid. You can't create instances until a factory becomes valid. A factory is invalid if required handlers are missing. This issue occurs only if the component type uses external handlers.</p> |
| <h3 id="component-instance">Component Instance<a class="headerlink" href="#component-instance" title="Permanent link">¶</a></h3> |
| <p>A component instance is an instance of a component type. For example, if a component type declares 'providing' and 'requiring' services, then the component instances will actually expose and require those services. Several instances can be created from one factory, but all these instances will be managed as different entities, and so are independent. A component instance is characterized by:</p> |
| <ul> |
| <li>a component type (the factory name)</li> |
| <li>an instance name (used to identify the instance, is unique)</li> |
| <li>a configuration : a set of <key, value> couple</li> |
| </ul> |
| <p>A factory keeps a reference to each created instance. If the factory stops, goes away, or becomes invalid, all created instances are stopped and are destroyed. |
| To create an instance, the creation request (describing the instance to create) must refer to the factory (by using the factory name), and provide the instance configuration. This configuration can specify the instance name (<code>instance.name</code> property). Be aware that this name must be unique. If not specified, iPOJO will generate a unique name. |
| A factory can refuse the creation if the configuration is not acceptable or if the factory is invalid. An unacceptable configuration is a not suitable configuration in regard to component type. Reasons for unacceptable configuration are: </p> |
| <ul> |
| <li>The instance name is not set or not unique</li> |
| <li>A property required by the component type is missing inside the configuration</li> |
| <li>A pushed property has a wrong type</li> |
| </ul> |
| <h2 id="how-to-declare-instances-inside-metadata-files">How-to declare instances inside metadata files<a class="headerlink" href="#how-to-declare-instances-inside-metadata-files" title="Permanent link">¶</a></h2> |
| <p>The main way to create instances is to declare those instances inside the iPOJO descriptor file (i.e. 'metadata.xml'). Those declarations can use either public factories from any bundle, or private factories from the same bundle. Private factories are generally used to guaranty singleton instance as instances can only be created inside the same bundle. </p> |
| <p>When a instance declaration targets an external public factory, it will wait until the factory becomes available. So, the instance will be created only when the factory appears and is valid. If the factory disappears after the instance creation, the instance is disposed and will be recreated as soon as the factory comes back. |
| The next snippet shows how to declare an instance in the metadata:</p> |
| <div class="codehilite"><pre><span class="nt"><instance</span> <span class="na">component=</span><span class="s">"component factory name"</span> <span class="na">name =</span> <span class="s">"instance name"</span> <span class="nt">></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"a property name"</span> <span class="na">value=</span><span class="s">"a string form of the value"</span><span class="nt">/></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"another prop name"</span> <span class="na">value=</span><span class="s">"the string form value "</span><span class="nt">/></span> |
| <span class="nt"></instance></span> |
| </pre></div> |
| |
| |
| <p>An instance declaration must contain the 'component' attribute. This attribute specifies the factory name (i.e. the component type). It can use either the factory name or the class name. The 'name' attribute allows setting the instance name. If not set, iPOJO will generate a unique name for you. Then, instances can declare properties. Those property are mostly key-value pair. The key refer to a property name from the component type declaration such as in:</p> |
| <div class="codehilite"><pre><span class="nt"><component</span> <span class="na">classname=</span><span class="s">"..."</span> <span class="na">name=</span><span class="s">"my-factory"</span><span class="nt">></span> |
| <span class="nt"><properties></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="nt">/></span> |
| <span class="nt"></properties></span> |
| <span class="nt"></component></span> |
| <span class="nt"><instance</span> <span class="na">component=</span><span class="s">"my-factory "</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">"bla bla bla"</span><span class="nt">/></span> |
| <span class="nt"></instance></span> |
| </pre></div> |
| |
| |
| <p>The string-form of the property value will be use to create the real object at runtime. If an unacceptable configuration is set, the instance is not created, and an error message appears to the console (and in the Log Service if present). |
| Instance declaration properties can be more complex than only 'key-value'. It can contains structure like list, map, dictionary and arrays such as in:</p> |
| <div class="codehilite"><pre><span class="nt"><instance</span> <span class="na">component=</span><span class="s">"a.factory"</span> <span class="na">name=</span><span class="s">"complex-props"</span><span class="nt">></span> |
| <span class="c"><!--Creates a string array--></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"array"</span> <span class="na">type=</span><span class="s">"array"</span><span class="nt">></span> |
| <span class="nt"><property</span> <span class="na">value=</span><span class="s">"a"</span><span class="nt">/></span> |
| <span class="nt"><property</span> <span class="na">value=</span><span class="s">"b"</span><span class="nt">/></span> |
| <span class="nt"></property></span> |
| <span class="c"><!--Creates a list containing string--></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"list"</span> <span class="na">type=</span><span class="s">"list"</span><span class="nt">></span> |
| <span class="nt"><property</span> <span class="na">value=</span><span class="s">"a"</span><span class="nt">/></span> |
| <span class="nt"><property</span> <span class="na">value=</span><span class="s">"b"</span><span class="nt">/></span> |
| <span class="nt"></property></span> |
| <span class="c"><!--Creates a dictionary containing string--></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"dict"</span> <span class="na">type=</span><span class="s">"dictionary"</span><span class="nt">></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"a"</span> <span class="na">value=</span><span class="s">"a"</span><span class="nt">/></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"b"</span> <span class="na">value=</span><span class="s">"b"</span><span class="nt">/></span> |
| <span class="nt"></property></span> |
| <span class="c"><!--Creates a map containing string--></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"map"</span> <span class="na">type=</span><span class="s">"map"</span><span class="nt">></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"a"</span> <span class="na">value=</span><span class="s">"a"</span><span class="nt">/></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"b"</span> <span class="na">value=</span><span class="s">"b"</span><span class="nt">/></span> |
| <span class="nt"></property></span> |
| <span class="c"><!--A complex type can contains any other complex objects:--></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"complex-array"</span> <span class="na">type=</span><span class="s">"array"</span><span class="nt">></span> |
| <span class="nt"><property</span> <span class="na">type=</span><span class="s">"list"</span><span class="nt">></span> |
| <span class="nt"><property</span> <span class="na">value=</span><span class="s">"a"</span><span class="nt">/></span> |
| <span class="nt"><property</span> <span class="na">value=</span><span class="s">"b"</span><span class="nt">/></span> |
| <span class="nt"></property></span> |
| <span class="nt"><property</span> <span class="na">type=</span><span class="s">"list"</span><span class="nt">></span> |
| <span class="nt"><property</span> <span class="na">value=</span><span class="s">"c"</span><span class="nt">/></span> |
| <span class="nt"><property</span> <span class="na">value=</span><span class="s">"d"</span><span class="nt">/></span> |
| <span class="nt"></property></span> |
| <span class="nt"></property></span> |
| <span class="c"><!--Empty structures will create empty objects--></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"empty-array"</span> <span class="na">type=</span><span class="s">"array"</span><span class="nt">/></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"empty-list"</span> <span class="na">type=</span><span class="s">"list"</span><span class="nt">/></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"empty-map"</span> <span class="na">type=</span><span class="s">"map"</span><span class="nt">/></span> |
| <span class="nt"></instance></span> |
| </pre></div> |
| |
| |
| <div class="alert alert-info" markdown="1"> |
| <h4>Instance name and factory name</h4> |
| The <code>instance.name</code> and <code>factory.name</code> property should not be set directly. iPOJO manages those properties. |
| </div> |
| |
| <h2 id="creating-disposing-and-reconfiguring-instances-with-the-api">Creating, disposing and reconfiguring instances with the API<a class="headerlink" href="#creating-disposing-and-reconfiguring-instances-with-the-api" title="Permanent link">¶</a></h2> |
| <p>A public factory is accessible through an exposed service (<a href="http://felix.apache.org/ipojo/api/1.12.1/org/apache/felix/ipojo/Factory.html">org.apache.felix.ipojo.Factory</a>). This service is accessible as any other OSGi service, and could be an iPOJO dependency using a LDAP filter or the 'from' attribute such as in:</p> |
| <div class="codehilite"><pre><span class="nt"><component</span> <span class="na">classname=</span><span class="s">"..."</span><span class="nt">></span> |
| <span class="c"><!-- These two requirement descriptions are equivalent --></span> |
| <span class="nt"><requires</span> <span class="na">field=</span><span class="s">"a_field"</span> <span class="na">filter=</span><span class="s">"(factory.name=factory-name)"</span><span class="nt">/></span> |
| <span class="nt"><requires</span> <span class="na">field=</span><span class="s">"another_field"</span> <span class="na">from=</span><span class="s">"another-factory"</span><span class="nt">/></span> |
| <span class="nt"></component></span> |
| </pre></div> |
| |
| |
| <h3 id="creating-instances">Creating instances<a class="headerlink" href="#creating-instances" title="Permanent link">¶</a></h3> |
| <p>Once you have a reference on the factory you can create instance with the 'createComponentInstance' method.</p> |
| <div class="codehilite"><pre>ComponentInstance createComponentInstance(java.util.Dictionary configuration) |
| throws UnacceptableConfiguration, |
| MissingHandlerException, |
| ConfigurationException |
| </pre></div> |
| |
| |
| <p>This method returns a reference on the created instance. As you see, the method receives a dictionary containing the instance configuration. This configuration contains key-value pairs. However, values are either object (of the adequate type) of String used to create objects. This configuration can be 'null' if no properties have to be pushed.</p> |
| <div class="info" markdown="1"> |
| <h4>Instance Name</h4> |
| The `instance.name` property can be used to specify the instance name. |
| </div> |
| |
| <p>Instances are automatically started when created. However, the instance can be invalid, if at least one handler is not valid). |
| The instance creation process can fail. Three exceptions can be thrown during the creation:</p> |
| <ul> |
| <li>UnacceptableConfiguration means that mandatory properties are missing in the instance configuration</li> |
| <li>MissingHandlerException means that the factory is not valid (i.e. an external handler is missing)</li> |
| <li>ConfigurationException means that the instance configuration has failed. The cause can be either an issue in the component type description or an invalid property type.</li> |
| </ul> |
| <p>If an error occurs, a comprehensive message is reported in order to solve the issue. |
| The next snippet shows an example of instance creation:</p> |
| <div class="codehilite"><pre><span class="c1">// Assume we get a Factory in the fact field</span> |
| <span class="n">Properties</span> <span class="n">props</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Properties</span><span class="o">();</span> |
| <span class="n">props</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"instance.name"</span><span class="o">,</span><span class="s">"instance-name"</span><span class="o">);</span> |
| <span class="n">props</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"foo"</span><span class="o">,</span> <span class="s">"blablabla"</span><span class="o">);</span> |
| <span class="k">try</span> <span class="o">{</span> |
| <span class="n">instance</span> <span class="o">=</span> <span class="n">fact</span><span class="o">.</span><span class="na">createComponentInstance</span><span class="o">(</span><span class="n">props</span><span class="o">);</span> |
| <span class="o">}</span> <span class="k">catch</span><span class="o">(</span><span class="n">Exception</span> <span class="n">e</span><span class="o">)</span> <span class="o">{</span> |
| <span class="n">fail</span><span class="o">(</span><span class="s">"Cannot create the instance : "</span> <span class="o">+</span> <span class="n">e</span><span class="o">.</span><span class="na">getMessage</span><span class="o">());</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <h3 id="disposing-created-instance">Disposing created instance<a class="headerlink" href="#disposing-created-instance" title="Permanent link">¶</a></h3> |
| <p>You can only disposed instances that you created. To dispose an instance, just call the 'dispose' method on the ComponentInstance object (returned by the createComponentInstance method).</p> |
| <div class="codehilite"><pre><span class="n">instance</span><span class="o">.</span><span class="na">dispose</span><span class="o">();</span> |
| </pre></div> |
| |
| |
| <h3 id="reconfiguring-instance">Reconfiguring instance<a class="headerlink" href="#reconfiguring-instance" title="Permanent link">¶</a></h3> |
| <p>To reconfigure an instance, call the <code>reconfigure</code> method on the ComponentInstance object. This method receives the new set of properties. Be aware that the <code>instance.name</code> property cannot be changed.</p> |
| <div class="codehilite"><pre><span class="n">Properties</span> <span class="n">props2</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Properties</span><span class="o">();</span> |
| <span class="n">props2</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"foo"</span><span class="o">,</span> <span class="s">"abc"</span><span class="o">);</span> |
| <span class="n">instance</span><span class="o">.</span><span class="na">reconfigure</span><span class="o">(</span><span class="n">props2</span><span class="o">);</span> |
| </pre></div> |
| |
| |
| <h3 id="accessing-services-exposed-by-created-instances">Accessing services exposed by created instances<a class="headerlink" href="#accessing-services-exposed-by-created-instances" title="Permanent link">¶</a></h3> |
| <p>You can obviously access services exposed by an instance that you create. |
| To do this just use the OSGi API and the bundle context in order to query service references in the service registry such as in</p> |
| <div class="codehilite"><pre><span class="n">ComponentInstance</span> <span class="n">instance</span> <span class="o">=</span> <span class="o">...</span> |
| <span class="c1">// ... </span> |
| <span class="k">try</span> <span class="o">{</span> |
| <span class="n">ServiceReference</span><span class="o">[]</span> <span class="n">refs</span> <span class="o">=</span> |
| <span class="n">context</span><span class="o">.</span><span class="na">getServiceReferences</span><span class="o">(</span><span class="n">YourServiceInterface</span><span class="o">.</span><span class="na">class</span><span class="o">.</span><span class="na">getName</span><span class="o">(),</span> |
| <span class="s">"(instance.name="</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="s">")"</span><span class="o">);</span> |
| <span class="k">if</span> <span class="o">(</span><span class="n">refs</span> <span class="o">!=</span> <span class="kc">null</span><span class="o">)</span> <span class="o">{</span> |
| <span class="n">Foo</span> <span class="n">your_object</span> <span class="o">=</span> <span class="o">(</span><span class="n">Foo</span><span class="o">)</span> <span class="n">context</span><span class="o">.</span><span class="na">getService</span><span class="o">(</span><span class="n">refs</span><span class="o">[</span><span class="mi">0</span><span class="o">]);</span> |
| <span class="o">}</span> |
| <span class="o">}</span> <span class="k">catch</span> <span class="o">(</span><span class="n">InvalidSyntaxException</span> <span class="n">e</span><span class="o">)</span> <span class="o">{</span> |
| <span class="c1">// Should not happen</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>The LDAP filter allows selecting the service provided by your instance. Be care that this service can be not accessible if the instance is not valid. Once you get the service reference, you can ask the service registry to get the service object (i.e. the object contained in your instance). </p> |
| <p>If your instance does not provide services, you can access to the instance by following principles illustrated in the next snippet:</p> |
| <div class="codehilite"><pre><span class="k">if</span> <span class="o">(</span><span class="n">instance</span><span class="o">.</span><span class="na">getState</span><span class="o">()</span> <span class="o">==</span> <span class="n">ComponentInstance</span><span class="o">.</span><span class="na">VALID</span><span class="o">)</span> <span class="o">{</span> |
| <span class="n">ImplementationClass</span> <span class="n">object</span> <span class="o">=</span> |
| <span class="o">(</span><span class="n">ImplementationClass</span><span class="o">)</span> <span class="o">((</span><span class="n">InstanceManager</span><span class="o">)</span> <span class="n">instance</span><span class="o">).</span><span class="na">getPojoObject</span><span class="o">();</span> |
| <span class="o">}</span> <span class="k">else</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">"Cannot get an implementation object from an invalid instance"</span><span class="o">);</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>Take care to check the instance state before accessing the object. Indeed, the behavior of an invalid instance is not guaranty. The 'getPojoObject' method will return an already created implementation (pojo) object or create a new one (if none already created).</p> |
| <h2 id="how-to-use-the-managedservicefactory-to-create-disposed-and-reconfigure-instances">How to use the ManagedServiceFactory to create, disposed and reconfigure instances<a class="headerlink" href="#how-to-use-the-managedservicefactory-to-create-disposed-and-reconfigure-instances" title="Permanent link">¶</a></h2> |
| <p>The principle of the ManagedServiceFactory is the same as the iPOJO Factory Service. So, you can create, dispose and reconfigure instances with the Configuration Admin. |
| For further information, read the OSGi R4.x Compendium - Configuration Admin chapter.</p> |
| <p>Be aware that the <code>updated</code> method is used both for instance creation (if the given configuration is new) and to reconfigure an existing instance. The <code>deleted</code> method is used to dispose instances.</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> |
