blob: 972d8a273ad6359001587af5fec1b12c9e665eb3 [file] [log] [blame]
<!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 - Configuring iPOJO Extender</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 &amp; 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="configuring-ipojo-extender">Configuring iPOJO Extender<a class="headerlink" href="#configuring-ipojo-extender" title="Permanent link">&para;</a></h1>
<p><em>This page presents how the iPOJO's extender can be configured.</em></p>
<div class="toc">
<ul>
<li><a href="#configuring-ipojo-extender">Configuring iPOJO Extender</a><ul>
<li><a href="#extender">Extender</a><ul>
<li><a href="#threadpool">ThreadPool</a></li>
<li><a href="#synchronous-asynchronous-processing">Synchronous / Asynchronous processing</a><ul>
<li><a href="#system-wide">System wide</a></li>
<li><a href="#per-bundle">Per-Bundle</a></li>
</ul>
</li>
<li><a href="#queueservice-insights">QueueService Insights</a></li>
<li><a href="#event-dispatcher">Event Dispatcher</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<h2 id="extender">Extender<a class="headerlink" href="#extender" title="Permanent link">&para;</a></h2>
<p>The iPOJO Extender starts with the iPOJO bundle (in fact, it's the iPOJO's <code>BundleActivator</code>). It is basically a <code>BundleTracker</code> that will discover iPOJO's components, instances, etc from the <code>ACTIVE</code> bundles.</p>
<h3 id="threadpool">ThreadPool<a class="headerlink" href="#threadpool" title="Permanent link">&para;</a></h3>
<p>In Apache Felix iPOJO 1.10, the extender has been refactored to take advantage of multi-threading capabilities of modern machines.
There is now an <code>ExecutorQueueService</code> service, based on a <code>ThreadPoolExecutor</code> that enable asynchronous (and concurrent) activation of Bundles.
All activation activities (search for <code>IPOJO-Components</code> and <code>IPOJO-Extensions</code> Manifest headers, creation of factories and instances, binding) are done through job submissions.
Respectively, deactivation is always done asynchronously (if bundle is stopped when we would perform actions on it, that the ideal way to Exceptions).</p>
<p>By default, the ThreadPool size is set to <em>1</em> (asynchronous, but not concurrent executions), to mimic the pre 1.10 behavior.</p>
<p>ThreadPool's size can be configured either with System properties or through ConfigurationAdmin.
With Config Admin, the Configuration object has to target the service with <code>org.apache.felix.ipojo.extender.ExecutorQueueService</code> as its Service PID.
Property names are identical for System properties and ConfigAdmin.</p>
<table class="table table-striped">
<thead>
<tr>
<th>Function</th>
<th>Property Name</th>
<th>Supported Type(s)</th>
<th>Default Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>Number of Threads</td>
<td><code>org.apache.felix.ipojo.extender.ThreadPoolSize</code></td>
<td>Integer</td>
<td><code>1</code></td>
<td>The size of the thread pool. The default value is 1. Increase in case of a large amount of bundle's to manage (bundles with iPOJO's components/instances inside).</td>
</tr>
</tbody>
</table>
<h3 id="synchronous-asynchronous-processing">Synchronous / Asynchronous processing<a class="headerlink" href="#synchronous-asynchronous-processing" title="Permanent link">&para;</a></h3>
<p>By default, Apache Felix iPOJO process the Bundles in an asynchronous way. It's better in term of performances and more aligned with OSGi spec recommendations.
However, in some situations, like when running in <a href="https://developers.google.com/appengine/">Google App Engine</a> (<em>GAE</em>), the underlying platform imposes limitations.
For example GAE imposes mono-threading. That means that no asynchronous processing can be done by the application itself.</p>
<p>In other situations, it can be useful to be sure that components and instances contained in a given Bundle will be synchronously started.</p>
<p>iPOJO's Extender can be configured to support mono-threaded bundle processing to support such use cases.</p>
<h4 id="system-wide">System wide<a class="headerlink" href="#system-wide" title="Permanent link">&para;</a></h4>
<p>General synchronous processing can be configured through System properties or iPOJO's own Manifest attributes (requires a dedicated iPOJO bundle build).</p>
<table class="table table-striped">
<thead>
<tr>
<th>Mean</th>
<th>Property Name</th>
<th>Supported Type(s)</th>
<th>Default Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>System Property</td>
<td><code>ipojo.processing.synchronous</code></td>
<td>Boolean</td>
<td><code>false</code></td>
<td>Whether the Bundles processing should be performed synchronously. The default value is <code>false</code>. Set it to <code>true</code> when running in GAE for example.</td>
</tr>
<tr>
<td>Manifest</td>
<td><code>IPojo-processing-synchronous</code></td>
<td>Boolean</td>
<td><code>false</code></td>
<td>Whether the Bundles processing should be performed synchronously. The default value is <code>false</code>. Set it to <code>true</code> when running in GAE for example. Notice that case is ignored (<code>IPOJO-PROCESSING-SYNCHRONOUS</code> works as well as <code>IPojo-Processing-Synchronous</code>).</td>
</tr>
</tbody>
</table>
<h4 id="per-bundle">Per-Bundle<a class="headerlink" href="#per-bundle" title="Permanent link">&para;</a></h4>
<p>The synchronous behavior can be selected per-bundle (given that it does not conflict with existing system wide configuration).
Synchronous/Asynchronous behavior can be expressed in the Bundle's Manifest (case is not significant, but an uppercase first letter is recommended):</p>
<div class="codehilite"><pre><span class="n">IPOJO</span><span class="o">-</span><span class="n">Queue</span><span class="o">-</span><span class="n">Preference</span> <span class="n">SYNC</span>
</pre></div>
<p>3 values are supported:</p>
<ul>
<li><code>SYNC</code> for synchronous processing</li>
<li><code>ASYNC</code> for asynchronous processing</li>
<li><code>DEFAULT</code> using the default behavior</li>
</ul>
<p>If no header (or invalid value) is provided, the fallback behavior is <code>DEFAULT</code> (use system wide preference).</p>
<h3 id="queueservice-insights">QueueService Insights<a class="headerlink" href="#queueservice-insights" title="Permanent link">&para;</a></h3>
<p>Apache Felix iPOJO provides a mechanism that stores Job events of the QueueService in use (synchronous, multi-threaded, ...) for replay.
This is very useful to see where time is spent during the bootstrap and take actions accordingly.</p>
<p>This mechanism is available when the <code>org.apache.felix.ipojo.extender.BootstrapQueueDebug</code> system property is set to <code>true</code>.
When activated, a new OSGi service is registered under the <code>org.apache.felix.ipojo.extender.queue.debug.QueueEventProxy</code> interface (see below).</p>
<p><code>QueueListener</code> has to be registered in this service, when added, they'll be invoked with all stored events.
After that, the proxy simply forward the queue events to registered listeners.</p>
<div class="codehilite"><pre><span class="cm">/**</span>
<span class="cm"> * This service record events from a {@link org.apache.felix.ipojo.extender.queue.QueueService}.</span>
<span class="cm"> * When a listener is added, all recorded events are replayed into the listener.</span>
<span class="cm"> */</span>
<span class="kd">public</span> <span class="kd">interface</span> <span class="nc">QueueEventProxy</span> <span class="o">{</span>
<span class="cm">/**</span>
<span class="cm"> * Add a {@link org.apache.felix.ipojo.extender.queue.QueueListener} that will be notified on events</span>
<span class="cm"> * relative to the observed {@link org.apache.felix.ipojo.extender.queue.QueueService}.</span>
<span class="cm"> * @param listener added listener</span>
<span class="cm"> */</span>
<span class="kt">void</span> <span class="nf">addQueueListener</span><span class="o">(</span><span class="n">QueueListener</span> <span class="n">listener</span><span class="o">);</span>
<span class="cm">/**</span>
<span class="cm"> * Remove a {@link QueueListener} from the observed {@link org.apache.felix.ipojo.extender.queue.QueueService}.</span>
<span class="cm"> * @param listener removed listener</span>
<span class="cm"> */</span>
<span class="kt">void</span> <span class="nf">removeQueueListener</span><span class="o">(</span><span class="n">QueueListener</span> <span class="n">listener</span><span class="o">);</span>
<span class="o">}</span>
</pre></div>
<h3 id="event-dispatcher">Event Dispatcher<a class="headerlink" href="#event-dispatcher" title="Permanent link">&para;</a></h3>
<p>Apache Felix iPOJO provides a way to circumvent the so-call event storm happening when starting large OSGi applications (chained services apparitions).
It is a dedicated Event dispatcher that mimics a service registry partition logic based on registered service interfaces (<code>Constants.OBJECTCLASS</code>).
It is not enabled by default (rely on the framework's own service registry).</p>
<table class="table table-striped">
<thead>
<tr>
<th>Mean</th>
<th>Property Name</th>
<th>Supported Type(s)</th>
<th>Default Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>System Property</td>
<td><code>ipojo.internal.dispatcher</code></td>
<td>Boolean</td>
<td><code>false</code></td>
<td>Whether the EventDispatcher should be enabled. The default value is <code>false</code>. Set it to <code>true</code> when running large-scale applications.</td>
</tr>
<tr>
<td>Manifest</td>
<td><code>IPOJO-Internal-Dispatcher</code></td>
<td>Boolean</td>
<td><code>false</code></td>
<td>Whether the EventDispatcher should be enabled. The default value is <code>false</code>. Set it to <code>true</code> when running large-scale applications. Notice that case is ignored (<code>IPOJO-INTERNAL-DISPATCHER</code> works as well as <code>IPOJO-Internal-Dispatcher</code>).</td>
</tr>
</tbody>
</table>
</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. 1530248 by clement on Tue, 8 Oct 2013 12:13:27 +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>