blob: 603bd08c43733b395c72bd1a3cc47bc85064c653 [file] [log] [blame]
package org.apache.felix.dm.lambda;
import org.apache.felix.dm.lambda.callbacks.CbRefServiceRefService;
import org.apache.felix.dm.lambda.callbacks.CbRefServiceRefServiceComponent;
import org.apache.felix.dm.lambda.callbacks.CbService;
import org.apache.felix.dm.lambda.callbacks.CbServiceComponent;
import org.apache.felix.dm.lambda.callbacks.CbServiceComponentRef;
import org.apache.felix.dm.lambda.callbacks.CbServiceDict;
import org.apache.felix.dm.lambda.callbacks.CbServiceMap;
import org.apache.felix.dm.lambda.callbacks.CbServiceRef;
import org.apache.felix.dm.lambda.callbacks.CbServiceService;
import org.apache.felix.dm.lambda.callbacks.CbServiceServiceComponent;
import org.apache.felix.dm.lambda.callbacks.InstanceCbRefServiceRefService;
import org.apache.felix.dm.lambda.callbacks.InstanceCbRefServiceRefServiceComponent;
import org.apache.felix.dm.lambda.callbacks.InstanceCbService;
import org.apache.felix.dm.lambda.callbacks.InstanceCbServiceComponent;
import org.apache.felix.dm.lambda.callbacks.InstanceCbServiceComponentRef;
import org.apache.felix.dm.lambda.callbacks.InstanceCbServiceDict;
import org.apache.felix.dm.lambda.callbacks.InstanceCbServiceMap;
import org.apache.felix.dm.lambda.callbacks.InstanceCbServiceRef;
import org.apache.felix.dm.lambda.callbacks.InstanceCbServiceService;
import org.apache.felix.dm.lambda.callbacks.InstanceCbServiceServiceComponent;
/**
* Builds a service dependency callback (required by default).
*
* A Service may be injected in a bind-method of a component or an object instance using this builder.
* The builder supports reflection based callbacks (same as with the original DM API), as well as java8 method reference based callbacks.
*
* <p> <b> List of signatures supported using reflection based callbacks (same as original DM API): </b>
*
* <pre> {@code
* method(S service)
* method(S service, Map<String, Object> serviceProperties)
* method(S service, Dictionary<String, Object> serviceProperties)
* method(ServiceReference<S> serviceRef, S service),
* method(ServiceReference<S> serviceRef)
* method(Component serviceComponent)
* method(Component serviceComponent, ServiceReference<S> serviceRef)
* method(Component serviceComponent, S service)
* method(Component serviceComponent, ServiceReference<S> serviceRef, S service)
* swapMethod(S oldService, S newService)
* swapMethod(ServiceReference<S> oldRef, S old, ServiceReference<S> newRef, S newService)
* swapMethod(Component component, S oldService, S newService)
* swapMethod(Component component, ServiceReference<S> oldRef, S old, ServiceReference<S> newRef, S newService)
* }</pre>
*
* <b> List of signatures supported using java 8 method references: </b>
*
* <pre> {@code
* method(S service)
* method(S service, ServiceReference<S> serviceRef),
* method(S service, Map<String, Object> serviceProperties)
* method(S service, Dictionary<String, Object> serviceProperties)
* method(S service, Component serviceComponent)
* method(S service, Component serviceComponent, ServiceReference<S> serviceRef)
* swapMethod(S oldService, S newService)
* swapMethod(S oldService, S newService, Component component))
* swapMethod(ServiceReference<S> oldRef, S old, ServiceReference<S> newRef, S newService)
* swapMethod(ServiceReference<S> oldRef, S old, ServiceReference<S> newRef, S newService, Component component)
* }</pre>
*
* <p> Here is an example of a Component that defines a dependency of a LogService which is injected in the "setLog" method using a ServiceCallbacksBuilder:
* The withSvc(...)" declaration defines a method reference on the "Pojo::setLog" method (using a lambda):
*
* <pre> {@code
* public class Activator extends DependencyManagerActivator {
* public void init(BundleContext ctx, DependencyManager dm) throws Exception {
* component(comp -> comp.impl(Pojo.class).withSvc(LogService.class, log -> log.add(Pojo::setLog)));
* }
* }}</pre>
*
* <p> Same example, but we inject the dependency to an object instance that we already have in hand:
*
* <pre> {@code
* public class Activator extends DependencyManagerActivator {
* public void init(BundleContext ctx, DependencyManager dm) throws Exception {
* Pojo impl = new Pojo();
* component(comp -> comp.impl(impl).withSvc(LogService.class, log -> log.add(impl::setLog)));
* }
* }}</pre>
*
* <p> Here, we inject a service using method reflection (as it is the case in original DM api):
*
* <pre> {@code
* public class Activator extends DependencyManagerActivator {
* public void init(BundleContext ctx, DependencyManager dm) throws Exception {
* component(comp -> comp.impl(Pojo::class).withSvc(LogService.class, log -> log.add("setLog")));
* }
* }}</pre>
*
* @param <S> the service dependency type
* @param <B> the type of a sub interface that may extends this interface.
*
* @author <a href="mailto:dev@felix.apache.org">Felix Project Team</a>
*/
public interface ServiceCallbacksBuilder<S, B extends ServiceCallbacksBuilder<S, B>> {
/**
* Sets the callback instance used for reflection based callbacks.
* @param callbackInstance the object on which reflection based callbacks are invoked on.
* @return this builder
*/
B callbackInstance(Object callbackInstance);
/**
* Sets <code>callback</code> methods to invoke when a service is added. When a service matches the service
* filter, then the service is injected using the specified callback method. The callback is invoked on the component instances, or on the callback
* instance, is specified using the {@link #callbackInstance(Object)} method.
*
* The following method signature are supported:
* <pre>{@code
* method(S service)
* method(S service, Map<String, Object> serviceProperties)
* method(S service, Dictionary<String, Object> serviceProperties)
* method(ServiceReference<S> serviceRef, S service),
* method(ServiceReference<S> serviceRef)
* method(Component serviceComponent)
* method(Component serviceComponent, ServiceReference<S> serviceRef)
* method(Component serviceComponent, S service)
* method(Component serviceComponent, ServiceReference<S> serviceRef, S service)
* }</pre>
*
* @param callback the add callback
* @return this builder
* @see #callbackInstance(Object)
*/
B add(String callback);
/**
* Sets <code>callback</code> methods to invoke when a service is changed. When a changed service matches the service
* filter, then the service is injected using the specified callback method. The callback is invoked on the component instances, or on the callback
* instance, is specified using the {@link #callbackInstance(Object)} method.
*
* The following method signature are supported:
* <pre>{@code
* method(S service)
* method(S service, Map<String, Object> serviceProperties)
* method(S service, Dictionary<String, Object> serviceProperties)
* method(ServiceReference<S> serviceRef, S service),
* method(ServiceReference<S> serviceRef)
* method(Component serviceComponent)
* method(Component serviceComponent, ServiceReference<S> serviceRef)
* method(Component serviceComponent, S service)
* method(Component serviceComponent, ServiceReference<S> serviceRef, S service)
* }</pre>
*
* @param callback the change callback
* @return this builder
* @see #callbackInstance(Object)
*/
B change(String callback);
/**
* Sets <code>callback</code> methods to invoke when a service is removed. When a removed service matches the service
* filter, then the specified callback in invoked with the removed service. The callback is invoked on the component instances, or on the callback
* instance, is specified using the {@link #callbackInstance(Object)} method.
*
* The following method signature are supported:
* <pre>{@code
* method(S service)
* method(S service, Map<String, Object> serviceProperties)
* method(S service, Dictionary<String, Object> serviceProperties)
* method(ServiceReference<S> serviceRef, S service),
* method(ServiceReference<S> serviceRef)
* method(Component serviceComponent)
* method(Component serviceComponent, ServiceReference<S> serviceRef)
* method(Component serviceComponent, S service)
* method(Component serviceComponent, ServiceReference<S> serviceRef, S service)
* }</pre>
*
* @param callback the remove callback
* @return this builder
* @see #callbackInstance(Object)
*/
B remove(String callback);
/**
* Sets <code>callback</code> methods to invoke when a service is swapped. The callback is invoked on the component instances, or on the callback
* instance, is specified using the {@link #callbackInstance(Object)} method.
*
* The following method signature are supported:
* <pre>{@code
* swapMethod(S oldService, S newService)
* swapMethod(ServiceReference<S> oldRef, S old, ServiceReference<S> newRef, S newService)
* swapMethod(Component component, S oldService, S newService)
* swapMethod(Component component, ServiceReference<S> oldRef, S old, ServiceReference<S> newRef, S newService)
* }</pre>
*
* @param callback the remove callback
* @return this builder
* @see #callbackInstance(Object)
*/
B swap(String callback);
/**
* Sets a <code>component instance callback(Service)</code> callback. The callback is invoked when a service is added.
* The method reference must point to a Component implementation class method.
*
* @param <T> the type of the component instance class on which the callback is invoked.
* @param add the method reference invoked when a service is added.
* @return this builder
*/
<T> B add(CbService<T, S> add);
/**
* Sets a <code>component instance callback(Service)</code> callback. The callback is invoked when a service is changed.
* The method reference must point to a Component implementation class method.
*
* @param <T> the type of the component instance class on which the callback is invoked.
* @param change the method reference invoked when a service is changed.
* @return this builder
*/
<T> B change(CbService<T, S> change);
/**
* Sets a <code>component instance callback(Service)</code> callback. The callback is invoked when a service is removed.
* The method reference must point to a Component implementation class method.
*
* @param <T> the type of the component instance class on which the callback is invoked.
* @param remove the method reference invoked when a service is removed.
* @return this builder
*/
<T> B remove(CbService<T, S> remove);
/**
* Sets a {@code component instance callback(Service, Map<String, Object>)} callback. The callback is invoked when a service is added.
* The method reference must point to a Component implementation class method.
*
* @param <T> the type of the component instance class on which the callback is invoked.
* @param add the method reference invoked when a service is added.
* @return this builder
*/
<T> B add(CbServiceMap<T, S> add);
/**
* Sets a {@code component instance callback(Service, Map<String, Object>)} callback. The callback is invoked when a service is changed.
* The method reference must point to a Component implementation class method.
*
* @param <T> the type of the component instance class on which the callback is invoked.
* @param change the method reference invoked when a service is changed.
* @return this builder
*/
<T> B change(CbServiceMap<T, S> change);
/**
* Sets a {@code component instance callback(Service, Map<String, Object></code>)} callback. The callback is invoked when a service is removed.
* The method reference must point to a Component implementation class method.
*
* @param <T> the type of the component instance class on which the callback is invoked.
* @param remove the method reference invoked when a service is removed.
* @return this builder
*/
<T> B remove(CbServiceMap<T, S> remove);
/**
* Sets a {@code component instance callback(Service, Dictionary<String, Object>)} callback. The callback is invoked when a service is added.
* The method reference must point to a Component implementation class method.
*
* @param <T> the type of the component instance class on which the callback is invoked.
* @param add the method reference invoked when a service is added.
* @return this builder
*/
<T> B add(CbServiceDict<T, S> add);
/**
* Sets a {@code component instance callback(Service, Dictionary<String, Object>)} callback. The callback is invoked when a service is changed.
* The method reference must point to a Component implementation class method.
*
* @param <T> the type of the component instance class on which the callback is invoked.
* @param change the method reference invoked when a service is changed.
* @return this builder
*/
<T> B change(CbServiceDict<T, S> change);
/**
* Sets a {@code component instance callback(Service, Dictionary<String, Object>)} callback. The callback is invoked when a service is removed.
* The method reference must point to a Component implementation class method.
*
* @param <T> the type of the component instance class on which the callback is invoked.
* @param remove the method reference invoked when a service is removed.
* @return this builder
*/
<T> B remove(CbServiceDict<T, S> remove);
/**
* Sets a <code>component instance callback(Service, ServiceReference)</code> callback. The callback is invoked when a service is added.
* The method reference must point to a Component implementation class method.
* @param <T> the type of the component instance class on which the callback is invoked.
* @param add the method reference invoked when a service is added.
* @return this builder
*/
<T> B add(CbServiceRef<T, S> add);
/**
* Sets a <code>component instance callback(Service, ServiceReference)</code> callback. The callback is invoked when a service is changed.
* The method reference must point to a Component implementation class method.
*
* @param <T> the type of the component instance class on which the callback is invoked.
* @param change the method reference invoked when a service is changed.
* @return this builder
*/
<T> B change(CbServiceRef<T, S> change);
/**
* Sets a <code>component instance callback(Service, ServiceReference)</code> callback. The callback is invoked when a service is removed.
* The method reference must point to a Component implementation class method.
*
* @param <T> the type of the component instance class on which the callback is invoked.
* @param remove the method reference invoked when a service is removed.
* @return this builder
*/
<T> B remove(CbServiceRef<T, S> remove);
/**
* Sets a <code>component instance callback(Service, Component)</code> callback. The callback is invoked when a service is added.
* The method reference must point to a Component implementation class method.
*
* @param <T> the type of the component instance class on which the callback is invoked.
* @param add the method reference invoked when a service is added.
* @return this builder
*/
<T> B add(CbServiceComponent<T, S> add);
/**
* Sets a <code>component instance callback(Service, Component)</code> callback. The callback is invoked when a service is changed.
* The method reference must point to a Component implementation class method.
*
* @param <T> the type of the component instance class on which the callback is invoked.
* @param change the method reference invoked when a service is changed.
* @return this builder
*/
<T> B change(CbServiceComponent<T, S> change);
/**
* Sets a <code>component instance callback(Service, Component)</code> callback. The callback is invoked when a service is removed.
* The method reference must point to a Component implementation class method.
*
* @param <T> the type of the component instance class on which the callback is invoked.
* @param remove the method reference invoked when a service is removed.
* @return this builder
*/
<T> B remove(CbServiceComponent<T, S> remove);
/**
* Sets a <code>component instance callback(Service, Component, ServiceReference ref)</code> callback. The callback is invoked when a service is added.
* The method reference must point to a Component implementation class method.
*
* @param <T> the type of the component instance class on which the callback is invoked.
* @param add the method reference invoked when a service is added.
* @return this builder
*/
<T> B add(CbServiceComponentRef<T, S> add);
/**
* Sets a <code>component instance callback(Service, Component, ServiceReference)</code> callback. The callback is invoked when a service is changed.
* The method reference must point to a Component implementation class method.
*
* @param <T> the type of the component instance class on which the callback is invoked.
* @param change the method reference invoked when a service is changed.
* @return this builder
*/
<T> B change(CbServiceComponentRef<T, S> change);
/**
* Sets a <code>component instance callback(Service, Component, ServiceReference)</code> callback. The callback is invoked when a service is removed.
* The method reference must point to a Component implementation class method.
*
* @param <T> the type of the component instance class on which the callback is invoked.
* @param remove the method reference invoked when a service is removed.
* @return this builder
*/
<T> B remove(CbServiceComponentRef<T, S> remove);
/**
* Sets an <code>object instance callback(Service)</code> callback. The callback is invoked when a service is added.
* The method reference must point to a method from an Object instance.
*
* @param add the method reference invoked when a service is added.
* @return this builder
*/
B add(InstanceCbService<S> add);
/**
* Sets an <code>object instance callback(Service)</code> callback. The callback is invoked when a service is changed.
* The method reference must point to method from an Object instance.
*
* @param change the method reference invoked when a service is changed.
* @return this builder
*/
B change(InstanceCbService<S> change);
/**
* Sets an <code>object instance callback(Service)</code> callback. The callback is invoked when a service is removed.
* The method reference must point to method from an Object instance.
*
* @param remove the method reference invoked when a service is removed.
* @return this builder
*/
B remove(InstanceCbService<S> remove);
/**
* Sets an {@code object instance callback(Service, Map<String, Object>)} callback. The callback is invoked when a service is added.
* The method reference must point to a method from an Object instance.
*
* @param add the method reference invoked when a service is added.
* @return this builder
*/
B add(InstanceCbServiceMap<S> add);
/**
* Sets an {@code object instance callback(Service, Map<String, Object>)} callback. The callback is invoked when a service is changed.
* The method reference must point to method from an Object instance.
*
* @param change the method reference invoked when a service is changed.
* @return this builder
*/
B change(InstanceCbServiceMap<S> change);
/**
* Sets an {@code object instance callback(Service, Map<String, Object>)} callback. The callback is invoked when a service is removed.
* The method reference must point to method from an Object instance.
*
* @param remove the method reference invoked when a service is removed.
* @return this builder
*/
B remove(InstanceCbServiceMap<S> remove);
/**
* Sets an {@code object instance callback(Service svc, Dictionary<String, Object>} callback. The callback is invoked when a service is added.
* The method reference must point to a method from an Object instance.
*
* @param add the method reference invoked when a service is added.
* @return this builder
*/
B add(InstanceCbServiceDict<S> add);
/**
* Sets an {@code object instance callback(Service, Dictionary<String, Object>)} callback. The callback is invoked when a service is changed.
* The method reference must point to method from an Object instance.
*
* @param change the method reference invoked when a service is changed.
* @return this builder
*/
B change(InstanceCbServiceDict<S> change);
/**
* Sets an {@code object instance callback(Service, Dictionary<String, Object>)} callback. The callback is invoked when a service is removed.
* The method reference must point to method from an Object instance.
*
* @param remove the method reference invoked when a service is removed.
* @return this builder
*/
B remove(InstanceCbServiceDict<S> remove);
/**
* Sets an <code>object instance callback(Service, ServiceReference)</code> callback. The callback is invoked when a service is added.
* The method reference must point to a method from an Object instance.
*
* @param add the method reference invoked when a service is added.
* @return this builder
*/
B add(InstanceCbServiceRef<S> add);
/**
* Sets an <code>object instance callback(Service, ServiceReference)</code> callback. The callback is invoked when a service is changed.
* The method reference must point to method from an Object instance.
*
* @param change the method reference invoked when a service is changed.
* @return this builder
*/
B change(InstanceCbServiceRef<S> change);
/**
* Sets an <code>object instance callback(Service, ServiceReference)</code> callback. The callback is invoked when a service is removed.
* The method reference must point to method from an Object instance.
*
* @param remove the method reference invoked when a service is removed.
* @return this builder
*/
B remove(InstanceCbServiceRef<S> remove);
/**
* Sets an <code>object instance callback(Service, Component)</code> callback invoked. The callback is when a service is added.
* The method reference must point to a method from an Object instance.
*
* @param add the method reference invoked when a service is added.
* @return this builder
*/
B add(InstanceCbServiceComponent<S> add);
/**
* Sets an <code>object instance callback(Service, Component)</code> callback invoked. The callback is when a service is changed.
* The method reference must point to method from an Object instance.
*
* @param change the method reference invoked when a service is changed.
* @return this builder
*/
B change(InstanceCbServiceComponent<S> change);
/**
* Sets an <code>object instance callback(Service, Component)</code> callback. The callback is invoked when a service is removed.
* The method reference must point to method from an Object instance.
*
* @param remove the method reference invoked when a service is removed.
* @return this builder
*/
B remove(InstanceCbServiceComponent<S> remove);
/**
* Sets an <code>object instance callback(Service, Component, ServiceReference)</code> callback. The callback is invoked when a service is added.
* The method reference must point to a method from an Object instance.
*
* @param add the method reference invoked when a service is added.
* @return this builder
*/
B add(InstanceCbServiceComponentRef<S> add);
/**
* Sets an <code>object instance callback(Service, Component, ServiceReference)</code> callback. The callback is invoked when a service is changed.
* The method reference must point to method from an Object instance.
*
* @param change the method reference invoked when a service is changed.
* @return this builder
*/
B change(InstanceCbServiceComponentRef<S> change);
/**
* Sets an <code>object instance callback(Service, Component, ServiceReference)</code> callback. The callback is invoked when a service is removed.
* The method reference must point to method from an Object instance.
*
* @param remove the method reference invoked when a service is removed.
* @return this builder
*/
B remove(InstanceCbServiceComponentRef<S> remove);
/**
* Sets a swap <code>component instance callback(Service, Service)</code> method reference. The callback is invoked when a service is swapped.
* The method reference must point to a Component implementation class method.
*
* @param <T> the type of the component instance class on which the callback is invoked.
* @param swap the method reference invoked when the service is swapped.
* @return this builder
*/
<T> B swap(CbServiceService<T, S> swap);
/**
* Sets a wap <code>component instance callback(Service, Service, Component)</code> method reference. The callback is invoked when a service is swapped.
* The method reference must point to a Component implementation class method.
*
* @param <T> the type of the component instance class on which the callback is invoked.
* @param swap the method reference invoked when the service is swapped.
* @return this builder
*/
<T> B swap(CbServiceServiceComponent<T, S> swap);
/**
* Sets a swap <code>component instance callback(ServiceReference, Service, ServiceReference, Service)</code> method reference. The callback is invoked when a service is swapped.
* The method reference must point to a Component implementation class method.
* the new service.
*
* @param <T> the type of the component instance class on which the callback is invoked.
* @param swap the method reference invoked when the service is swapped.
* @return this builder
*/
<T> B swap(CbRefServiceRefService<T, S> swap);
/**
* Sets a swap <code>component instance callback(ServiceReference, Service, ServiceReference, Service, Component</code> method reference. The callback is invoked when a service is swapped.
* The method reference must point to a Component implementation class method.
* the new service.
*
* @param <T> the type of the component instance class on which the callback is invoked.
* @param swap the method reference invoked when the service is swapped.
* @return this builder
*/
<T> B swap(CbRefServiceRefServiceComponent<T, S> swap);
/**
* Sets a swap <code>instance callback(Service, Service)</code> method reference. The callback is invoked when a service is swapped.
* The method reference must point to a method from an Object instance.
*
* @param swap the method reference invoked when the service is swapped.
* @return this builder
*/
B swap(InstanceCbServiceService<S> swap);
/**
* Sets a swap <code>instance callback(Service, Service, Component)</code> method reference. The callback is invoked when a service is swapped.
* The method reference must point to a method from an Object instance.
*
* @param swap the method reference invoked when the service is swapped.
* @return this builder
*/
B swap(InstanceCbServiceServiceComponent<S> swap);
/**
* Sets a swap <code>instance callback(ServiceReference, Service, ServiceReference, Service)</code> method reference. The callback is invoked when a service is swapped.
* The method reference must point to a method from an Object instance.
*
* @param swap the method reference invoked when the service is swapped.
* @return this builder
*/
B swap(InstanceCbRefServiceRefService<S> swap);
/**
* Sets a swap <code>instance callback(ServiceReference, Service, ServiceReference, Service, Component)</code> method reference. The callback is invoked when a service is swapped.
* The method reference must point to a method from an Object instance.
*
* @param swap the method reference invoked when the service is swapped.
* @return this builder
*/
B swap(InstanceCbRefServiceRefServiceComponent<S> swap);
}