| <!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 - Creating instances</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="creating-instances">Creating instances<a class="headerlink" href="#creating-instances" title="Permanent link">¶</a></h1> |
| <div class="toc"> |
| <ul> |
| <li><a href="#creating-instances">Creating instances</a></li> |
| <li><a href="#component-types-and-instances">Component types and instances</a></li> |
| <li><a href="#instantiate">@Instantiate</a><ul> |
| <li><a href="#declaring-a-singleton-instance">Declaring a singleton instance</a></li> |
| </ul> |
| </li> |
| <li><a href="#configuration">@Configuration</a><ul> |
| <li><a href="#configuration-including-lists-and-maps">Configuration including lists and maps</a></li> |
| <li><a href="#methods-returning-instance-objects">Methods returning Instance objects</a></li> |
| </ul> |
| </li> |
| <li><a href="#declaring-instances-in-xml">Declaring instances in XML</a><ul> |
| <li><a href="#setting-the-instance-name">Setting the instance name</a></li> |
| <li><a href="#describing-complex-properties-in-xml">Describing complex properties in XML</a></li> |
| </ul> |
| </li> |
| <li><a href="#creating-instances-using-the-factory-service">Creating instances using the Factory service</a><ul> |
| <li><a href="#the-factory-service">The Factory service</a></li> |
| <li><a href="#creating-instances_1">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="#following-the-factory-state">Following the factory state</a></li> |
| </ul> |
| </li> |
| <li><a href="#creating-instances-using-the-osgi-configuration-admin">Creating instances using the OSGi Configuration Admin</a><ul> |
| <li><a href="#creating-instances_2">Creating instances</a></li> |
| <li><a href="#reconfiguring-instances">Reconfiguring instances</a></li> |
| <li><a href="#disposing-instances">Disposing instances</a></li> |
| </ul> |
| </li> |
| <li><a href="#creating-instances-with-declarations">Creating instances with declarations</a></li> |
| </ul> |
| </div> |
| <h1 id="component-types-and-instances">Component types and instances<a class="headerlink" href="#component-types-and-instances" title="Permanent link">¶</a></h1> |
| <p>iPOJO is a component model enforcing strictly the distinction between component types and instances. The relationship between types and instances is the same as the one between classes and objects in OOP. You can <em>instantiate</em> as many instances as you want from a component type. These instances can be configured with different properties. As a consequence, just using @Component or <component/> declares a component type, not an instance. So, at runtime, nothing will happen until you actually declare or create an instance.</p> |
| <p>iPOJO provides several ways to create instances, this page presents these possibilities:</p> |
| <ul> |
| <li>@Instantiate to create an instance directly from the a class annotated with @Component</li> |
| <li>@Configuration to declare a set of instances</li> |
| <li>using <instance> in the XML metadata</li> |
| <li>using the iPOJO Factory service</li> |
| <li>using the OSGi Configuration Admin</li> |
| <li>using the <code>DeclarationBuilderService</code></li> |
| </ul> |
| <h1 id="instantiate">@Instantiate<a class="headerlink" href="#instantiate" title="Permanent link">¶</a></h1> |
| <p>The @Instantiate annotation is the simplest way to declare an instance. In a class annotated with @Component, you just add the @Instantiate annotation. It instructs iPOJO to declare an instance of the component type described by the current class. </p> |
| <div class="codehilite"><pre><span class="kn">import</span> <span class="nn">org.apache.felix.ipojo.annotations.Component</span><span class="o">;</span> |
| <span class="kn">import</span> <span class="nn">org.apache.felix.ipojo.annotations.Instantiate</span><span class="o">;</span> |
| |
| <span class="nd">@Component</span> |
| <span class="nd">@Instantiate</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>Optionally, you can set the instance name, using the <code>name</code> attribute.</p> |
| <div class="codehilite"><pre><span class="kn">import</span> <span class="nn">org.apache.felix.ipojo.annotations.Component</span><span class="o">;</span> |
| <span class="kn">import</span> <span class="nn">org.apache.felix.ipojo.annotations.Instantiate</span><span class="o">;</span> |
| |
| <span class="nd">@Component</span> |
| <span class="nd">@Instantiate</span><span class="o">(</span><span class="n">name</span><span class="o">=</span><span class="s">"myInstance"</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>The @Instantiate annotation is easy to use but, has a couple of limitations:</p> |
| <ul> |
| <li>it must be used in the @Component class</li> |
| <li>you can't provide a configuration to the instance</li> |
| <li>you can declare only one instance</li> |
| </ul> |
| <h2 id="declaring-a-singleton-instance">Declaring a singleton instance<a class="headerlink" href="#declaring-a-singleton-instance" title="Permanent link">¶</a></h2> |
| <p>The @Instance annotation is particularly useful to declare singleton instances, i.e. a component type with only one instance. To create a singleton instance, combine the @Instantiate annotation and the <code>publicFactory</code> attribute of the @Component annotation:</p> |
| <div class="codehilite"><pre><span class="kn">import</span> <span class="nn">org.apache.felix.ipojo.annotations.Component</span><span class="o">;</span> |
| <span class="kn">import</span> <span class="nn">org.apache.felix.ipojo.annotations.Instantiate</span><span class="o">;</span> |
| |
| <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> |
| <span class="nd">@Instantiate</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">MySingleton</span> <span class="o">{</span> |
| <span class="c1">//...</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>The <code>publicFactory=false</code> attribute makes the component type <em>private</em>, so invisible from other bundles. No one else would be able to create another instance of the component type.</p> |
| <h1 id="configuration">@Configuration<a class="headerlink" href="#configuration" title="Permanent link">¶</a></h1> |
| <p>This second annotation is used on classes to create one or several instances using a fluent API.</p> |
| <div class="codehilite"><pre><span class="kn">import</span> <span class="nn">org.apache.felix.ipojo.configuration.Configuration</span><span class="o">;</span> |
| <span class="kn">import</span> <span class="nn">org.apache.felix.ipojo.configuration.Instance</span><span class="o">;</span> |
| |
| |
| <span class="kn">import</span> <span class="nn">static</span> <span class="n">org</span><span class="o">.</span><span class="na">apache</span><span class="o">.</span><span class="na">felix</span><span class="o">.</span><span class="na">ipojo</span><span class="o">.</span><span class="na">configuration</span><span class="o">.</span><span class="na">Instance</span><span class="o">.</span><span class="na">instance</span><span class="o">;</span> |
| <span class="nd">@Configuration</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">ConfigureOneInstance</span> <span class="o">{</span> |
| |
| <span class="n">Instance</span> <span class="n">myInstance</span> <span class="o">=</span> <span class="n">instance</span><span class="o">().</span><span class="na">of</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="o">.</span><span class="na">with</span><span class="o">(</span><span class="s">"property"</span><span class="o">).</span><span class="na">setto</span><span class="o">(</span><span class="s">"value"</span><span class="o">);</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>The class is annotated with @Configuration. All fields of type Instance (<code>org.apache.felix.ipojo.configuration.Instance</code>) are read and declares an instance. In the previous example, an instance of the <code>MyComponent</code> component type is declared with a property <code>property</code> set to <code>value</code>. The instance is named <code>myInstance</code> (the field name).</p> |
| <p>You can declare several instances in the same @Configuration class:</p> |
| <div class="codehilite"><pre><span class="nd">@Configuration</span> |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">ConfigureTwoInstances</span> <span class="o">{</span> |
| |
| <span class="c1">// Declare an instance of MyComponent named myInstance</span> |
| <span class="n">Instance</span> <span class="n">myInstance1</span> <span class="o">=</span> <span class="n">instance</span><span class="o">().</span><span class="na">of</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="o">.</span><span class="na">with</span><span class="o">(</span><span class="s">"property"</span><span class="o">).</span><span class="na">setto</span><span class="o">(</span><span class="s">"value"</span><span class="o">);</span> |
| |
| <span class="c1">// Declare an instance of MyComponent</span> |
| <span class="n">Instance</span> <span class="n">myInstance2</span> <span class="o">=</span> <span class="n">instance</span><span class="o">().</span><span class="na">of</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="o">.</span><span class="na">with</span><span class="o">(</span><span class="s">"property"</span><span class="o">).</span><span class="na">setto</span><span class="o">(</span><span class="s">"value2"</span><span class="o">);</span> |
| |
| <span class="c1">// Declare an instance of AnotherComponent</span> |
| <span class="n">Instance</span> <span class="n">myInstance2</span> <span class="o">=</span> <span class="n">instance</span><span class="o">().</span><span class="na">of</span><span class="o">(</span><span class="n">AnotherComponent</span><span class="o">.</span><span class="na">class</span><span class="o">);</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>By default, the instance name is set to the field name. However, you can also set the instance name:</p> |
| <div class="codehilite"><pre><span class="c1">// Declare an instance of MyComponent named hello</span> |
| <span class="n">Instance</span> <span class="n">myInstance2</span> <span class="o">=</span> <span class="n">instance</span><span class="o">().</span><span class="na">of</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="o">.</span><span class="na">named</span><span class="o">(</span><span class="s">"hello"</span><span class="o">)</span> |
| <span class="o">.</span><span class="na">with</span><span class="o">(</span><span class="s">"property"</span><span class="o">).</span><span class="na">setto</span><span class="o">(</span><span class="s">"value"</span><span class="o">);</span> |
| </pre></div> |
| |
| |
| <p>Using this configuration DSL allows creating a set of instances that you can configure easily.</p> |
| <h2 id="configuration-including-lists-and-maps">Configuration including lists and maps<a class="headerlink" href="#configuration-including-lists-and-maps" title="Permanent link">¶</a></h2> |
| <p>The <code>setto</code> method accepts any object. To ease creating collections, the API proposed two methods to handle lists and maps:</p> |
| <div class="codehilite"><pre><span class="n">instance</span><span class="o">()</span> |
| <span class="o">.</span><span class="na">of</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="c1">// Lists </span> |
| <span class="o">.</span><span class="na">with</span><span class="o">(</span><span class="s">"list"</span><span class="o">).</span><span class="na">setto</span><span class="o">(</span><span class="n">list</span><span class="o">(</span><span class="mi">1</span><span class="o">,</span> <span class="mi">2</span><span class="o">,</span> <span class="mi">3</span><span class="o">))</span> |
| <span class="o">.</span><span class="na">with</span><span class="o">(</span><span class="s">"list2"</span><span class="o">).</span><span class="na">setto</span><span class="o">(</span><span class="n">list</span><span class="o">().</span><span class="na">with</span><span class="o">(</span><span class="mi">1</span><span class="o">).</span><span class="na">with</span><span class="o">(</span><span class="mi">2</span><span class="o">).</span><span class="na">with</span><span class="o">(</span><span class="mi">3</span><span class="o">))</span> |
| <span class="c1">// Maps</span> |
| <span class="o">.</span><span class="na">with</span><span class="o">(</span><span class="s">"map"</span><span class="o">).</span><span class="na">setto</span><span class="o">(</span><span class="n">map</span><span class="o">().</span><span class="na">with</span><span class="o">(</span><span class="n">pair</span><span class="o">(</span><span class="s">"entry"</span><span class="o">,</span> <span class="s">"value"</span><span class="o">)))</span> |
| <span class="o">.</span><span class="na">with</span><span class="o">(</span><span class="s">"map2"</span><span class="o">)</span> |
| <span class="o">.</span><span class="na">setto</span><span class="o">(</span><span class="n">map</span><span class="o">()</span> |
| <span class="o">.</span><span class="na">with</span><span class="o">(</span><span class="n">entry</span><span class="o">(</span><span class="s">"key"</span><span class="o">,</span> <span class="mi">1</span><span class="o">),</span> <span class="n">entry</span><span class="o">(</span><span class="s">"key2"</span><span class="o">,</span> <span class="mi">2</span><span class="o">)));</span> |
| </pre></div> |
| |
| |
| <h2 id="methods-returning-instance-objects">Methods returning Instance objects<a class="headerlink" href="#methods-returning-instance-objects" title="Permanent link">¶</a></h2> |
| <p>The class annotated with @Configuration does not only handle fields, but also handles methods returning Instance object. These methods can have either no arguments or the BundleContext as unique argument.</p> |
| <div class="codehilite"><pre><span class="n">Instance</span> <span class="nf">instance1</span><span class="o">()</span> <span class="o">{</span> |
| <span class="k">return</span> <span class="nf">instance</span><span class="o">().</span><span class="na">of</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="o">}</span> |
| |
| <span class="n">Instance</span> <span class="nf">instance2</span><span class="o">(</span><span class="n">BundleContext</span> <span class="n">bc</span><span class="o">)</span> <span class="o">{</span> |
| <span class="k">return</span> <span class="nf">instance</span><span class="o">().</span><span class="na">of</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="o">}</span> |
| </pre></div> |
| |
| |
| <p>As for fields, the method name is used as instance name except if the instance already received a name.</p> |
| <p><em>Note</em>: the injected BundleContext is the BundleContext of the bundle containing the annotated class.</p> |
| <h1 id="declaring-instances-in-xml">Declaring instances in XML<a class="headerlink" href="#declaring-instances-in-xml" title="Permanent link">¶</a></h1> |
| <p>You can declare instances using the iPOJO XML descriptor. If you use XML to describe you component type, you probably want to use this way to create your instances.</p> |
| <div class="codehilite"><pre> <span class="nt"><instance</span> <span class="na">component=</span><span class="s">"factory.name"</span><span class="nt">></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"property"</span> <span class="na">value=</span><span class="s">"value"</span><span class="nt">/></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"another property"</span> <span class="na">value=</span><span class="s">"another value"</span><span class="nt">/></span> |
| <span class="nt"></instance></span> |
| </pre></div> |
| |
| |
| <p>The <em>component</em> attribute specifies the targeted component type. Generally it's the qualified classname of the component class, but can also be the name of the factory if one is specified.</p> |
| <p>The <em>property</em> elements have a mandatory <code>name</code> attribute to set the property name, and a <code>value</code> attribute to specify the String form of the property's value.</p> |
| <p>You can declare as many as you want instances in the XML descriptor. They can targets component types declared within the same bundles or not.</p> |
| <h2 id="setting-the-instance-name">Setting the instance name<a class="headerlink" href="#setting-the-instance-name" title="Permanent link">¶</a></h2> |
| <p>To set the instance name you can use the <em>name</em> attribute of the <em>instance</em> element or the <em>instance.name</em> property:</p> |
| <div class="codehilite"><pre><span class="nt"><instance</span> <span class="na">component=</span><span class="s">"…MyComponent"</span> <span class="na">name=</span><span class="s">"my-instance"</span><span class="nt">/></span> |
| <span class="nt"><instance</span> <span class="na">component=</span><span class="s">"…MyComponent"</span><span class="nt">></span> |
| <span class="nt"><property</span> <span class="na">name=</span><span class="s">"instance.name"</span> <span class="na">value=</span><span class="s">"my-instance-2"</span><span class="nt">/></span> |
| <span class="nt"></instance></span> |
| </pre></div> |
| |
| |
| <h2 id="describing-complex-properties-in-xml">Describing complex properties in XML<a class="headerlink" href="#describing-complex-properties-in-xml" title="Permanent link">¶</a></h2> |
| <p>The <em>property</em> element can be used to configure complex types such as arrays, lists and maps.</p> |
| <div class="codehilite"><pre><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 contain 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> |
| </pre></div> |
| |
| |
| <h1 id="creating-instances-using-the-factory-service">Creating instances using the Factory service<a class="headerlink" href="#creating-instances-using-the-factory-service" title="Permanent link">¶</a></h1> |
| <p>In previous technics to create instances were declarative. You declare an instance. This instance is going to be created as soon as the component type becomes available, and disappears as soon as the component type leaves. The technic presented here is a programatic way.</p> |
| <p>Each (non private) component types are exposed as an OSGi service. You can use this OSGi service to create, reconfigure and dispose instances from your code.</p> |
| <h2 id="the-factory-service">The Factory service<a class="headerlink" href="#the-factory-service" title="Permanent link">¶</a></h2> |
| <p>The published service interface is <code>[org.apache.felix.ipojo.Factory](http://felix.apache.org/ipojo/api/1.12.1/org/apache/felix/ipojo/Factory.html)</code> and provides the following methods:</p> |
| <div class="codehilite"><pre><span class="cm">/**</span> |
| <span class="cm"> * Creates an instance manager (i.e. component type instance).</span> |
| <span class="cm"> * @param configuration the configuration properties for this component.</span> |
| <span class="cm"> * @return the created instance manager.</span> |
| <span class="cm"> * @throws UnacceptableConfiguration if the given configuration is not valid.</span> |
| <span class="cm"> * @throws MissingHandlerException if an handler is missing.</span> |
| <span class="cm"> * @throws ConfigurationException if the instance configuration failed.</span> |
| <span class="cm"> */</span> |
| <span class="n">ComponentInstance</span> <span class="nf">createComponentInstance</span><span class="o">(</span><span class="n">Dictionary</span> <span class="n">configuration</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">UnacceptableConfiguration</span><span class="o">,</span> <span class="n">MissingHandlerException</span><span class="o">,</span> <span class="n">ConfigurationException</span><span class="o">;</span> |
| |
| <span class="cm">/**</span> |
| <span class="cm"> * Reconfigures an instance already created. This configuration needs to</span> |
| <span class="cm"> * have the name property to identify the instance.</span> |
| <span class="cm"> * @param conf the configuration to reconfigure the instance. The instance.name property must be set to identify the instance to reconfigure.</span> |
| <span class="cm"> * @throws UnacceptableConfiguration if the given configuration is not consistent for the targeted instance.</span> |
| <span class="cm"> * @throws MissingHandlerException if an handler is missing.</span> |
| <span class="cm"> */</span> |
| <span class="kt">void</span> <span class="nf">reconfigure</span><span class="o">(</span><span class="n">Dictionary</span> <span class="n">conf</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">UnacceptableConfiguration</span><span class="o">,</span> <span class="n">MissingHandlerException</span><span class="o">;</span> |
| </pre></div> |
| |
| |
| <p>You can identify the factory using the <em>factory.name</em>. So target a specific component type, use the following filter:</p> |
| <div class="codehilite"><pre> <span class="o">(</span>factory.name<span class="o">=</span>...MyComponent<span class="o">)</span> |
| </pre></div> |
| |
| |
| <p>If you grab all factories, you can check their names using the <code>getName()</code> method.</p> |
| <h2 id="creating-instances_1">Creating instances<a class="headerlink" href="#creating-instances_1" title="Permanent link">¶</a></h2> |
| <p>Once you have the right Factory service, you can create instances using <code>createComponentInstance</code> method. This method returns a reference on the created instance. This method receives an optional configuration containing key-value pairs. Values are either objects (of the adequate type) or Strings used to create objects. This configuration can be 'null' if no properties have to be pushed.</p> |
| <p>You can set the instance name using the 'instance.name' property can be used to specify the instance name.</p> |
| <p>Instances are automatically started when created. However, the instance can be invalid, if at least one handler is not valid. </p> |
| <p>The instance creation process can fail. Three exceptions can be thrown during the creation:</p> |
| <ul> |
| <li><code>UnacceptableConfiguration</code> means that mandatory properties are missing in the instance configuration</li> |
| <li><code>MissingHandlerException</code> means that the factory is not valid (i.e. an external handler is missing)</li> |
| <li><code>ConfigurationException</code> 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.</p> |
| <p>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> |
| |
| |
| <h2 id="disposing-created-instance">Disposing created instance<a class="headerlink" href="#disposing-created-instance" title="Permanent link">¶</a></h2> |
| <p>You can only disposed instances that you created. To dispose an instance, just call the <code>dispose</code> 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> |
| |
| |
| <h2 id="reconfiguring-instance">Reconfiguring instance<a class="headerlink" href="#reconfiguring-instance" title="Permanent link">¶</a></h2> |
| <p>To reconfigure an instance, call the 'reconfigure' method on the ComponentInstance object. This method receives the new set of properties. Be aware that the 'instance.name' 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> |
| |
| |
| <h2 id="following-the-factory-state">Following the factory state<a class="headerlink" href="#following-the-factory-state" title="Permanent link">¶</a></h2> |
| <p>Factories can becomes invalid if one of the handler they require is not available. Basically, handlers are pieces of iPOJO containers. </p> |
| <p>You can check the factory state using the <code>Factory.getState()</code> method. This method returns <code>1</code> if the factory is valid, <code>0</code> if not.</p> |
| <p>You can also register a <code>org.apache.felix.ipojo.FactoryStateListener</code> object on the factory to be notified of the changes.</p> |
| <h1 id="creating-instances-using-the-osgi-configuration-admin">Creating instances using the OSGi Configuration Admin<a class="headerlink" href="#creating-instances-using-the-osgi-configuration-admin" title="Permanent link">¶</a></h1> |
| <p>The configuration admin service is a standard service specified by the OSGi Alliance to handle configurations. It allows an operator to configured the deployed bundles, and so iPOJO instances. </p> |
| <p>iPOJO supports the configuration admin and you can create, reconfigure and dispose instanced using this service.</p> |
| <h2 id="creating-instances_2">Creating instances<a class="headerlink" href="#creating-instances_2" title="Permanent link">¶</a></h2> |
| <p>Creating an instance is done by creating a <em>factory</em> configuration:</p> |
| <div class="codehilite"><pre><span class="n">ConfigurationAdmin</span> <span class="n">admin</span> <span class="o">=</span> <span class="o">...</span><span class="c1">// Let's assume with have the configuration admin</span> |
| <span class="n">Configuration</span> <span class="n">conf</span> <span class="o">=</span> <span class="n">admin</span><span class="o">.</span><span class="na">createFactoryConfiguration</span><span class="o">(</span><span class="s">"...MyComponent"</span><span class="o">,</span> <span class="s">"?"</span><span class="o">);</span> |
| |
| <span class="c1">// Build the instance configuration</span> |
| <span class="n">Dictionary</span> <span class="n">dict</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Hashtable</span><span class="o">();</span> |
| <span class="c1">//...</span> |
| |
| <span class="c1">// Push the configuration to the configuration admin</span> |
| <span class="n">conf</span><span class="o">.</span><span class="na">update</span><span class="o">(</span><span class="n">dict</span><span class="o">);</span> |
| </pre></div> |
| |
| |
| <p>To create the <em>factory</em> configuration, use the <code>createFactoryConfiguration</code> method on the Configuration Admin object. The first argument is the factory name. The second is the location binding. Using "?" is a wildcard, for more details, check the configuration admin specification.</p> |
| <p>You populate this configuration with a dictionary. The configuration is actually created using the <code>update</code> method. </p> |
| <h2 id="reconfiguring-instances">Reconfiguring instances<a class="headerlink" href="#reconfiguring-instances" title="Permanent link">¶</a></h2> |
| <p>If the instance was created using the Configuration Admin and you own the Configuration object used for the creation, the reconfiguration is done by calling the <code>update</code> method with the new properties.</p> |
| <p>If the instance was already created, you can configure it using a <em>regular</em> configuration. The pid given to this configuration is the instance name.</p> |
| <h2 id="disposing-instances">Disposing instances<a class="headerlink" href="#disposing-instances" title="Permanent link">¶</a></h2> |
| <p>To dispose an instance, just call the <code>delete</code> method on the configuration object you used to configure the instance.</p> |
| <h1 id="creating-instances-with-declarations">Creating instances with declarations<a class="headerlink" href="#creating-instances-with-declarations" title="Permanent link">¶</a></h1> |
| <p>Declarations offer a nice way to declares instances in a programmatic way. If not retracted by hand, |
| they're bound to the declaring bundle lifecycle (i.e. are unregistered when the bundle is not <code>ACTIVE</code> |
| anymore).</p> |
| <p>Declarations can be build using the <code>DeclarationBuilderService</code> (see interface below). Instances (of |
| components), types (components) and iPOJO extensions can also be build using this service.</p> |
| <div class="codehilite"><pre><span class="kd">public</span> <span class="kd">interface</span> <span class="nc">DeclarationBuilderService</span> <span class="o">{</span> |
| <span class="n">InstanceBuilder</span> <span class="nf">newInstance</span><span class="o">(</span><span class="n">String</span> <span class="n">type</span><span class="o">);</span> |
| <span class="n">InstanceBuilder</span> <span class="nf">newInstance</span><span class="o">(</span><span class="n">String</span> <span class="n">type</span><span class="o">,</span> <span class="n">String</span> <span class="n">name</span><span class="o">);</span> |
| <span class="n">InstanceBuilder</span> <span class="nf">newInstance</span><span class="o">(</span><span class="n">String</span> <span class="n">type</span><span class="o">,</span> <span class="n">String</span> <span class="n">name</span><span class="o">,</span> <span class="n">String</span> <span class="n">version</span><span class="o">);</span> |
| <span class="n">DeclarationHandle</span> <span class="nf">newExtension</span><span class="o">(</span><span class="n">String</span> <span class="n">name</span><span class="o">,</span> <span class="n">FactoryBuilder</span> <span class="n">builder</span><span class="o">);</span> |
| <span class="n">DeclarationHandle</span> <span class="nf">newType</span><span class="o">(</span><span class="n">Element</span> <span class="n">description</span><span class="o">);</span> |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>Instances created through declaration can indeed be configured.</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>The builder ultimately produces handles to declarations. Handles are the live link to the underlying |
| declarations: service publication and un-registration are done through the <code>handle.publish()</code> and |
| <code>handle.retract()</code> methods. Declaration status (is it bound or not) is also accessible with <code>handle.getStatus()</code>.</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> |
