Author: pderop
Date: Sat Jan 30 23:49:06 2016
New Revision: 1727768
URL: http://svn.apache.org/viewvc?rev=1727768&view=rev
Log:
Javadoc.
Modified:
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda.itest/src/org/apache/felix/dm/lambda/itest/BundleAdapterWithCallbacksNotAutoConfiguredTest.java
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/BundleAdapterBuilder.java
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/BundleDependencyBuilder.java
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/ComponentBuilder.java
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/ConfigurationDependencyBuilder.java
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/FactoryPidAdapterBuilder.java
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/FutureDependencyBuilder.java
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/ServiceAdapterBuilder.java
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/ServiceAspectBuilder.java
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/ServiceCallbacksBuilder.java
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/ServiceDependencyBuilder.java
Modified:
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda.itest/src/org/apache/felix/dm/lambda/itest/BundleAdapterWithCallbacksNotAutoConfiguredTest.java
URL:
http://svn.apache.org/viewvc/felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda.itest/src/org/apache/felix/dm/lambda/itest/BundleAdapterWithCallbacksNotAutoConfiguredTest.java?rev=1727768&r1=1727767&r2=1727768&view=diff
==============================================================================
---
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda.itest/src/org/apache/felix/dm/lambda/itest/BundleAdapterWithCallbacksNotAutoConfiguredTest.java
(original)
+++
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda.itest/src/org/apache/felix/dm/lambda/itest/BundleAdapterWithCallbacksNotAutoConfiguredTest.java
Sat Jan 30 23:49:06 2016
@@ -38,11 +38,8 @@ public class BundleAdapterWithCallbacksN
String bsn = "org.apache.felix.dependencymanager";
String filter = "(Bundle-SymbolicName=" + bsn + ")";
- Component adapter = bundleAdapter(m)
- .mask(Bundle.ACTIVE).filter(filter).cb("add")
- .impl(baWithCb)
- .build();
-
+ Component adapter =
bundleAdapter(m).mask(Bundle.ACTIVE).filter(filter).cb("add").impl(baWithCb).build();
+
// add the bundle adapter
m.add(adapter);
Modified:
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/BundleAdapterBuilder.java
URL:
http://svn.apache.org/viewvc/felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/BundleAdapterBuilder.java?rev=1727768&r1=1727767&r2=1727768&view=diff
==============================================================================
---
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/BundleAdapterBuilder.java
(original)
+++
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/BundleAdapterBuilder.java
Sat Jan 30 23:49:06 2016
@@ -6,32 +6,50 @@ import org.apache.felix.dm.lambda.callba
import org.apache.felix.dm.lambda.callbacks.CbTypeComponentBundle;
/**
- * Builder interface for a DM Bundle Adapter.
+ * Builds a Dependency Manager bundle adapter. The adapter created by this
builder will be applied to any bundle that matches the specified
+ * bundle state mask and filter condition. For each matching bundle an adapter
service will be created based on the adapter implementation class.
+ * The adapter will be registered with the specified interface and existing
properties from the original bundle plus any extra properties
+ * you supply here. The bundle is injected by reflection in adapter class
fields having a Bundle type, or using a callback method that you can
+ * specify.
*
- * <p> Example that creates a MyBundleAdapter service for each started bundle
(the bundle is added by reflection on
- * class field with a Bundle type):
+ * <p> Example which creates a BundleAdapter service for each started bundle
(the bundle is added by reflection on
+ * a class field that has a "Bundle" type):
*
* <pre> {@code
* public class Activator extends DependencyManagerActivator {
* public void activate() throws Exception {
* bundleAdapter(adapt -> adapt
- * .impl(MyBundleAdapterImpl.class)
- * .provides(MyBundleAdapter.class)
+ * .impl(BundleAdapterImpl.class)
+ * .provides(BundleAdapter.class)
* .mask(Bundle.INSTALLED | Bundle.RESOLVED | Bundle.ACTIVE));
* }
* }
* } </pre>
*
- * Example that creates a MyBundleAdapter service for each started bundle (the
bundle is added using a method reference):
+ * Example that creates a BundleAdapter service for each started bundle (the
bundle is added using a method reference):
*
* <pre> {@code
* public class Activator extends DependencyManagerActivator {
* public void activate() throws Exception {
* bundleAdapter(adapt -> adapt
- * .impl(MyBundleAdapterImpl.class)
- * .provides(MyBundleAdapter.class)
+ * .impl(BundleAdapterImpl.class)
+ * .provides(BundleAdapter.class)
* .mask(Bundle.INSTALLED | Bundle.RESOLVED | Bundle.ACTIVE)
- * .cb(MyBundleAdapterImpl::setBundle));
+ * .cb(BundleAdapterImpl::setBundle));
+ * }
+ * }
+ * }</pre>
+ *
+ * Example that creates a BundleAdapter service for each started bundle (the
bundle is added using a method name):
+ *
+ * <pre> {@code
+ * public class Activator extends DependencyManagerActivator {
+ * public void activate() throws Exception {
+ * bundleAdapter(adapt -> adapt
+ * .impl(BundleAdapterImpl.class)
+ * .provides(BundleAdapter.class)
+ * .mask(Bundle.INSTALLED | Bundle.RESOLVED | Bundle.ACTIVE)
+ * .cb("setBundle"));
* }
* }
* }</pre>
@@ -74,31 +92,31 @@ public interface BundleAdapterBuilder ex
BundleAdapterBuilder propagate();
/**
- * Sets some <code>callback</code> methods to invoke on the component
instance(s). When a bundle state matches the bundle
+ * Sets some <code>callbacks</code> invoked on the component
implementation instances. When a bundle state matches the bundle
* adapter filter, then the bundle is injected using the specified
callback methods. When you specify one callback, it stands for the "add"
callback.
* When you specify two callbacks, the first one corresponds to the "add"
callback, and the second one to the "remove" callback. When you specify three
* callbacks, the first one stands for the "add" callback, the second one
for the "change" callback, and the third one for the "remove" callback.
*
- * @param callbacks a list of callbacks (1 param : "add", 2 params :
"add"/remove", 3 params : "add"/"change"/"remove" callbacks).
+ * @param callbacks a list of callbacks (1 param : "add", 2 params :
"add"/remove", 3 params : "add"/"change"/"remove").
* @return this builder
*/
BundleAdapterBuilder cb(String ... callbacks);
/**
- * Sets some <code>callback instance</code> methods to invoke on a given
Object instance. When a bundle state matches the bundle
+ * Sets some <code>callback instance</code> methods invoked on a given
Object instance. When a bundle state matches the bundle
* adapter filter, then the bundle is injected using the specified
callback methods. When you specify one callback, it stands for the "add"
callback.
* When you specify two callbacks, the first one corresponds to the "add"
callback, and the second one to the "remove" callback.
* When you specify three callbacks, the first one stands for the "add"
callback, the second one for the "change" callback, and the third one for
* the "remove" callback.
*
* @param callbackInstance the Object instance where the callbacks are
invoked on
- * @param callbacks a list of callbacks (1 param : "add", 2 params :
"add"/remove", 3 params : "add"/"change"/"remove" callbacks).
+ * @param callbacks a list of callbacks (1 param : "add", 2 params :
"add"/remove", 3 params : "add"/"change"/"remove").
* @return this builder
*/
BundleAdapterBuilder cbi(Object callbackInstance, String ... callbacks);
/**
- * Sets a <code>callback</code> java8 method reference which is invoked
when a bundle is added.
+ * Sets a <code>callback</code> invoked on a component implementation
instance when a bundle is added.
* The method reference must point to a Component implementation class
method, and take as argument a Bundle.
*
* @param <T> the type of the component instance class on which the
callback is invoked.
@@ -108,7 +126,7 @@ public interface BundleAdapterBuilder ex
<T> BundleAdapterBuilder cb(CbTypeBundle<T> add);
/**
- * Sets some <code>callback</code> java8 method references which are
invoked when a bundle is added, or removed.
+ * Sets some <code>callbacks</code> invoked on a component implementation
instance when a bundle is added/removed.
* The method references must point to a Component implementation class
method, and take as argument a Bundle.
*
* @param <T> the type of the component instance class on which the
callback is invoked.
@@ -119,7 +137,7 @@ public interface BundleAdapterBuilder ex
<T> BundleAdapterBuilder cb(CbTypeBundle<T> add, CbTypeBundle<T> remove);
/**
- * Sets some <code>callback</code> java8 method references which are
invoked when a bundle is added, changed or removed.
+ * Sets some <code>callbacks</code> invoked on a component implementation
instance when a bundle is added, changed or removed.
* The method references must point to a Component implementation class
method, and take as argument a Bundle.
*
* @param <T> the type of the component instance class on which the
callback is invoked.
@@ -131,7 +149,7 @@ public interface BundleAdapterBuilder ex
<T> BundleAdapterBuilder cb(CbTypeBundle<T> add, CbTypeBundle<T> change,
CbTypeBundle<T> remove);
/**
- * Sets a <code>callback</code> java8 method reference which is invoked
when a bundle is added.
+ * Sets a <code>callback</code> invoked on a component implementation
instance when a bundle is added.
* The method reference must point to a Component implementation class
method, and take as argument a Component and a Bundle.
*
* @param <T> the type of the component instance class on which the
callback is invoked.
@@ -141,7 +159,7 @@ public interface BundleAdapterBuilder ex
<T> BundleAdapterBuilder cb(CbTypeComponentBundle<T> add);
/**
- * Sets some <code>callback</code> java8 method references which are
invoked when a bundle is added, or removed.
+ * Sets some <code>callbacks</code> invoked on a component implementation
instance when a bundle is added, or removed.
* The method references must point to a Component implementation class
method, and take as argument a Component and a Bundle.
*
* @param <T> the type of the component instance class on which the
callback is invoked.
@@ -152,7 +170,7 @@ public interface BundleAdapterBuilder ex
<T> BundleAdapterBuilder cb(CbTypeComponentBundle<T> add,
CbTypeComponentBundle<T> remove);
/**
- * Sets some <code>callback</code> java8 method references which are
invoked when a bundle is added, changed or removed.
+ * Sets some <code>callbacks</code> invoked on a component implementation
instance when a bundle is added, changed or removed.
* The method references must point to a Component implementation class
method, and take as argument a Component and a Bundle.
*
* @param <T> the type of the component instance class on which the
callback is invoked.
@@ -164,7 +182,7 @@ public interface BundleAdapterBuilder ex
<T> BundleAdapterBuilder cb(CbTypeComponentBundle<T> add,
CbTypeComponentBundle<T> change, CbTypeComponentBundle<T> remove);
/**
- * Sets a <code>callback instance</code> java8 method reference which is
invoked when a bundle is added.
+ * Sets a <code>callback instance</code> invoked on a given Object
instance when a bundle is added.
* The method reference must point to an Object instance method, and takes
as argument a Bundle parameter.
*
* @param add the method reference invoked when a bundle is added.
@@ -173,7 +191,7 @@ public interface BundleAdapterBuilder ex
BundleAdapterBuilder cbi(CbBundle add);
/**
- * Sets some <code>callback instance</code> java8 method references which
are invoked when a bundle is added or removed.
+ * Sets some <code>callback instance</code> invoked on a given Object
instance when a bundle is added or removed.
* The method references must point to an Object instance method, and take
as argument a Bundle parameter.
*
* @param add the method reference invoked when a bundle is added.
@@ -183,7 +201,7 @@ public interface BundleAdapterBuilder ex
BundleAdapterBuilder cbi(CbBundle add, CbBundle remove);
/**
- * Sets some <code>callback instance</code> java8 method references which
are invoked when a bundle is added, changed or removed.
+ * Sets some <code>callback instance</code> invoked on a given Object
instance when a bundle is added, changed or removed.
* The method references must point to an Object instance method, and take
as argument a Bundle parameter.
*
* @param add the method reference invoked when a bundle is added.
@@ -194,7 +212,7 @@ public interface BundleAdapterBuilder ex
BundleAdapterBuilder cbi(CbBundle add, CbBundle change, CbBundle remove);
/**
- * Sets a <code>callback instance</code> java8 method reference which is
invoked when a bundle is added.
+ * Sets a <code>callback instance</code> invoked on a given Object
instance when a bundle is added.
* The method reference must point to an Object instance method, and takes
as arguments a Component and a Bundle.
*
* @param add the method reference invoked when a bundle is added.
@@ -203,7 +221,7 @@ public interface BundleAdapterBuilder ex
BundleAdapterBuilder cbi(CbComponentBundle add);
/**
- * Sets some <code>callback instance</code> java8 method references which
are invoked when a bundle is added or removed.
+ * Sets some <code>callback instance</code> invoked on a given Object
instance when a bundle is added or removed.
* The method references must point to an Object instance method, and take
as argument a Component and a Bundle.
*
* @param add the method reference invoked when a bundle is added.
@@ -213,7 +231,7 @@ public interface BundleAdapterBuilder ex
BundleAdapterBuilder cbi(CbComponentBundle add, CbComponentBundle remove);
/**
- * Sets some <code>callback instance</code> java8 method references which
are invoked when a bundle is added, changed or removed.
+ * Sets some <code>callback instance</code> invoked on a given Object
instance when a bundle is added, changed or removed.
* The method references must point to an Object instance method, and take
as argument a Component and a Bundle.
*
* @param add the method reference invoked when a bundle is added.
Modified:
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/BundleDependencyBuilder.java
URL:
http://svn.apache.org/viewvc/felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/BundleDependencyBuilder.java?rev=1727768&r1=1727767&r2=1727768&view=diff
==============================================================================
---
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/BundleDependencyBuilder.java
(original)
+++
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/BundleDependencyBuilder.java
Sat Jan 30 23:49:06 2016
@@ -11,16 +11,17 @@ import org.apache.felix.dm.lambda.callba
import org.osgi.framework.Bundle;
/**
- * Builder for a DM Bundle Dependency.
+ * Builds a Dependency Manager Bundle Dependency. The Dependency is required
by default (unlike in the original Dependency Manager API).
*
- * Example that uses a Bundle Dependency:
+ * <p> Example of a Component which tracks a started bundle having a given
bundle symbolic name:
*
* <pre> {@code
* public class Activator extends DependencyManagerActivator {
* public void activate() throws Exception {
+ * String BSN = "org.apache.felix.dependencymanager";
* component(comp -> comp
* .impl(MyComponent.class)
- * .withBundle(b -> b.filter("(Bundle-SymbolicName=" + BSN +
")").cb(MyComponent::add, MyComponent::remove)));
+ * .withBundle(b ->
b.mask(Bundle.ACTIVE).filter("(Bundle-SymbolicName=" + BSN +
")").cb(MyComponent::add, MyComponent::remove)));
*
* }
* }
@@ -47,9 +48,9 @@ public interface BundleDependencyBuilder
public BundleDependencyBuilder autoConfig();
/**
- * Sets the dependency to be required.
+ * Sets the dependency to be required. By default, the dependency is
required.
*
- * @param required <code>true</code> if this bundle dependency is required
+ * @param required <code>true</code> if this bundle dependency is required
(true by default).
* @return the bundle dependency builder
*/
public BundleDependencyBuilder required(boolean required);
@@ -151,7 +152,7 @@ public interface BundleDependencyBuilder
BundleDependencyBuilder cb(Object callbackInstance, String ... callbacks);
/**
- * Sets a <code>callback</code> java8 method reference which is invoked
when a bundle is added.
+ * Sets a <code>callback</code> method reference which is invoked when a
bundle is added.
* The method reference must point to a Component implementation class
method, and take as argument a Bundle.
*
* @param <T> the type of the component implementation class on which the
callback is invoked on.
@@ -161,7 +162,7 @@ public interface BundleDependencyBuilder
<T> BundleDependencyBuilder cb(CbTypeBundle<T> add);
/**
- * Sets some <code>callback</code> java8 method references which are
invoked when a bundle is added, or removed.
+ * Sets some <code>callback</code> method references which are invoked
when a bundle is added, or removed.
* The method references must point to a Component implementation class
method, and take as argument a Bundle.
*
* @param <T> the type of the component implementation class on which the
callback is invoked on.
@@ -172,7 +173,7 @@ public interface BundleDependencyBuilder
<T> BundleDependencyBuilder cb(CbTypeBundle<T> add, CbTypeBundle<T>
remove);
/**
- * Sets some <code>callback</code> java8 method references which are
invoked when a bundle is added, changed or removed.
+ * Sets some <code>callback</code> method references which are invoked
when a bundle is added, changed or removed.
* The method references must point to a Component implementation class
method, and take as argument a Bundle.
*
* @param <T> the type of the component implementation class on which the
callback is invoked on.
@@ -184,7 +185,7 @@ public interface BundleDependencyBuilder
<T> BundleDependencyBuilder cb(CbTypeBundle<T> add, CbTypeBundle<T>
change, CbTypeBundle<T> remove);
/**
- * Sets a <code>callback</code> java8 method reference which is invoked
when a bundle is added.
+ * Sets a <code>callback</code> method reference which is invoked when a
bundle is added.
* The method reference must point to a Component implementation class
method, and take as argument a Component and a Bundle.
*
* @param <T> the type of the component implementation class on which the
callback is invoked on.
@@ -194,7 +195,7 @@ public interface BundleDependencyBuilder
<T> BundleDependencyBuilder cb(CbTypeComponentBundle<T> add);
/**
- * Sets some <code>callback</code> java8 method references which are
invoked when a bundle is added, or removed.
+ * Sets some <code>callback</code> method references which are invoked
when a bundle is added, or removed.
* The method references must point to a Component implementation class
method, and take as argument a Component and a Bundle.
*
* @param <T> the type of the component implementation class on which the
callback is invoked on.
@@ -205,7 +206,7 @@ public interface BundleDependencyBuilder
<T> BundleDependencyBuilder cb(CbTypeComponentBundle<T> add,
CbTypeComponentBundle<T> remove);
/**
- * Sets some <code>callback</code> java8 method references which are
invoked when a bundle is added, changed or removed.
+ * Sets some <code>callback</code> method references which are invoked
when a bundle is added, changed or removed.
* The method references must point to a Component implementation class
method, and take as argument a Component and a Bundle.
*
* @param <T> the type of the component implementation class on which the
callback is invoked on.
@@ -217,7 +218,7 @@ public interface BundleDependencyBuilder
<T> BundleDependencyBuilder cb(CbTypeComponentBundle<T> add,
CbTypeComponentBundle<T> change, CbTypeComponentBundle<T> remove);
/**
- * Sets a <code>callback instance</code> java8 method reference which is
invoked when a bundle is added.
+ * Sets a <code>callback instance</code> method reference which is invoked
when a bundle is added.
* The method reference must point to an Object instance method, and takes
as argument a Bundle parameter.
*
* @param add the method reference invoked when a bundle is added.
@@ -226,7 +227,7 @@ public interface BundleDependencyBuilder
BundleDependencyBuilder cbi(CbBundle add);
/**
- * Sets some <code>callback instance</code> java8 method references which
are invoked when a bundle is added or removed.
+ * Sets some <code>callback instance</code> method references which are
invoked when a bundle is added or removed.
* The method references must point to an Object instance method, and take
as argument a Bundle parameter.
*
* @param add the method reference invoked when a bundle is added.
@@ -236,7 +237,7 @@ public interface BundleDependencyBuilder
BundleDependencyBuilder cbi(CbBundle add, CbBundle remove);
/**
- * Sets some <code>callback instance</code> java8 method references which
are invoked when a bundle is added, changed or removed.
+ * Sets some <code>callback instance</code> method references which are
invoked when a bundle is added, changed or removed.
* The method references must point to an Object instance method, and take
as argument a Bundle parameter.
*
* @param add the method reference invoked when a bundle is added.
@@ -247,7 +248,7 @@ public interface BundleDependencyBuilder
BundleDependencyBuilder cbi(CbBundle add, CbBundle change, CbBundle
remove);
/**
- * Sets a <code>callback instance</code> java8 method reference which is
invoked when a bundle is added.
+ * Sets a <code>callback instance</code> method reference which is invoked
when a bundle is added.
* The method reference must point to an Object instance method, and takes
as arguments a Component and a Bundle.
*
* @param add the method reference invoked when a bundle is added.
@@ -256,7 +257,7 @@ public interface BundleDependencyBuilder
BundleDependencyBuilder cbi(CbComponentBundle add);
/**
- * Sets some <code>callback instance</code> java8 method references which
are invoked when a bundle is added or removed.
+ * Sets some <code>callback instance</code> method references which are
invoked when a bundle is added or removed.
* The method references must point to an Object instance method, and take
as argument a Component and a Bundle.
*
* @param add the method reference invoked when a bundle is added.
@@ -266,7 +267,7 @@ public interface BundleDependencyBuilder
BundleDependencyBuilder cbi(CbComponentBundle add, CbComponentBundle
remove);
/**
- * Sets some <code>callback instance</code> java8 method references which
are invoked when a bundle is added, changed or removed.
+ * Sets some <code>callback instance</code> method references which are
invoked when a bundle is added, changed or removed.
* The method references must point to an Object instance method, and take
as argument a Component and a Bundle.
*
* @param add the method reference invoked when a bundle is added.
Modified:
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/ComponentBuilder.java
URL:
http://svn.apache.org/viewvc/felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/ComponentBuilder.java?rev=1727768&r1=1727767&r2=1727768&view=diff
==============================================================================
---
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/ComponentBuilder.java
(original)
+++
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/ComponentBuilder.java
Sat Jan 30 23:49:06 2016
@@ -13,7 +13,12 @@ import org.apache.felix.dm.lambda.callba
import org.apache.felix.dm.lambda.callbacks.CbTypeComponent;
/**
- * Component builder. This interface is also the base interface for extended
components like aspects, adapters, etc ...
+ * Builds a Dependency Manager Component. Components are the main building
blocks for OSGi applications.
+ * They can publish themselves as a service, and they can have dependencies.
+ * These dependencies will influence their life cycle as component will only
be activated when all
+ * required dependencies are available.
+ *
+ * <p> This interface is also the base interface for extended components like
aspects, adapters, etc ...
*
* <p> Example of a component that depends on a ConfigurationAdmin service.
The dependency is injected by reflection
* on a class field which type matches the ConfigurationAdmin interface:
@@ -66,7 +71,9 @@ public interface ComponentBuilder<B exte
* Configures a factory used to create this component implementation using
a Factory object and a method in the Factory object.
* Example:
*
+ * <pre> {@code
* factory(Factory::new, Factory::create)
+ * }</pre>
*
* @param <U> the type of the factory returned by the supplier
* @param <V> the type of the object that is returned by the factory
create method.
@@ -82,9 +89,11 @@ public interface ComponentBuilder<B exte
*
* Example:
*
+ * <pre> {@code
* CompositionManager mngr = new CompositionManager();
* ...
* factory(mngr::create, mngr::getComposition)
+ * }</pre>
*
* @param factory the supplier used to return the main component
implementation instance
* @param getComposition the supplier that returns the list of instances
that are part of the component implementation classes.
@@ -97,7 +106,9 @@ public interface ComponentBuilder<B exte
*
* Example:
*
+ * <pre> {@code
* factory(CompositionManager::new, CompositionManager::create,
CompositionManager::getComposition).
+ * }</pre>
*
* Here, the CompositionManager will act as a factory (the create method
will return the component implementation object), and the
* CompositionManager.getComposition() method will return all the objects
that are also part of the component implementation.
@@ -135,9 +146,9 @@ public interface ComponentBuilder<B exte
*
* code example:
*
- * {@code
+ * <pre> {@code
* provides(MyService.class, property1 -> "value1", property2 -> 123);
- * }
+ * }</pre>
*
* @param iface the public interfaces to register in the OSGI service
registry.
* @param properties a list of fluent service properties for the
provided service. You can specify a list of lambda expression, each one
implementing the
@@ -293,7 +304,9 @@ public interface ComponentBuilder<B exte
/**
* Sets the components's service properties using varargs. The number of
parameters must be even, representing a list of pair property key-value.
*
+ * <pre> {@code
* Example: properties("param1", "value1", "service.ranking", 3)
+ * }</pre>
*
* @param name the first property name
* @param value the first property value
@@ -329,14 +342,14 @@ public interface ComponentBuilder<B exte
B withSrv(Class<?> service, String filter);
/**
- * Adds a required/autoconfig service dependency.
+ * Adds in one shot multiple required/autoconfig service dependencies.
* @param services the dependencies that are required and that will be
injected in any field with the same dependency type.
* @return this builder
*/
B withSrv(Class<?> ... services);
/**
- * Adds a service dependency.
+ * Adds a service dependency built using a Consumer lambda that is
provided with a ServiceDependencyBuilder.
*
* @param <U> the type of the dependency service
* @param service the service
@@ -353,8 +366,8 @@ public interface ComponentBuilder<B exte
B withCnf(Consumer<ConfigurationDependencyBuilder> consumer);
/**
- * Adds multiple configuration dependencies in one single call.
- * @param pids list of configuration pids
+ * Adds multiple configuration dependencies in one single call. All
configurations are injected by default in the "updated" callback.
+ * @param pids list of configuration pids.
* @return this builder
*/
@SuppressWarnings("unchecked")
Modified:
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/ConfigurationDependencyBuilder.java
URL:
http://svn.apache.org/viewvc/felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/ConfigurationDependencyBuilder.java?rev=1727768&r1=1727767&r2=1727768&view=diff
==============================================================================
---
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/ConfigurationDependencyBuilder.java
(original)
+++
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/ConfigurationDependencyBuilder.java
Sat Jan 30 23:49:06 2016
@@ -7,7 +7,7 @@ import org.apache.felix.dm.lambda.callba
import org.apache.felix.dm.lambda.callbacks.CbTypeDictionary;
/**
- * Defines a builder for a DM Configuration Dependency.
+ * Builds a Dependency Manager Configuration Dependency.
* By default, the updated callback is "updated", like in original DM API.
*
* <p> Code example with a component that defines a Configuration Dependency.
the ServiceImpl modified method
@@ -35,7 +35,7 @@ public interface ConfigurationDependency
ConfigurationDependencyBuilder pid(String pid);
/**
- * Sets the class which fqdn represents the pid for this configuration
dependency.
+ * Sets the class which fqdn represents the pid for this configuration
dependency. Usually, this class can optionally be annotated with metatypes bnd
annotations.
*
* @param pidClass the class which fqdn represents the pid for this
configuration dependency.
* @return this builder
@@ -43,22 +43,23 @@ public interface ConfigurationDependency
ConfigurationDependencyBuilder pid(Class<?> pidClass);
/**
- * Sets that all public configuration properties are propagated to the
component service properties (false by default).
+ * Sets propagation of the configuration properties to the service
properties (false by default).
+ * All public configuration properties (not starting with a dot) will be
propagated to the component service properties.
*
* @return this builder
*/
ConfigurationDependencyBuilder propagate();
/**
- * Sets that all public configuration properties are propagated to the
component service properties (false by default).
+ * Sets propagation of the configuration properties to the service
properties (false by default).
*
- * @param propagate true if all public configuration properties must be
propagated to the component service properties (false by default)
+ * @param propagate true if all public configuration properties (not
starting with a dot) must be propagated to the component service properties
(false by default)
* @return this builder
*/
ConfigurationDependencyBuilder propagate(boolean propagate);
/**
- * Sets if the component instance should be instantiated at the time the
updated callback is invoked.
+ * Configures whether or not the component instance should be instantiated
at the time the updated callback is invoked.
* By default, when the callback is applied on an external object
instance, the component is not instantiated, but in this case
* you can force the creation of the component instances by calling this
method.
*
Modified:
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/FactoryPidAdapterBuilder.java
URL:
http://svn.apache.org/viewvc/felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/FactoryPidAdapterBuilder.java?rev=1727768&r1=1727767&r2=1727768&view=diff
==============================================================================
---
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/FactoryPidAdapterBuilder.java
(original)
+++
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/FactoryPidAdapterBuilder.java
Sat Jan 30 23:49:06 2016
@@ -6,9 +6,12 @@ import org.apache.felix.dm.lambda.callba
import org.apache.felix.dm.lambda.callbacks.CbTypeDictionary;
/**
- * Builder for a DM Factory Configuration Adapter Component.<p>
+ * Builds a Dependency Manager Factory Configuration Adapter Component. For
each new Config Admin factory configuration matching the factoryPid,
+ * an adapter will be created based on the adapter implementation class. The
adapter will be registered with the specified interface,
+ * and with the specified adapter service properties. Depending on the
propagate parameter, every public factory configuration properties
+ * (which don't start with ".") will be propagated along with the adapter
service properties.
*
- * Example that defines a factory configuration adapter service for the
"foo.bar" factory pid:
+ * <p> Example that defines a factory configuration adapter service for the
"foo.bar" factory pid:
*
* <pre> {@code
* public class Activator extends DependencyManagerActivator {
Modified:
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/FutureDependencyBuilder.java
URL:
http://svn.apache.org/viewvc/felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/FutureDependencyBuilder.java?rev=1727768&r1=1727767&r2=1727768&view=diff
==============================================================================
---
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/FutureDependencyBuilder.java
(original)
+++
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/FutureDependencyBuilder.java
Sat Jan 30 23:49:06 2016
@@ -9,17 +9,17 @@ import org.apache.felix.dm.lambda.callba
/**
* Defines a builder for a CompletableFuture dependency.
* Using such dependency allows your component to wait for the completion of a
given asynchronous task
- * represented by a standard jdk <code>CompletableFuture</code> object;
+ * represented by a standard jdk <code>CompletableFuture</code> object.
*
- * A FutureDependency is required and unblock the Component once the future
result has completed.
+ * A FutureDependency is required and unblock the Component once the
CompletableFuture result has completed.
*
- * <h3>Usage Examples</h3>
+ * <h3>Usage Example</h3>
*
* <p> Here is an Activator that downloads a page from the web and injects the
string result to a component.
* When the web page is downloaded, the result is injected in the
MyComponent::setPage method and
* the component is then called in its "start" method:
*
- * <pre> {@code
+ * <pre>{@code
*
* public class Activator extends DependencyManagerActivator {
* public void activate() throws Exception {
@@ -27,34 +27,39 @@ import org.apache.felix.dm.lambda.callba
* CompletableFuture<String> page = CompletableFuture.supplyAsync(() ->
downloadSite(url));
*
* // The component depends on a log service and on the content of the
Felix site.
+ * // The lambda passed to the "withFuture" method configures the
callback that is
+ * // invoked with the result of the CompletableFuture (the page content).
* component(comp -> comp
* .impl(MyComponent.class)
- * .withService(LogService.class, log ->
log.onAdd(MyComponent::bindLog))
- * .withFuture(page, future -> future.cb(MyComponent::setPage)));
+ * .withService(LogService.class)
+ * .withFuture(page, result -> result.cb(MyComponent::setPage)));
* }
* }
+ *
+ * public class MyComponent {
+ * void setPage(String page) {
+ * // injected by the FutureDependency.
+ * }
+ *
+ * void start() {
+ * // all required dependencies injected.
+ * }
+ * }
+ *
* }</pre>
*
* @param <F> the type of the CompletableFuture result.
*/
public interface FutureDependencyBuilder<F> extends
DependencyBuilder<Dependency> {
/**
- * Sets the callback method name to invoke on the component instances,
once the CompletableFuture on which we depend has completed.
+ * Sets the callback method name to invoke on the component instances,
once the CompletableFuture has completed.
* @param callback the callback method name to invoke on the component
instances, once the CompletableFuture on which we depend has completed.
* @return this dependency.
*/
FutureDependencyBuilder<F> cb(String callback);
/**
- * Sets the callback instance method name to invoke on the component
instances, once the CompletableFuture on which we depend has completed.
- * @param callbackInstance the object instance on which the callback must
be invoked
- * @param callback the callback method name to invoke on the component
instances, once the CompletableFuture on which we depend has completed.
- * @return this dependency.
- */
- FutureDependencyBuilder<F> cbi(Object callbackInstance, String callback);
-
- /**
- * Sets the function to invoke when the future task has completed. The
function is one of the Component instances method that accepts the
+ * Sets the function to invoke when the future task has completed. The
function is from one of the Component implementation classes, and it accepts the
* result of the completed future.
*
* @param <T> the type of the CompletableFuture result.
@@ -64,8 +69,8 @@ public interface FutureDependencyBuilder
<T> FutureDependencyBuilder<F> cb(CbTypeFuture<T, ? super F> callback);
/**
- * Sets the function to invoke asynchronously when the future task has
completed. The function is one of the Component instances method that accepts
the
- * result of the completed future.
+ * Sets the function to invoke asynchronously when the future task has
completed. The function is from one of the Component implementation classes,
+ * and it accepts the result of the completed future.
*
* @param <T> the type of the CompletableFuture result.
* @param callback the function to perform when the future task as
completed.
@@ -75,18 +80,26 @@ public interface FutureDependencyBuilder
<T> FutureDependencyBuilder<F> cb(CbTypeFuture<T, ? super F> callback,
boolean async);
/**
- * Sets the function to invoke asynchronously when the future task has
completed. The function is one of the Component instances method that accepts
the
- * result of the completed future.
+ * Sets the function to invoke asynchronously when the future task has
completed. The function is from one of the Component implementation classes,
+ * and it accepts the result of the completed future.
*
* @param <T> the type of the CompletableFuture result.
* @param callback the function to perform when the future task as
completed.
- * @param executor the executor used to schedule the action.
+ * @param executor the executor used to schedule the callback.
* @return this dependency
*/
<T> FutureDependencyBuilder<F> cb(CbTypeFuture<T, ? super F> callback,
Executor executor);
/**
- * Sets the callback instance to invoke when the future task has
completed. The action is a Consumer instance which accepts the
+ * Sets the callback instance method name to invoke on a given Object
instance, once the CompletableFuture has completed.
+ * @param callbackInstance the object instance on which the callback must
be invoked
+ * @param callback the callback method name to invoke on Object instance,
once the CompletableFuture has completed.
+ * @return this dependency.
+ */
+ FutureDependencyBuilder<F> cbi(Object callbackInstance, String callback);
+
+ /**
+ * Sets the callback instance to invoke when the future task has
completed. The callback is a Consumer instance which accepts the
* result of the completed future.
* @param callback a Consumer instance which accepts the result of the
completed future.
* @return this dependency
@@ -94,7 +107,7 @@ public interface FutureDependencyBuilder
FutureDependencyBuilder<F> cbi(CbFuture<? super F> callback);
/**
- * Sets the action to perform asynchronously when the future task has
completed. The action is a Consumer instance which accepts the
+ * Sets the callback instance to invoke when the future task has
completed. The callback is a Consumer instance which accepts the
* result of the completed future.
*
* @param callback a Consumer instance which accepts the result of the
completed future.
@@ -104,10 +117,10 @@ public interface FutureDependencyBuilder
FutureDependencyBuilder<F> cbi(CbFuture<? super F> callback, boolean
async);
/**
- * Sets the action to perform asynchronously when the future task has
completed. The action is a Consumer instance which accepts the
+ * Sets the callback instance to invoke when the future task has
completed. The callback is a Consumer instance which accepts the
* result of the completed future.
* @param callback the action to perform when the future task as
completed.
- * @param executor the executor to use for asynchronous execution of the
action.
+ * @param executor the executor to use for asynchronous execution of the
callback.
* @return this dependency
*/
FutureDependencyBuilder<F> cbi(CbFuture<? super F> callback, Executor
executor);
Modified:
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/ServiceAdapterBuilder.java
URL:
http://svn.apache.org/viewvc/felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/ServiceAdapterBuilder.java?rev=1727768&r1=1727767&r2=1727768&view=diff
==============================================================================
---
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/ServiceAdapterBuilder.java
(original)
+++
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/ServiceAdapterBuilder.java
Sat Jan 30 23:49:06 2016
@@ -1,12 +1,12 @@
package org.apache.felix.dm.lambda;
/**
- * Defines the interface for a DependencyManager adapter builder.
+ * Builds a Dependency Manager Service Adapter Component.
* The adapter will be applied to any service that matches the specified
interface and filter. For each matching service an adapter will be created
* based on the adapter implementation class. The adapter will be registered
with the specified interface and existing properties from the original
* service plus any extra properties you supply here.<p>
*
- * Code example that adapts a "Device" service to an HttpServlet service. the
adapter accepts a lambda that is provided with an AdapterBuilder
+ * Code example that adapts a "Device" service to an HttpServlet service. The
adapter is created using a ServiceAdapterBuilder that is passed to the lambda.
*
* <pre> {@code
* public class Activator extends DependencyManagerActivator {
Modified:
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/ServiceAspectBuilder.java
URL:
http://svn.apache.org/viewvc/felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/ServiceAspectBuilder.java?rev=1727768&r1=1727767&r2=1727768&view=diff
==============================================================================
---
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/ServiceAspectBuilder.java
(original)
+++
felix/sandbox/pderop/dependencymanager-lambda/org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/ServiceAspectBuilder.java
Sat Jan 30 23:49:06 2016
@@ -1,22 +1,33 @@
package org.apache.felix.dm.lambda;
/**
- * Defines the interface for a DependencyManager aspect builder.
- * The aspect will be applied to any service that matches the specified
interface and filter. For each matching service an aspect will be created based
+ * Builds a Dependency Manager Aspect Component.
+ * The aspect will be applied to any service that matches the specified
interface and filter (if any). For each matching service an aspect will be
created based
* on the aspect implementation class.
- * The aspect will be registered with the same interface and properties as the
original service, plus any extra properties you supply here. <p>
+ * The aspect will be registered with the same interface and properties as the
original service, plus any extra properties you supply here.
+ * Multiple Aspects of the same service are chained and ordered using aspect
ranks.
*
- * Code example that provides an aspect service for an English dictionary
service (the aspect service is injected in the DictionaryAspect::bind method):
+ * <p> Code example that provides a "LogService" aspect that performs
spell-checking of each log message.
+ * The aspect decorates a LogService. The aspect also depends on an Dictionary
service that is internally used to perform log spell checking.
+ * The LogService and Dictionary services are injected in the aspect
implementation using reflection on class fields:
*
- * <pre> {@code
+ * <pre>{@code
* public class Activator extends DependencyManagerActivator {
* public void activate() throws Exception {
- * aspect(DictionaryService.class, asp -> asp
- * .filter("(lang=en)").rank(10).impl(DictionaryAspect.class)
- * .cb(dict -> dict.cb(DictionaryAspect::bind))
- * .withSrv(LogService.class, log -> log.required(false)));
+ * aspect(LogService.class, asp ->
asp.impl(SpellCheckLogAspect.class).rank(10).withSrv(Dictionary.class));
* }
- * }}</pre>
+ * }} </pre>
+ *
+ * Same example, but using callbacks for injecting LogService and Dictionary
services in the aspect implementation class:
+ *
+ * <pre>{@code
+ * public class Activator extends DependencyManagerActivator {
+ * public void activate() throws Exception {
+ * aspect(LogService.class, asp ->
asp.impl(SpellCheckLogAspect.class).rank(10)
+ * .cb(SpellCheckLogAspect::setLogService)
+ * .withSrv(Dictionary.class, dict ->
dict.cb(SpellCheckLogAspect::setDictionary)));
+ * }
+ * }} </pre>
*
* @param <T> the aspect service
*/
