Author: pderop
Date: Sat Mar 7 21:39:45 2015
New Revision: 1664922
URL: http://svn.apache.org/r1664922
Log:
use factoryName instead of deprecated factorySet attribute in Component
annotation.
Modified:
felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/components.mdtext
Modified:
felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/components.mdtext
URL:
http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/components.mdtext?rev=1664922&r1=1664921&r2=1664922&view=diff
==============================================================================
---
felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/components.mdtext
(original)
+++
felix/site/trunk/content/documentation/subprojects/apache-felix-dependency-manager-4/reference/components.mdtext
Sat Mar 7 21:39:45 2015
@@ -104,7 +104,7 @@ take control of how the component is cr
be used to create the component as a dynamic proxy ...
----
-**`factorySet`**
+**`factoryName`**
*Required*: No
*Default*: --
@@ -112,32 +112,13 @@ This attribute is the identifier for a c
component is automatically instantiated as a singleton when the bundle is
started, and when all required dependencies are satisfied. But when a
component must be created, configured, or disposed dynamically, and when
-multiple instances of the same component are needed, a factorySet should be
-used. When you use this attribute, a java.util.Set<Dictionary> object is
-registered into the OSGi regitry, with a specific *dm.factory.name* service
-property matching the ID you specify in the attribute.
-
-This Set<Dictionary> will act as a Factory API, and another component may
-define a dependency on this Set and add some configuration dictionaries in it,
-in order to fire some component instantiation/activation. There is one
-component instantiated per added dictionary, which is passed to component
-instances via a configurable callback method (using the *factoryConfigure*
-attribute). All public properties will be propagated along with eventual
-published service. A public property is a property which does not start with
-a dot ("."). Properties starting with a dot are considered private to the
-component, and won't be propagated to published service. This model is
-actually similar to the Declarative Service "Component Factories" concept,
-except that you don't have a dependency on a specific API, but rather on a
-basic jdk class (java.util.Set<Dictionary>).
-
-Notice that, unlike in Declarative Service, the component factory is provided
once the component
-bundle is started, even if required dependencies are not satisfied. This is
-useful when the component want to dynamically configure its dependency
-filters. So, to summarize:
-
-- Each time a new Dictionary is added into the Set, then a new instance of the
annotated component will be instantiated, and this dictionary is passed to the
component callback specified with the factoryConfigure attribute.
-- Each time an existing Dictionary is re-added into the Set, then the
corresponding component instance is updated, and the updated dictionary is also
passed to the callback specified in the factoryConfigure attribute.
-- Each time an existing Dictionary is removed from the Set, then the
corresponding component instance will be stopped and destroyed.
+multiple instances of the same component are needed, a factoryName can be
+used. When you use this attribute, a
*org.apache.felix.dm.runtime.api.ComponentFactory*
+OSGi Service will be provided with a *dm.factory.name* service property
matching your
+specified factoryName 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..
----
**`factoryConfigure`**
@@ -145,7 +126,7 @@ filters. So, to summarize:
*Default*: --
This attributes sets the *configure* method name to be called with the factory
-configuration. This attribute only makes sense if the factorySet() attribute
+configuration. This attribute only makes sense if the *factoryName* attribute
is used. If specified, then this attribute references a component callback
method, which is called for providing the configuration supplied by the
factory that instantiated this component. The current Service properties will
@@ -176,10 +157,13 @@ Usage example:
}
-Example using a factorySet, where the X component is
instantiated/updated/disposed by another Y component:
+Example using a factoryName, where the X component is
instantiated/updated/disposed by another Y component:
:::java
- @Component(factorySet="MyComponentFactory", factoryConfigure="configure")
+ import org.apache.felix.dm.runtime.api.ComponentFactory;
+ import org.apache.felix.dm.runtime.api.ComponentInstance;
+
+ @Component(factoryName="MyComponentFactory", factoryConfigure="configure")
class X implements Z {
void configure(Dictionary conf) {
// Configure or reconfigure our component. The conf is provided
by
@@ -212,26 +196,25 @@ Example using a factorySet, where the X
class Y {
// This Set acts as a Factory API for creating X component instances.
@ServiceDependency(filter="(dm.factory.name=MyComponentFactory)")
- Set<Dictionary> _XFactory;
+ ComponentFactory _XFactory;
@Start
void start() {
// Instantiate a X component instance
Dictionary x1 = new Hashtable() {{ put("foo", "bar1"); }};
- _XFactory.add(x1);
+ ComponentInstance i1 = _XFactory.newInstance(x1);
// Instantiate another X component instance
Dictionary x2 = new Hashtable() {{ put("foo", "bar2"); }};
- _XFactory.add(x2);
+ ComponentInstance i2 = _XFactory.newInstance(x2);
// Update the first X component instance
- x1.put("foo", "bar1_modified");
- _XFactory.add(x1);
+ x1 = new Hashtable() {{ put("foo", "bar1_modified"); }};
+ i1.update(x1);
- // Destroy all components (Notice that invoking
- // _XFactory.clear() also destroys every X instances)
- _XFactory.remove(x1);
- _XFactory.remove(x2);
+ // Destroy components
+ i1.dispose();
+ i2.dispose();
}
}
