Package org.apache.felix.dm

Interface ServiceDependency

All Superinterfaces:
ComponentDependencyDeclaration, Dependency
@ProviderType public interface ServiceDependency extends Dependency, ComponentDependencyDeclaration
Service dependency that can track an OSGi service. When defining dependency method callbacks; for "add", "change", "remove" callbacks, the following method signatures are supported: 

 (Component comp, ServiceReference ref, Service service)
 (Component comp, ServiceReference ref, Object service)
 (Component comp, ServiceReference ref)
 (Component comp, Service service)
 (Component comp, Object service)
 (Component comp)
 (Component comp, Map properties, Service service)
 (ServiceReference ref, Service service)
 (ServiceReference ref, Object service)
 (ServiceReference ref)
 (Service service)
 (Service service, Map propeerties)
 (Map properties, Service, service)
 (Service service, Dictionary properties)
 (Dictionary properties, Service service)
 (Object service)
 (ServiceObjects service)

For "swap" callbacks, the following method signatures are supported: 


 (Service old, Service replace)
 (Object old, Object replace)
 (ServiceReference old, Service old, ServiceReference replace, Service replace)
 (ServiceReference old, Object old, ServiceReference replace, Object replace)
 (Component comp, Service old, Service replace)
 (Component comp, Object old, Object replace)
 (Component comp, ServiceReference old, Service old, ServiceReference replace, Service replace)
 (Component comp, ServiceReference old, Object old, ServiceReference replace, Object replace)
 (ServiceReference old, ServiceReference replace)
 (Component comp, ServiceReference old, ServiceReference replace)
 (ServiceObjects old, ServiceObjects replace)
 (Component comp, ServiceObjects old, ServiceObjects replace)
