| <!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 - apache-felix-ipojo-api</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-api">iPOJO API<a class="headerlink" href="#ipojo-api" title="Permanent link">¶</a></h1> |
| <p><em>The iPOJO API provides a third way to describe iPOJO components and instances. With the API, you can dynamically create new components types and create instances from them. Your component types are described with a Java API. To use the API, deploy and start the iPOJO-API bundle and the iPOJO core bundle.</em></p> |
| <div class="toc"> |
| <ul> |
| <li><a href="#ipojo-api">iPOJO API</a><ul> |
| <li><a href="#a-simple-example">A simple example</a></li> |
| <li><a href="#deploying-the-api">Deploying the API</a></li> |
| <li><a href="#primitive-component-type-basics">Primitive Component Type basics</a></li> |
| <li><a href="#immediate-component-validate-and-invalidate-method">Immediate Component, Validate and Invalidate Method</a></li> |
| <li><a href="#declaring-services">Declaring services</a></li> |
| <li><a href="#service-dependencies">Service Dependencies</a></li> |
| <li><a href="#properties">Properties</a></li> |
| <li><a href="#temporal-dependencies">Temporal Dependencies</a></li> |
| <li><a href="#instance-creation">Instance creation</a></li> |
| <li><a href="#managed-service-and-propagation">Managed Service and Propagation</a></li> |
| <li><a href="#managing-ipojo-factory">Managing iPOJO Factory</a></li> |
| <li><a href="#access-to-the-introspection-api">Access to the introspection API</a></li> |
| <li><a href="#singleton-component-type">Singleton Component Type</a></li> |
| <li><a href="#using-external-handlers">Using external handlers</a></li> |
| <li><a href="#creating-compositions-with-the-api">Creating compositions with the API</a><ul> |
| <li><a href="#creating-instances-inside-a-composite">Creating instances inside a composite:</a></li> |
| <li><a href="#importing-a-service">Importing a service</a></li> |
| <li><a href="#instantiating-a-service">Instantiating a service</a></li> |
| <li><a href="#exporting-a-service">Exporting a service</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </div> |
| <h2 id="a-simple-example">A simple example<a class="headerlink" href="#a-simple-example" title="Permanent link">¶</a></h2> |
| <p>Let's imagine a simple component providing a service Foo. The following code is the implementation class of our component:</p> |
| <div class="codehilite"><pre><span class="kn">package</span> <span class="n">org</span><span class="o">.</span><span class="na">example</span><span class="o">.</span><span class="na">service</span><span class="o">.</span><span class="na">impl</span><span class="o">;</span> |
| |
| <span class="kn">import</span> <span class="nn">org.example.service.Foo</span><span class="o">;</span> |
| |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">FooImpl</span> <span class="kd">implements</span> <span class="n">Foo</span> <span class="o">{</span> |
| |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">doSomething</span><span class="o">()</span> <span class="o">{</span> |
| <span class="c1">// Do something...</span> |
| <span class="o">}</span> |
| |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>To create the component type and an instance of the component type just create a class, get the bundle context (either from a Bundle-Activator, or from an iPOJO component), and write the following code:</p> |
| <div class="codehilite"><pre><span class="k">new</span> <span class="nf">PrimitiveComponentType</span><span class="o">()</span> |
| <span class="o">.</span><span class="na">setBundleContext</span><span class="o">(</span><span class="n">context</span><span class="o">)</span> |
| <span class="o">.</span><span class="na">setClassName</span><span class="o">(</span><span class="n">FooImpl</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="o">.</span><span class="na">addService</span><span class="o">(</span><span class="k">new</span> <span class="n">Service</span><span class="o">())</span> <span class="c1">// Provide the Foo service</span> |
| <span class="o">.</span><span class="na">createInstance</span><span class="o">();</span> <span class="c1">// Create the instance</span> |
| </pre></div> |
| |
| |
| <p>So, now let's imagine another component using this service. The following code is the implementation class of this component type:</p> |
| <div class="codehilite"><pre><span class="kn">package</span> <span class="n">org</span><span class="o">.</span><span class="na">example</span><span class="o">.</span><span class="na">service</span><span class="o">.</span><span class="na">impl</span><span class="o">;</span> |
| |
| <span class="kn">import</span> <span class="nn">org.example.service.Foo</span><span class="o">;</span> |
| |
| <span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyComponentImpl</span> <span class="o">{</span> |
| <span class="kd">private</span> <span class="n">Foo</span> <span class="n">myFoo</span><span class="o">;</span> |
| |
| <span class="kd">public</span> <span class="kt">void</span> <span class="nf">start</span><span class="o">()</span> <span class="o">{</span> |
| <span class="n">myFoo</span><span class="o">.</span><span class="na">doSomething</span><span class="o">();</span> |
| <span class="o">}</span> |
| |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>It is a regular iPOJO component expecting to get a Foo service in the <code>myFoo</code> field. It also has a method executed when the instance is valid using the Foo service. To describe this component, just write the following lines:</p> |
| <div class="codehilite"><pre><span class="k">new</span> <span class="nf">PrimitiveComponentType</span><span class="o">()</span> |
| <span class="o">.</span><span class="na">setBundleContext</span><span class="o">(</span><span class="n">context</span><span class="o">)</span> |
| <span class="o">.</span><span class="na">setClassName</span><span class="o">(</span><span class="n">MyComponentImpl</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="o">.</span><span class="na">addDependency</span><span class="o">(</span><span class="k">new</span> <span class="n">Dependency</span><span class="o">().</span><span class="na">setField</span><span class="o">(</span><span class="s">"myFoo"</span><span class="o">))</span> |
| <span class="o">.</span><span class="na">setValidateMethod</span><span class="o">(</span><span class="s">"start"</span><span class="o">)</span> |
| <span class="o">.</span><span class="na">createInstance</span><span class="o">();</span> |
| </pre></div> |
| |
| |
| <h2 id="deploying-the-api">Deploying the API<a class="headerlink" href="#deploying-the-api" title="Permanent link">¶</a></h2> |
| <p>Before being able to create component types at runtime, you need to deploy 3 bundles:</p> |
| <ul> |
| <li>iPOJO (core)</li> |
| <li>iPOJO Composite</li> |
| <li>iPOJO API</li> |
| </ul> |
| <h2 id="primitive-component-type-basics">Primitive Component Type basics<a class="headerlink" href="#primitive-component-type-basics" title="Permanent link">¶</a></h2> |
| <p>When you create a new Primitive component type (so, using a Java class as implementation), you must set the bundle context and the class name. Everything else is optional. </p> |
| <p>Note about inner classes: iPOJO is based on a bytecode manipulation. The API embeds the manipulator. So, when you initialize the component type, the specified class name is manipulated (if not already manipulated). So, as this force using a customized classloader, inner classes cannot be manipulated. So, inner class injection is not supported with the API.</p> |
| <h2 id="immediate-component-validate-and-invalidate-method">Immediate Component, Validate and Invalidate Method<a class="headerlink" href="#immediate-component-validate-and-invalidate-method" title="Permanent link">¶</a></h2> |
| <p>To set the component type as immediate, just call the <code>setImmediate(immediate)</code> method on the primitive component type object. |
| To set validate and invalidate methods, just call the <code>setValidate(method)</code> and <code>setInvalidate(method)</code>. Specify the method name that you want to call in argument. </p> |
| <h2 id="declaring-services">Declaring services<a class="headerlink" href="#declaring-services" title="Permanent link">¶</a></h2> |
| <p>To declare that a component provides a service, add a new service to your primitive component type. |
| The Service object can be configured. By default, it exposed every implemented interface (regular iPOJO behavior). So, you can:</p> |
| <ul> |
| <li>Add service property</li> |
| <li>Set the creation strategy</li> |
| <li> |
| <p>Set the exposed service specifications</p> |
| <p>:::java |
| new PrimitiveComponentType() |
| .setBundleContext(context) |
| .setClassName(org.example.service.impl.MyComponentImpl.class.getName()) |
| .addService(new Service() |
| .addProperty(new ServiceProperty() |
| .setField("myServiceProperty") |
| .setName("sample.myProperty")) |
| .setCreationStrategy(Service.INSTANCE_STRATEGY)) |
| .createInstance();</p> |
| </li> |
| </ul> |
| <h2 id="service-dependencies">Service Dependencies<a class="headerlink" href="#service-dependencies" title="Permanent link">¶</a></h2> |
| <p>To declare a service dependency, create and add a Dependency object. The dependency object offers all the iPOJO service dependency features. You can set the injected field and/or bind/unbind methods. Here is an example:</p> |
| <div class="codehilite"><pre><span class="k">new</span> <span class="nf">PrimitiveComponentType</span><span class="o">()</span> |
| <span class="o">.</span><span class="na">setBundleContext</span><span class="o">(</span><span class="n">context</span><span class="o">)</span> |
| <span class="o">.</span><span class="na">setClassName</span><span class="o">(</span><span class="n">org</span><span class="o">.</span><span class="na">example</span><span class="o">.</span><span class="na">service</span><span class="o">.</span><span class="na">impl</span><span class="o">.</span><span class="na">MyComponentImpl</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="o">.</span><span class="na">addDependency</span><span class="o">(</span> |
| <span class="k">new</span> <span class="nf">Dependency</span><span class="o">().</span><span class="na">setField</span><span class="o">(</span><span class="s">"myFoo"</span><span class="o">)</span> |
| <span class="o">.</span><span class="na">setOptional</span><span class="o">(</span><span class="kc">true</span><span class="o">)</span> |
| <span class="o">.</span><span class="na">setDefaultImplementation</span><span class="o">(</span><span class="s">"org.sample.FooDefaultImplementation"</span><span class="o">)</span> |
| <span class="o">)</span> |
| <span class="o">.</span><span class="na">createInstance</span><span class="o">();</span> |
| </pre></div> |
| |
| |
| <h2 id="properties">Properties<a class="headerlink" href="#properties" title="Permanent link">¶</a></h2> |
| <p>Thanks to the <code>addProperty</code> method, you can create component properties. Here is some example of properties:</p> |
| <div class="codehilite"><pre><span class="k">new</span> <span class="nf">PrimitiveComponentType</span><span class="o">()</span> |
| <span class="o">.</span><span class="na">setBundleContext</span><span class="o">(</span><span class="n">context</span><span class="o">)</span> |
| <span class="o">.</span><span class="na">setClassName</span><span class="o">(</span><span class="n">MyComponentImpl</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="o">.</span><span class="na">addProperty</span><span class="o">(</span><span class="k">new</span> <span class="n">Property</span><span class="o">()</span> |
| <span class="o">.</span><span class="na">setField</span><span class="o">(</span><span class="s">"myProperty"</span><span class="o">)</span> |
| <span class="o">.</span><span class="na">setValue</span><span class="o">(</span><span class="s">"default-value"</span><span class="o">)</span> |
| <span class="o">)</span> |
| <span class="o">.</span><span class="na">addProperty</span><span class="o">(</span><span class="k">new</span> <span class="n">Property</span><span class="o">()</span> |
| <span class="o">.</span><span class="na">setMethod</span><span class="o">(</span><span class="s">"setMethod"</span><span class="o">)</span> |
| <span class="o">.</span><span class="na">setName</span><span class="o">(</span><span class="s">"prop"</span><span class="o">)</span> |
| <span class="o">)</span> |
| <span class="o">.</span><span class="na">createInstance</span><span class="o">();</span> |
| </pre></div> |
| |
| |
| <h2 id="temporal-dependencies">Temporal Dependencies<a class="headerlink" href="#temporal-dependencies" title="Permanent link">¶</a></h2> |
| <p>Temporal dependencies are also supported: </p> |
| <div class="codehilite"><pre><span class="k">new</span> <span class="nf">PrimitiveComponentType</span><span class="o">()</span> |
| <span class="o">.</span><span class="na">setBundleContext</span><span class="o">(</span><span class="n">context</span><span class="o">)</span> |
| <span class="o">.</span><span class="na">setClassName</span><span class="o">(</span><span class="n">MyComponentImpl</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="o">.</span><span class="na">addDependency</span><span class="o">(</span> |
| <span class="k">new</span> <span class="nf">TemporalDependency</span><span class="o">().</span><span class="na">setField</span><span class="o">(</span><span class="s">"myFoo"</span><span class="o">)</span> |
| <span class="o">.</span><span class="na">setOnTimeoutPolicy</span><span class="o">(</span><span class="n">TemporalDependency</span><span class="o">.</span><span class="na">NULLABLE</span><span class="o">)</span> |
| <span class="o">.</span><span class="na">setTimeout</span><span class="o">(</span><span class="mi">3000</span><span class="o">)</span> |
| <span class="o">.</span><span class="na">setProxy</span><span class="o">(</span><span class="kc">true</span><span class="o">)</span> |
| <span class="o">)</span> |
| <span class="o">.</span><span class="na">createInstance</span><span class="o">();</span> |
| </pre></div> |
| |
| |
| <h2 id="instance-creation">Instance creation<a class="headerlink" href="#instance-creation" title="Permanent link">¶</a></h2> |
| <p>The API allows you to create instances from the component type you described. Three differents methods. |
| The <code>createInstance()</code> method just creates an instance. The <code>createInstance(String name)</code> method allows to set the instance name. Finally, the <code>createInstance(Dictionary configuration)</code> allows setting the instance configuration. All those methods returns the ComponentInstance object allowing to manage the instance (stop, start, dispose). </p> |
| <h2 id="managed-service-and-propagation">Managed Service and Propagation<a class="headerlink" href="#managed-service-and-propagation" title="Permanent link">¶</a></h2> |
| <p>You can enable/disable the property propagation thanks to the <code>setPropagation</code> method on the PrimitiveComponentType object. |
| You can also set the the managed service PID with the <code>setManagedServicePID</code> method. This method should be only use to give a default value of for singleton component. In all other case, the managed service pid has to be provided inside the instance configuration.</p> |
| <h2 id="managing-ipojo-factory">Managing iPOJO Factory<a class="headerlink" href="#managing-ipojo-factory" title="Permanent link">¶</a></h2> |
| <p>Beyond the PrimitiveComponentType, an iPOJO factory is hidden. You can configure this factory to be public or private with the <code>setPublic</code> method. You can also set the name of the factory with the <code>setName</code> method. </p> |
| <p>Then, you can access to the Factory object by calling the <code>getFactory</code> method.</p> |
| <h2 id="access-to-the-introspection-api">Access to the introspection API<a class="headerlink" href="#access-to-the-introspection-api" title="Permanent link">¶</a></h2> |
| <p>The API provides bridge to get access to the iPOJO introspection API. The introspection API allows reconfiguring at runtime an instance (properties, service dependencies...). From Service and Dependency, Property and ServiceProperty objects, call the <code>getXXXDescription</code> method. You must give the instance that you want to introspect in argument. If the lookup success, you get an object allowing reconfiguring the service, dependency or property. </p> |
| <h2 id="singleton-component-type">Singleton Component Type<a class="headerlink" href="#singleton-component-type" title="Permanent link">¶</a></h2> |
| <p>If you are sure to create only one instance of your component type, you can use the singleton component type class. This is a kind of primitive component type, but when you start it (with the <code>create</code> method), it will automatically create an instance.</p> |
| <div class="codehilite"><pre> <span class="n">PrimitiveComponentType</span> <span class="n">type</span> <span class="o">=</span> <span class="k">new</span> <span class="n">SingletonComponentType</span><span class="o">()</span> |
| <span class="o">.</span><span class="na">setBundleContext</span><span class="o">(</span><span class="n">context</span><span class="o">)</span> |
| <span class="o">.</span><span class="na">setClassName</span><span class="o">(</span><span class="n">org</span><span class="o">.</span><span class="na">example</span><span class="o">.</span><span class="na">service</span><span class="o">.</span><span class="na">impl</span><span class="o">.</span><span class="na">MyComponentImpl</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="o">.</span><span class="na">addDependency</span><span class="o">(</span><span class="k">new</span> <span class="n">Dependency</span><span class="o">().</span><span class="na">setField</span><span class="o">(</span><span class="s">"myFoo"</span><span class="o">))</span> |
| <span class="o">.</span><span class="na">setValidateMethod</span><span class="o">(</span><span class="s">"start"</span><span class="o">);</span> |
| |
| <span class="o">((</span><span class="n">SingletonComponentType</span><span class="o">)</span> <span class="n">type</span><span class="o">)</span> |
| <span class="o">.</span><span class="na">setObject</span><span class="o">(</span><span class="k">new</span> <span class="n">MyComponentImpl</span><span class="o">(</span><span class="mi">5</span><span class="o">))</span> <span class="c1">// Inject a pojo object</span> |
| <span class="o">.</span><span class="na">create</span><span class="o">();</span><span class="c1">// Create an instance</span> |
| </pre></div> |
| |
| |
| <p>The type created with the singleton component type are set to <code>private</code> by default. Instead of calling the <code>start</code> method, you have to call one of the <code>create</code> methods to start the type and create the instance.</p> |
| <p>You can also set the contained POJO object by using the <code>setObject</code> method. The given object MUST be compatible with the component implementation class.</p> |
| <h2 id="using-external-handlers">Using external handlers<a class="headerlink" href="#using-external-handlers" title="Permanent link">¶</a></h2> |
| <p>iPOJO is extensible... So, it makes sense that the API is also extensible. So component type provides a method allowing to add external handler configuration:</p> |
| <div class="codehilite"><pre><span class="k">return</span> <span class="k">new</span> <span class="nf">PrimitiveComponentType</span><span class="o">()</span> |
| <span class="o">.</span><span class="na">setBundleContext</span><span class="o">(</span><span class="n">context</span><span class="o">)</span> |
| <span class="o">.</span><span class="na">setClassName</span><span class="o">(</span><span class="n">HostImpl</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="o">.</span><span class="na">addHandler</span><span class="o">(</span><span class="k">new</span> <span class="n">Whiteboard</span><span class="o">()</span> |
| <span class="o">.</span><span class="na">onArrival</span><span class="o">(</span><span class="s">"arrival"</span><span class="o">)</span> |
| <span class="o">.</span><span class="na">onDeparture</span><span class="o">(</span><span class="s">"departure"</span><span class="o">)</span> |
| <span class="o">.</span><span class="na">setFilter</span><span class="o">(</span><span class="s">"(foo=foo)"</span><span class="o">)</span> |
| <span class="o">);</span> |
| </pre></div> |
| |
| |
| <p>The <code>addHandler</code> method allows you to add any handler description. A handler description is an object of a class implementing <code>org.apache.felix.ipojo.api.HandlerConfiguration</code>. Handler provider willing to support the API have to provide this class. For example, the example above uses <code>Whiteboard</code> that is the Whiteboard pattern handler description. This class is very simple, and is shown below:</p> |
| <div class="codehilite"><pre><span class="kd">public</span> <span class="kd">class</span> <span class="nc">Whiteboard</span> <span class="kd">implements</span> <span class="n">HandlerConfiguration</span> <span class="o">{</span> |
| |
| <span class="kd">public</span> <span class="kd">static</span> <span class="kd">final</span> <span class="n">String</span> <span class="n">NAME</span> <span class="o">=</span> <span class="s">"wbp"</span><span class="o">;</span> |
| |
| <span class="kd">public</span> <span class="kd">static</span> <span class="kd">final</span> <span class="n">String</span> <span class="n">NAMESPACE</span> <span class="o">=</span> <span class="s">"org.apache.felix.ipojo.whiteboard"</span><span class="o">;</span> |
| |
| <span class="kd">private</span> <span class="n">String</span> <span class="n">arrival</span><span class="o">;</span> |
| |
| <span class="kd">private</span> <span class="n">String</span> <span class="n">departure</span><span class="o">;</span> |
| |
| <span class="kd">private</span> <span class="n">String</span> <span class="n">modification</span><span class="o">;</span> |
| |
| <span class="kd">private</span> <span class="n">String</span> <span class="n">filter</span><span class="o">;</span> |
| |
| <span class="kd">public</span> <span class="n">Whiteboard</span> <span class="nf">onArrival</span><span class="o">(</span><span class="n">String</span> <span class="n">method</span><span class="o">)</span> <span class="o">{</span> |
| <span class="n">arrival</span> <span class="o">=</span> <span class="n">method</span><span class="o">;</span> |
| <span class="k">return</span> <span class="k">this</span><span class="o">;</span> |
| <span class="o">}</span> |
| |
| <span class="kd">public</span> <span class="n">Whiteboard</span> <span class="nf">onDeparture</span><span class="o">(</span><span class="n">String</span> <span class="n">method</span><span class="o">)</span> <span class="o">{</span> |
| <span class="n">departure</span> <span class="o">=</span> <span class="n">method</span><span class="o">;</span> |
| <span class="k">return</span> <span class="k">this</span><span class="o">;</span> |
| <span class="o">}</span> |
| |
| <span class="kd">public</span> <span class="n">Whiteboard</span> <span class="nf">onModification</span><span class="o">(</span><span class="n">String</span> <span class="n">method</span><span class="o">)</span> <span class="o">{</span> |
| <span class="n">modification</span> <span class="o">=</span> <span class="n">method</span><span class="o">;</span> |
| <span class="k">return</span> <span class="k">this</span><span class="o">;</span> |
| <span class="o">}</span> |
| |
| <span class="kd">public</span> <span class="n">Whiteboard</span> <span class="nf">setFilter</span><span class="o">(</span><span class="n">String</span> <span class="n">fil</span><span class="o">)</span> <span class="o">{</span> |
| <span class="n">filter</span> <span class="o">=</span> <span class="n">fil</span><span class="o">;</span> |
| <span class="k">return</span> <span class="k">this</span><span class="o">;</span> |
| <span class="o">}</span> |
| |
| <span class="kd">public</span> <span class="n">Element</span> <span class="nf">getElement</span><span class="o">()</span> <span class="o">{</span> |
| <span class="n">ensureValidity</span><span class="o">();</span> |
| <span class="c1">// Create the root element.</span> |
| <span class="n">Element</span> <span class="n">element</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Element</span><span class="o">(</span><span class="n">NAME</span><span class="o">,</span> <span class="n">NAMESPACE</span><span class="o">);</span> |
| <span class="c1">// Mandatory attributes</span> |
| <span class="n">element</span><span class="o">.</span><span class="na">addAttribute</span><span class="o">(</span><span class="k">new</span> <span class="n">Attribute</span><span class="o">(</span><span class="s">"onArrival"</span><span class="o">,</span> <span class="n">arrival</span><span class="o">));</span> |
| <span class="n">element</span><span class="o">.</span><span class="na">addAttribute</span><span class="o">(</span><span class="k">new</span> <span class="n">Attribute</span><span class="o">(</span><span class="s">"onDeparture"</span><span class="o">,</span> <span class="n">departure</span><span class="o">));</span> |
| <span class="n">element</span><span class="o">.</span><span class="na">addAttribute</span><span class="o">(</span><span class="k">new</span> <span class="n">Attribute</span><span class="o">(</span><span class="s">"filter"</span><span class="o">,</span> <span class="n">filter</span><span class="o">));</span> |
| |
| <span class="c1">// Optional attribute</span> |
| <span class="k">if</span> <span class="o">(</span><span class="n">modification</span> <span class="o">!=</span> <span class="kc">null</span><span class="o">)</span> <span class="o">{</span> |
| <span class="n">element</span><span class="o">.</span><span class="na">addAttribute</span><span class="o">(</span><span class="k">new</span> <span class="n">Attribute</span><span class="o">(</span><span class="s">"onModification"</span><span class="o">,</span> <span class="n">modification</span><span class="o">));</span> |
| <span class="o">}</span> |
| |
| <span class="k">return</span> <span class="n">element</span><span class="o">;</span> |
| <span class="o">}</span> |
| |
| <span class="kd">private</span> <span class="kt">void</span> <span class="nf">ensureValidity</span><span class="o">()</span> <span class="o">{</span> |
| <span class="k">if</span> <span class="o">(</span><span class="n">arrival</span> <span class="o">==</span> <span class="kc">null</span><span class="o">)</span> <span class="o">{</span> |
| <span class="k">throw</span> <span class="k">new</span> <span class="nf">IllegalStateException</span><span class="o">(</span><span class="s">"The whiteboard pattern configuration must have a onArrival method"</span><span class="o">);</span> |
| <span class="o">}</span> |
| <span class="k">if</span> <span class="o">(</span><span class="n">departure</span> <span class="o">==</span> <span class="kc">null</span><span class="o">)</span> <span class="o">{</span> |
| <span class="k">throw</span> <span class="k">new</span> <span class="nf">IllegalStateException</span><span class="o">(</span><span class="s">"The whiteboard pattern configuration must have a onDeparture method"</span><span class="o">);</span> |
| <span class="o">}</span> |
| <span class="k">if</span> <span class="o">(</span><span class="n">filter</span> <span class="o">==</span> <span class="kc">null</span><span class="o">)</span> <span class="o">{</span> |
| <span class="k">throw</span> <span class="k">new</span> <span class="nf">IllegalStateException</span><span class="o">(</span><span class="s">"The whiteboard pattern configuration must have a filter"</span><span class="o">);</span> |
| <span class="o">}</span> |
| |
| <span class="o">}</span> |
| </pre></div> |
| |
| |
| <p>The only required method is <code>getElement</code> returning the <code>Element-Attribute</code> structure representing the handler configuration (this uses the internal iPOJO data format). If the metadata cannot be generated, the class throws IllegalStateExceptions.</p> |
| <h2 id="creating-compositions-with-the-api">Creating compositions with the API<a class="headerlink" href="#creating-compositions-with-the-api" title="Permanent link">¶</a></h2> |
| <p>The API also allows you to create iPOJO compositions in a pretty simple way. So you can create compositions:</p> |
| <ul> |
| <li>containing internal instances</li> |
| <li>importing services</li> |
| <li>instantiating sub-services</li> |
| <li>exporting services</li> |
| <li>providing services (by delegation)</li> |
| </ul> |
| <p>Here are some examples:</p> |
| <h4 id="creating-instances-inside-a-composite">Creating instances inside a composite:<a class="headerlink" href="#creating-instances-inside-a-composite" title="Permanent link">¶</a></h4> |
| <div class="codehilite"><pre><span class="n">PrimitiveComponentType</span> <span class="n">prov</span> <span class="o">=</span> <span class="n">createAProvider</span><span class="o">();</span> <span class="c1">// Create a primitive type</span> |
| <span class="n">PrimitiveComponentType</span> <span class="n">cons</span> <span class="o">=</span> <span class="n">createAConsumer</span><span class="o">();</span> <span class="c1">// Create another primitive type</span> |
| |
| <span class="n">CompositeComponentType</span> <span class="n">type</span> <span class="o">=</span> <span class="k">new</span> <span class="n">CompositeComponentType</span><span class="o">()</span> |
| <span class="o">.</span><span class="na">setBundleContext</span><span class="o">(</span><span class="n">context</span><span class="o">)</span> |
| <span class="o">.</span><span class="na">setComponentTypeName</span><span class="o">(</span><span class="s">"comp1"</span><span class="o">)</span> |
| <span class="o">.</span><span class="na">addInstance</span><span class="o">(</span><span class="k">new</span> <span class="n">Instance</span><span class="o">(</span><span class="n">prov</span><span class="o">.</span><span class="na">getFactory</span><span class="o">().</span><span class="na">getName</span><span class="o">()))</span> <span class="c1">// Create an instance in the composite</span> |
| <span class="o">.</span><span class="na">addInstance</span><span class="o">(</span><span class="k">new</span> <span class="n">Instance</span><span class="o">(</span><span class="n">cons</span><span class="o">.</span><span class="na">getFactory</span><span class="o">().</span><span class="na">getName</span><span class="o">()));</span> |
| |
| <span class="n">ComponentInstance</span> <span class="n">ci</span> <span class="o">=</span> <span class="n">type</span><span class="o">.</span><span class="na">createInstance</span><span class="o">();</span> |
| </pre></div> |
| |
| |
| <h4 id="importing-a-service">Importing a service<a class="headerlink" href="#importing-a-service" title="Permanent link">¶</a></h4> |
| <div class="codehilite"><pre><span class="n">CompositeComponentType</span> <span class="n">type</span> <span class="o">=</span> <span class="k">new</span> <span class="n">CompositeComponentType</span><span class="o">()</span> |
| <span class="o">.</span><span class="na">setBundleContext</span><span class="o">(</span><span class="n">context</span><span class="o">)</span> |
| <span class="o">.</span><span class="na">setComponentTypeName</span><span class="o">(</span><span class="s">"comp3"</span><span class="o">)</span> |
| <span class="o">.</span><span class="na">addSubService</span><span class="o">(</span><span class="k">new</span> <span class="n">ImportedService</span><span class="o">()</span> <span class="c1">// Importation</span> |
| <span class="o">.</span><span class="na">setSpecification</span><span class="o">(</span><span class="n">Foo</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="o">.</span><span class="na">setOptional</span><span class="o">(</span><span class="kc">true</span><span class="o">));</span> |
| </pre></div> |
| |
| |
| <h4 id="instantiating-a-service">Instantiating a service<a class="headerlink" href="#instantiating-a-service" title="Permanent link">¶</a></h4> |
| <div class="codehilite"><pre><span class="n">CompositeComponentType</span> <span class="n">type</span> <span class="o">=</span> <span class="k">new</span> <span class="n">CompositeComponentType</span><span class="o">()</span> |
| <span class="o">.</span><span class="na">setBundleContext</span><span class="o">(</span><span class="n">context</span><span class="o">)</span> |
| <span class="o">.</span><span class="na">setComponentTypeName</span><span class="o">(</span><span class="s">"comp2"</span><span class="o">)</span> |
| <span class="o">.</span><span class="na">addSubService</span><span class="o">(</span><span class="k">new</span> <span class="n">InstantiatedService</span><span class="o">()</span> <span class="c1">// Instantiated service</span> |
| <span class="o">.</span><span class="na">setSpecification</span><span class="o">(</span><span class="n">Foo</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="o">.</span><span class="na">addInstance</span><span class="o">(</span><span class="k">new</span> <span class="n">Instance</span><span class="o">(</span><span class="n">cons</span><span class="o">.</span><span class="na">getFactory</span><span class="o">().</span><span class="na">getName</span><span class="o">()));</span> |
| </pre></div> |
| |
| |
| <h4 id="exporting-a-service">Exporting a service<a class="headerlink" href="#exporting-a-service" title="Permanent link">¶</a></h4> |
| <div class="codehilite"><pre><span class="n">CompositeComponentType</span> <span class="n">type</span> <span class="o">=</span> <span class="k">new</span> <span class="n">CompositeComponentType</span><span class="o">()</span> |
| <span class="o">.</span><span class="na">setBundleContext</span><span class="o">(</span><span class="n">context</span><span class="o">)</span> |
| <span class="o">.</span><span class="na">setComponentTypeName</span><span class="o">(</span><span class="s">"compExport"</span><span class="o">)</span> |
| <span class="o">.</span><span class="na">addSubService</span><span class="o">(</span><span class="k">new</span> <span class="n">InstantiatedService</span><span class="o">().</span><span class="na">setSpecification</span><span class="o">(</span><span class="n">Foo</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="o">.</span><span class="na">addService</span><span class="o">(</span><span class="k">new</span> <span class="n">ExportedService</span><span class="o">()</span> |
| <span class="o">.</span><span class="na">setSpecification</span><span class="o">(</span><span class="n">Foo</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="c1">// Exports a service</span> |
| </pre></div> |
| </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> |
