felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From pde...@apache.org
Subject svn commit: r1727768 [1/2] - in /felix/sandbox/pderop/dependencymanager-lambda: org.apache.felix.dependencymanager.lambda.itest/src/org/apache/felix/dm/lambda/itest/ org.apache.felix.dependencymanager.lambda/src/org/apache/felix/dm/lambda/
Date Sat, 30 Jan 2016 23:49:06 GMT
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
  */



Mime
View raw message