Author:
Felix Project Team

  • Method Details

    • setCallbacks

      ServiceDependency setCallbacks(String add, String remove)
      Sets the callbacks for this service. These callbacks can be used as hooks whenever a dependency is added or removed. When you specify callbacks, the auto configuration feature is automatically turned off, because we're assuming you don't need it in this case.
      Parameters:
      add - the method to call when a service was added
      remove - the method to call when a service was removed
      Returns:
      this service dependency

    • setCallbacks

      ServiceDependency setCallbacks(String add, String change, String remove)
      Sets the callbacks for this service. These callbacks can be used as hooks whenever a dependency is added, changed or removed. When you specify callbacks, the auto configuration feature is automatically turned off, because we're assuming you don't need it in this case.
      Parameters:
      add - the method to call when a service was added
      change - the method to call when a service was changed
      remove - the method to call when a service was removed
      Returns:
      this service dependency

    • setCallbacks

      ServiceDependency setCallbacks(String add, String change, String remove, String swap)
      Sets the callbacks for this service. These callbacks can be used as hooks whenever a dependency is added, changed or removed. When you specify callbacks, the auto configuration feature is automatically turned off, because we're assuming you don't need it in this case.
      Parameters:
      add - the method to call when a service was added
      change - the method to call when a service was changed
      remove - the method to call when a service was removed
      swap - the method to call when the service was swapped due to addition or removal of an aspect
      Returns:
      this service dependency

    • setCallbacks

      ServiceDependency setCallbacks(Object instance, String add, String remove)
      Sets the callbacks for this service. These callbacks can be used as hooks whenever a dependency is added or removed. They are called on the instance you provide. When you specify callbacks, the auto configuration feature is automatically turned off, because we're assuming you don't need it in this case.
      Parameters:
      instance - the instance to call the callbacks on
      add - the method to call when a service was added
      remove - the method to call when a service was removed
      Returns:
      this service dependency

    • setCallbacks

      ServiceDependency setCallbacks(Object instance, String add, String change, String remove)
      Sets the callbacks for this service. These callbacks can be used as hooks whenever a dependency is added, changed or removed. They are called on the instance you provide. When you specify callbacks, the auto configuration feature is automatically turned off, because we're assuming you don't need it in this case.
      Parameters:
      instance - the instance to call the callbacks on
      add - the method to call when a service was added
      change - the method to call when a service was changed
      remove - the method to call when a service was removed
      Returns:
      this service dependency

    • setCallbacks

      ServiceDependency setCallbacks(Object instance, String added, String changed, String removed, String swapped)
      Sets the callbacks for this service. These callbacks can be used as hooks whenever a dependency is added, changed or removed. When you specify callbacks, the auto configuration feature is automatically turned off, because we're assuming you don't need it in this case.
      Parameters:
      instance - the instance to call the callbacks on
      added - the method to call when a service was added
      changed - the method to call when a service was changed
      removed - the method to call when a service was removed
      swapped - the method to call when the service was swapped due to addition or removal of an aspect
      Returns:
      this service dependency

    • setRequired

      ServiceDependency setRequired(boolean required)
      Sets the required flag which determines if this service is required or not. A ServiceDependency is false by default.
      Parameters:
      required - the required flag
      Returns:
      this service dependency

    • setAutoConfig

      ServiceDependency setAutoConfig(boolean autoConfig)
      Sets auto configuration for this service. Auto configuration allows the dependency to fill in the attribute in the service implementation that has the same type and instance name. Dependency services will be injected in the following kind of fields:

      • a field having the same type as the dependency. If the field may be accessed by anythread, then the field should be declared volatile, in order to ensure visibility when the field is auto injected concurrently.
      • a field which is assignable to an Iterable<T> where T must match the dependency type. In this case, an Iterable will be injected by DependencyManager before the start callback is called. The Iterable field may then be traversed to inspect the currently available dependency services. The Iterable can possibly be set to a final value so you can choose the Iterable implementation of your choice (for example, a CopyOnWrite ArrayList, or a ConcurrentLinkedQueue).
      • a Map<K,V> where K must match the dependency type and V must exactly be equal to Dictionary. In this case, a ConcurrentHashMap will be injected by DependencyManager before the start callback is called. The Map may then be consulted to lookup current available dependency services, including the dependency service properties (the map key holds the dependency service, and the map value holds the dependency service properties). The Map field may be set to a final value so you can choose a Map of your choice (Typically a ConcurrentHashMap). A ConcurrentHashMap is "weakly consistent", meaning that when traversing the elements, you may or may not see any concurrent updates made on the map. So, take care to traverse the map using an iterator on the map entry set, which allows to atomically lookup pairs of Dependency service/Service properties.

      Here are some example using an Iterable: 

       
 public class SpellChecker {
    // can be traversed to inspect currently available dependencies
    final Iterable<DictionaryService> dictionaries = new ConcurrentLinkedQueueinvalid input: '<'>();
    
    Or
    
    // will be injected by DM automatically and can be traversed any time to inspect all currently available dependencies.
    volatile Iterable<DictionaryService> dictionaries = null;
 }
      Here are some example using a Map: 
       
 public class SpellChecker {
    // can be traversed to inspect currently available dependencies
    final Map<DictionaryService, Dictionary> dictionaries = new ConcurrentLinkedQueueinvalid input: '<'>();
    
    or
    
    // will be injected by DM automatically and can be traversed to inspect currently available dependencies
    volatile Map<DictionaryService, Dictionary> dictionaries = null;

    void iterateOnAvailableServices() {                 
       for (Map.Entryinvalid input: '<'MyService, Dictionary> entry : this.services.entrySet()) {
           MyService currentService = entry.getKey();
           Dictionary currentServiceProperties = entry.getValue();
           // ...
       }
    }
 }
      Parameters:
      autoConfig - the name of attribute to auto configure
      Returns:
      this service dependency

    • setAutoConfig

      ServiceDependency setAutoConfig(String instanceName)
      Sets auto configuration for this service. Auto configuration allows the dependency to fill in the attribute in the service implementation that has the same type and instance name.
      Parameters:
      instanceName - the name of attribute to auto config
      Returns:
      this service dependency
      See Also:

    • setService

      ServiceDependency setService(Class<?> serviceName)
      Sets the name of the service that should be tracked.
      Parameters:
      serviceName - the name of the service
      Returns:
      this service dependency

    • setService

      ServiceDependency setService(Class<?> serviceName, String serviceFilter)
      Sets the name of the service that should be tracked. You can either specify only the name, or the name and a filter. In the latter case, the filter is used to track the service and should only return services of the type that was specified in the name. To make sure of this, the filter is actually extended internally to filter on the correct name.
      Parameters:
      serviceName - the name of the service
      serviceFilter - the filter condition
      Returns:
      this service dependency

    • setService

      ServiceDependency setService(String serviceFilter)
      Sets the filter for the services that should be tracked. Any service object matching the filter will be returned, without any additional filter on the class.
      Parameters:
      serviceFilter - the filter condition
      Returns:
      this service dependency

    • setService

      ServiceDependency setService(Class<?> serviceName, org.osgi.framework.ServiceReference serviceReference)
      Sets the name of the service that should be tracked. You can either specify only the name, or the name and a reference. In the latter case, the service reference is used to track the service and should only return services of the type that was specified in the name.
      Parameters:
      serviceName - the name of the service
      serviceReference - the service reference to track
      Returns:
      this service dependency

    • setDefaultImplementation

      ServiceDependency setDefaultImplementation(Object implementation)
      Sets the default implementation for an optional service dependency. You can use this to supply your own implementation that will be used instead of a Null Object when the dependency is not available. This is also convenient if the service dependency is not an interface (which would cause the Null Object creation to fail) but a class. Only use this attribute on an optional service dependency injected on a class field.
      Parameters:
      implementation - the instance to use or the class to instantiate if you want to lazily instantiate this implementation
      Returns:
      this service dependency

    • setPropagate

      ServiceDependency setPropagate(boolean propagate)
      Sets propagation of the service dependency properties to the provided service properties. Any additional service properties specified directly are merged with these. The provided service properties take precedence over the propagated service dependency properties. It means a service dependency property won't override a component service property having the same name.
      Parameters:
      propagate - true if the dependency service properties should be propagated to the component service properties.

    • setPropagate

      ServiceDependency setPropagate(Object instance, String method)
      Sets an Object instance and a callback method used to propagate some properties to the provided service properties. The method will be invoked on the specified object instance and must have one of the following signatures:

      • Dictionary callback(ServiceReference, Object service)
      • Dictionary callback(ServiceReference)
      Parameters:
      instance - the Object instance which is used to retrieve propagated service properties
      method - the method to invoke for retrieving the properties to be propagated to the service properties.
      Returns:
      this service dependency.

    • setDebug

      ServiceDependency setDebug(String debugKey)
      Enabled debug logging for this dependency instance. The logging is prefixed with the given identifier.
      Parameters:
      debugKey - a prefix log identifier
      Returns:
      this service dependency.

    • setDereference

      ServiceDependency setDereference(boolean dereferenceServiceInternally)
      Configures whether or not this dependency should internally obtain the service object for all tracked service references. By default, DM internally dereferences all discovered service references (using BundleContext.getService(ServiceReference ref) methods. However, sometimes, your callback only needs the ServiceReference, and sometimes you don't want to dereference the service. So, in this case you can use the setDereference(false) method in order to tell to DM that it should never internally dereference the service dependency internally.
      Returns:
      false if the service must never be dereferenced by dependency manager (internally).