Google Git
Sign in
apache / felix-site-pub / 765641cca8e5f533fd0ff82a0d20f91a6d37449a / . / documentation / _attachments / apidocs / dependencymanager.annotations / r7 / org / apache / felix / dm / annotation / api / Component.html
blob: 18f8326a45fb65b311bbe967e61c5704d63ad499 [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!-- NewPage -->
<html lang="en">
<head>
<!-- Generated by javadoc (1.8.0_74) on Wed Feb 24 01:07:22 CET 2016 -->
<title>Component</title>
<meta name="date" content="2016-02-24">
<link rel="stylesheet" type="text/css" href="../../../../../../stylesheet.css" title="Style">
<script type="text/javascript" src="../../../../../../script.js"></script>
</head>
<body>
<script type="text/javascript"><!--
try {
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="Component";
}
}
catch(err) {
}
//-->
</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
<!-- ========= START OF TOP NAVBAR ======= -->
<div class="topNav"><a name="navbar.top">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div>
<a name="navbar.top.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../../../org/apache/felix/dm/annotation/api/package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../../../index-all.html">Index</a></li>
<li><a href="../../../../../../help-doc.html">Help</a></li>
</ul>
</div>
<div class="subNav">
<ul class="navList">
<li><a href="../../../../../../org/apache/felix/dm/annotation/api/BundleDependency.html" title="annotation in org.apache.felix.dm.annotation.api"><span class="typeNameLink">Prev&nbsp;Class</span></a></li>
<li><a href="../../../../../../org/apache/felix/dm/annotation/api/Composition.html" title="annotation in org.apache.felix.dm.annotation.api"><span class="typeNameLink">Next&nbsp;Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../../../../../index.html?org/apache/felix/dm/annotation/api/Component.html" target="_top">Frames</a></li>
<li><a href="Component.html" target="_top">No&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_top">
<li><a href="../../../../../../allclasses-noframe.html">All&nbsp;Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_top");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li><a href="#annotation.type.field.summary">Field</a>&nbsp;|&nbsp;</li>
<li>Required&nbsp;|&nbsp;</li>
<li><a href="#annotation.type.optional.element.summary">Optional</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li><a href="#annotation.type.field.detail">Field</a>&nbsp;|&nbsp;</li>
<li><a href="#annotation.type.element.detail">Element</a></li>
</ul>
</div>
<a name="skip.navbar.top">
<!-- -->
</a></div>
<!-- ========= END OF TOP NAVBAR ========= -->
<!-- ======== START OF CLASS DATA ======== -->
<div class="header">
<div class="subTitle">org.apache.felix.dm.annotation.api</div>
<h2 title="Annotation Type Component" class="title">Annotation Type Component</h2>
</div>
<div class="contentContainer">
<div class="description">
<ul class="blockList">
<li class="blockList">
<hr>
<br>
<pre>@Retention(value=CLASS)
@Target(value=TYPE)
public @interface <span class="memberNameLabel">Component</span></pre>
<div class="block">Annotates an OSGi Component class with its dependencies. Components are the main building
blocks for OSGi applications. They can publish themselves as a service, and/or they can have
dependencies. These dependencies will influence their life cycle as component will only be
activated when all required dependencies are available.
By default, all directly implemented interfaces are registered into the OSGi registry,
and the component is instantiated automatically, when the component bundle is started and
when the component dependencies are available. If you need to take control of when and how
much component instances must be created, then you can use the <code>factoryName</code>
annotation attribute.<p>
If a <code>factoryName</code> attribute is set, the component is not started automatically
during bundle startup, and a <code>org.apache.felix.dm.runtime.api.ComponentFactory</code>
object is registered into the OSGi registry on behalf of the component. This ComponentFactory
can then be used by another component in order to instantiate multiple instances of the component
(DM ComponentFactory are really similar to DS ComponentFactory).
<h3>Usage Examples</h3>
Here is a sample showing a X component, which depends on a configuration dependency:
<blockquote>
<pre>
&#47;**
* This component will be activated once the bundle is started and when all required dependencies
* are available.
*&#47;
&#64;Component
class X implements Z {
&#64;ConfigurationDependency(pid="MyPid")
void configure(Dictionary conf) {
// Configure or reconfigure our component.
}
&#64;Start
void start() {
// Our component is starting and is about to be registered in the OSGi registry as a Z service.
}
public void doService() {
// ...
}
}
</pre>
</blockquote>
Here is a sample showing how a Y component may dynamically instantiate several X component instances,
using the <a href="../../../../../../org/apache/felix/dm/annotation/api/Component.html#factoryName--"><code>factoryName()</code></a> attribute:
<blockquote>
<pre>
&#47;**
* All component instances will be created/updated/removed by the "Y" component
*&#47;
&#64;Component(factoryName="MyComponentFactory", factoryConfigure="configure")
class X implements Z {
void configure(Dictionary conf) {
// Configure or reconfigure our component. The conf is provided by the factory,
// and all public properties (which don't start with a dot) are propagated with the
// service properties specified in the properties annotation attribute.
}
&#64;ServiceDependency
void bindOtherService(OtherService other) {
// store this require dependency
}
&#64;Start
void start() {
// Our component is starting and is about to be registered in the OSGi registry as a Z service.
}
public void doService() {
// ...
}
}
import import org.apache.felix.dm.runtime.api.ComponentFactory;
&#47;**
* This class will instantiate some X component instances
*&#47;
&#64;Component
class Y {
&#64;ServiceDependency(filter="(" + Component.FACTORY_NAME + "=MyComponentFactory)")
ComponentFactory _XFactory;
&#64;Start
void start() {
// Instantiate a X component instance
Dictionary instance1Conf = new Hashtable() {{ put("foo", "bar1"); }};
ComponentInstance instance1 = _XFactory.newInstance(instance1Conf);
// Instantiate another X component instance
Dictionary instance2Conf = new Hashtable() {{ put("foo2", "bar2"); }};
ComponentInstance instance2 = _XFactory.newInstance(instance2Conf);
// Update the first X component instance
instance1Conf = new Hashtable() {{ put("foo", "bar1 modified"); }};
instance1.update(instance1Conf);
// Instantiate a third X instance, by explicitly providing the implementation object
Dictionary instance3Conf = new Hashtable() {{ put(Component.FACTORY_INSTANCE, new X()); }};
ComponentInstance instance3 = _XFactory.newInstance(instance3Conf);
// Destroy x1/x2/x3 components
instance1.dispose();
instance2.dispose();
instance3.dispose();
}
}
</pre>
</blockquote></div>
</li>
</ul>
</div>
<div class="summary">
<ul class="blockList">
<li class="blockList">
<!-- =========== ANNOTATION TYPE FIELD SUMMARY =========== -->
<ul class="blockList">
<li class="blockList"><a name="annotation.type.field.summary">
<!-- -->
</a>
<h3>Field Summary</h3>
<table class="memberSummary" border="0" cellpadding="3" cellspacing="0" summary="Field Summary table, listing fields, and an explanation">
<caption><span>Fields</span><span class="tabEnd">&nbsp;</span></caption>
<tr>
<th class="colFirst" scope="col">Modifier and Type</th>
<th class="colLast" scope="col">Fields and Description</th>
</tr>
<tr class="altColor">
<td class="colFirst"><code>static java.lang.String</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../../../org/apache/felix/dm/annotation/api/Component.html#FACTORY_INSTANCE">FACTORY_INSTANCE</a></span></code>
<div class="block">Key used when providing an implementation when using a Component Factory .</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><code>static java.lang.String</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../../../org/apache/felix/dm/annotation/api/Component.html#FACTORY_NAME">FACTORY_NAME</a></span></code>
<div class="block">Service property name used to match a given Component Factory.</div>
</td>
</tr>
</table>
</li>
</ul>
<!-- =========== ANNOTATION TYPE OPTIONAL MEMBER SUMMARY =========== -->
<ul class="blockList">
<li class="blockList"><a name="annotation.type.optional.element.summary">
<!-- -->
</a>
<h3>Optional Element Summary</h3>
<table class="memberSummary" border="0" cellpadding="3" cellspacing="0" summary="Optional Element Summary table, listing optional elements, and an explanation">
<caption><span>Optional Elements</span><span class="tabEnd">&nbsp;</span></caption>
<tr>
<th class="colFirst" scope="col">Modifier and Type</th>
<th class="colLast" scope="col">Optional Element and Description</th>
</tr>
<tr class="altColor">
<td class="colFirst"><code>java.lang.String</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../../../org/apache/felix/dm/annotation/api/Component.html#factoryConfigure--">factoryConfigure</a></span></code>
<div class="block">Sets "configure" callback method name to be called with the factory configuration.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><code>java.lang.String</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../../../org/apache/felix/dm/annotation/api/Component.html#factoryMethod--">factoryMethod</a></span></code>
<div class="block">Sets the static method used to create the components implementation instance.</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><code>java.lang.String</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../../../org/apache/felix/dm/annotation/api/Component.html#factoryName--">factoryName</a></span></code>
<div class="block">Returns the name of the <code>ComponentFactory</code> used to dynamically instantiate this component.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><code>java.lang.String</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../../../org/apache/felix/dm/annotation/api/Component.html#factorySet--">factorySet</a></span></code>
<div class="block"><span class="deprecatedLabel">Deprecated.</span>&nbsp;
<div class="block"><span class="deprecationComment">use <a href="../../../../../../org/apache/felix/dm/annotation/api/Component.html#factoryName--"><code>factoryName()</code></a> instead of a factorySet.</span></div>
</div>
</td>
</tr>
<tr class="altColor">
<td class="colFirst"><code><a href="../../../../../../org/apache/felix/dm/annotation/api/Property.html" title="annotation in org.apache.felix.dm.annotation.api">Property</a>[]</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../../../org/apache/felix/dm/annotation/api/Component.html#properties--">properties</a></span></code>
<div class="block">Sets list of provided service properties.</div>
</td>
</tr>
<tr class="rowColor">
<td class="colFirst"><code>java.lang.Class&lt;?&gt;[]</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../../../org/apache/felix/dm/annotation/api/Component.html#provides--">provides</a></span></code>
<div class="block">Sets list of provided interfaces.</div>
</td>
</tr>
</table>
</li>
</ul>
</li>
</ul>
</div>
<div class="details">
<ul class="blockList">
<li class="blockList">
<!-- ============ ANNOTATION TYPE FIELD DETAIL =========== -->
<ul class="blockList">
<li class="blockList"><a name="annotation.type.field.detail">
<!-- -->
</a>
<h3>Field Detail</h3>
<a name="FACTORY_NAME">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>FACTORY_NAME</h4>
<pre>public static final&nbsp;java.lang.String&nbsp;FACTORY_NAME</pre>
<div class="block">Service property name used to match a given Component Factory.</div>
<dl>
<dt><span class="seeLabel">See Also:</span></dt>
<dd><a href="../../../../../../org/apache/felix/dm/annotation/api/Component.html#factoryName--"><code>for more information about factory sets.</code></a></dd>
</dl>
</li>
</ul>
</li>
</ul>
<ul class="blockList">
<li class="blockList"><a name="FACTORY_INSTANCE">
<!-- -->
</a>
<ul class="blockListLast">
<li class="blockList">
<h4>FACTORY_INSTANCE</h4>
<pre>public static final&nbsp;java.lang.String&nbsp;FACTORY_INSTANCE</pre>
<div class="block">Key used when providing an implementation when using a Component Factory .</div>
<dl>
<dt><span class="seeLabel">See Also:</span></dt>
<dd><a href="../../../../../../org/apache/felix/dm/annotation/api/Component.html#factoryName--"><code>factoryName()</code></a></dd>
</dl>
</li>
</ul>
</li>
</ul>
<!-- ============ ANNOTATION TYPE MEMBER DETAIL =========== -->
<ul class="blockList">
<li class="blockList"><a name="annotation.type.element.detail">
<!-- -->
</a>
<h3>Element Detail</h3>
<a name="provides--">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>provides</h4>
<pre>public abstract&nbsp;java.lang.Class&lt;?&gt;[]&nbsp;provides</pre>
<div class="block">Sets list of provided interfaces. By default, the directly implemented interfaces are provided.</div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the provided interfaces</dd>
</dl>
<dl>
<dt>Default:</dt>
<dd>{}</dd>
</dl>
</li>
</ul>
</li>
</ul>
<ul class="blockList">
<li class="blockList"><a name="properties--">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>properties</h4>
<pre>public abstract&nbsp;<a href="../../../../../../org/apache/felix/dm/annotation/api/Property.html" title="annotation in org.apache.felix.dm.annotation.api">Property</a>[]&nbsp;properties</pre>
<div class="block">Sets list of provided service properties. Since R7 version, Property annotation is repeatable and you can directly
apply it on top of the component class multiple times, instead of using the Component properties attribute.</div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the component properties.</dd>
</dl>
<dl>
<dt>Default:</dt>
<dd>{}</dd>
</dl>
</li>
</ul>
</li>
</ul>
<ul class="blockList">
<li class="blockList"><a name="factorySet--">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>factorySet</h4>
<pre>public abstract&nbsp;java.lang.String&nbsp;factorySet</pre>
<div class="block"><span class="deprecatedLabel">Deprecated.</span>&nbsp;<span class="deprecationComment">use <a href="../../../../../../org/apache/felix/dm/annotation/api/Component.html#factoryName--"><code>factoryName()</code></a> instead of a factorySet.</span></div>
<div class="block">Returns the name of the <code>Factory Set</code> used to dynamically instantiate this component.
When you set this attribute, a <code>java.util.Set&lt;java.lang.Dictionary&gt;</code> OSGi Service will
be provided with a <code>dm.factory.name</code> service property matching your specified <code>factorySet</code> attribute.
This Set will be provided once the component bundle is started, even if required dependencies are not available, and the
Set will be unregistered from the OSGi registry once the component bundle is stopped or being updated.<p>
So, basically, another component may then be injected with this set in order to dynamically instantiate some component instances:
<ul>
<li> Each time a new Dictionary is added into the Set, then a new instance of the annotated component will be instantiated.</li>
<li> Each time an existing Dictionary is re-added into the Set, then the corresponding component instance will be updated.</li>
<li> Each time an existing Dictionary is removed from the Set, then the corresponding component instance will be destroyed.</li>
</ul>
<p>The dictionary registered in the Set will be provided to the created component instance using a callback method that you can
optionally specify in the <a href="../../../../../../org/apache/felix/dm/annotation/api/Component.html#factoryConfigure--"><code>factoryConfigure()</code></a> attribute. Each public properties from that dictionary
(which don't start with a dot) will be propagated along with the annotated component service properties.
<p>Optionally, the dictionary registered into the factory set may provide an implementation instance for the component to be created,
using the <a href="../../../../../../org/apache/felix/dm/annotation/api/Component.html#FACTORY_INSTANCE">"dm.factory.instance"</a> key.</div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the factory set name</dd>
</dl>
<dl>
<dt>Default:</dt>
<dd>""</dd>
</dl>
</li>
</ul>
</li>
</ul>
<ul class="blockList">
<li class="blockList"><a name="factoryName--">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>factoryName</h4>
<pre>public abstract&nbsp;java.lang.String&nbsp;factoryName</pre>
<div class="block">Returns the name of the <code>ComponentFactory</code> used to dynamically instantiate this component.
When you set this attribute, a <code>org.apache.felix.dm.runtime.api.ComponentFactory</code> OSGi Service will
be provided with a <code>dm.factory.name</code> service property matching your specified <code>factoryName</code> attribute.
The ComponentFactory will be provided once the component bundle is started, even if required dependencies are not available, and the
ComponentFactory will be unregistered from the OSGi registry once the component bundle is stopped or being updated.<p>
So, another component may then be injected with this ComponentFactory in order to dynamically instantiate some component instances:
<p>The dictionary passed to the ComponentFactory.newInstance method will be provided to the created component instance using a callback
method that you can optionally specify in the <a href="../../../../../../org/apache/felix/dm/annotation/api/Component.html#factoryConfigure--"><code>factoryConfigure()</code></a> attribute. Each public properties from that dictionary
(which don't start with a dot) will be propagated along with the annotated component service properties.
<p>Optionally, the dictionary registered into the factory set may provide an implementation instance for the component to be created,
using a "dm.runtime.factory.instance" key.</div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the factory name</dd>
</dl>
<dl>
<dt>Default:</dt>
<dd>""</dd>
</dl>
</li>
</ul>
</li>
</ul>
<ul class="blockList">
<li class="blockList"><a name="factoryConfigure--">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>factoryConfigure</h4>
<pre>public abstract&nbsp;java.lang.String&nbsp;factoryConfigure</pre>
<div class="block">Sets "configure" callback method name to be called with the factory configuration. This attribute only makes sense if the
<a href="../../../../../../org/apache/felix/dm/annotation/api/Component.html#factoryName--"><code>factoryName()</code></a> attribute is used. If specified, then this attribute references a callback method, which is called
for providing the configuration supplied by the factory that instantiated this component. The current component service properties will be
also updated with all public properties (which don't start with a dot).</div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the factory configure callback name</dd>
</dl>
<dl>
<dt>Default:</dt>
<dd>""</dd>
</dl>
</li>
</ul>
</li>
</ul>
<ul class="blockList">
<li class="blockList"><a name="factoryMethod--">
<!-- -->
</a>
<ul class="blockListLast">
<li class="blockList">
<h4>factoryMethod</h4>
<pre>public abstract&nbsp;java.lang.String&nbsp;factoryMethod</pre>
<div class="block">Sets the static method used to create the components implementation instance.</div>
<dl>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the factory method used to instantiate the component</dd>
</dl>
<dl>
<dt>Default:</dt>
<dd>""</dd>
</dl>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
<!-- ========= END OF CLASS DATA ========= -->
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<div class="bottomNav"><a name="navbar.bottom">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div>
<a name="navbar.bottom.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../../../org/apache/felix/dm/annotation/api/package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../../../index-all.html">Index</a></li>
<li><a href="../../../../../../help-doc.html">Help</a></li>
</ul>
</div>
<div class="subNav">
<ul class="navList">
<li><a href="../../../../../../org/apache/felix/dm/annotation/api/BundleDependency.html" title="annotation in org.apache.felix.dm.annotation.api"><span class="typeNameLink">Prev&nbsp;Class</span></a></li>
<li><a href="../../../../../../org/apache/felix/dm/annotation/api/Composition.html" title="annotation in org.apache.felix.dm.annotation.api"><span class="typeNameLink">Next&nbsp;Class</span></a></li>
</ul>
<ul class="navList">
<li><a href="../../../../../../index.html?org/apache/felix/dm/annotation/api/Component.html" target="_top">Frames</a></li>
<li><a href="Component.html" target="_top">No&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_bottom">
<li><a href="../../../../../../allclasses-noframe.html">All&nbsp;Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_bottom");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li><a href="#annotation.type.field.summary">Field</a>&nbsp;|&nbsp;</li>
<li>Required&nbsp;|&nbsp;</li>
<li><a href="#annotation.type.optional.element.summary">Optional</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li><a href="#annotation.type.field.detail">Field</a>&nbsp;|&nbsp;</li>
<li><a href="#annotation.type.element.detail">Element</a></li>
</ul>
</div>
<a name="skip.navbar.bottom">
<!-- -->
</a></div>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
</body>
</html>