org.apache.felix.dm

Interface ServiceDependency

All Superinterfaces:

ComponentDependencyDeclaration, Dependency

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)
 

Field Summary

Fields inherited from interface org.apache.felix.dm.ComponentDependencyDeclaration

STATE_AVAILABLE_OPTIONAL, STATE_AVAILABLE_REQUIRED, STATE_NAMES, STATE_OPTIONAL, STATE_REQUIRED, STATE_UNAVAILABLE_OPTIONAL, STATE_UNAVAILABLE_REQUIRED

Method Summary

Modifier and Type	Method and Description
ServiceDependency	setAutoConfig(boolean autoConfig) Sets auto configuration for this service.
ServiceDependency	setAutoConfig(java.lang.String instanceName) Sets auto configuration for this service.
ServiceDependency	setCallbacks(java.lang.Object instance, java.lang.String add, java.lang.String remove) Sets the callbacks for this service.
ServiceDependency	setCallbacks(java.lang.Object instance, java.lang.String add, java.lang.String change, java.lang.String remove) Sets the callbacks for this service.
ServiceDependency	setCallbacks(java.lang.Object instance, java.lang.String added, java.lang.String changed, java.lang.String removed, java.lang.String swapped) Sets the callbacks for this service.
ServiceDependency	setCallbacks(java.lang.String add, java.lang.String remove) Sets the callbacks for this service.
ServiceDependency	setCallbacks(java.lang.String add, java.lang.String change, java.lang.String remove) Sets the callbacks for this service.
ServiceDependency	setCallbacks(java.lang.String add, java.lang.String change, java.lang.String remove, java.lang.String swap) Sets the callbacks for this service.
ServiceDependency	setDebug(java.lang.String debugKey) Enabled debug logging for this dependency instance.
ServiceDependency	setDefaultImplementation(java.lang.Object implementation) Sets the default implementation for an optional service dependency.
ServiceDependency	setDereference(boolean dereferenceServiceInternally) Configures whether or not this dependency should internally obtain the service object for all tracked service references.
ServiceDependency	setPropagate(boolean propagate) Sets propagation of the service dependency properties to the provided service properties.
ServiceDependency	setPropagate(java.lang.Object instance, java.lang.String method) Sets an Object instance and a callback method used to propagate some properties to the provided service properties.
ServiceDependency	setRequired(boolean required) Sets the required flag which determines if this service is required or not.
ServiceDependency	setService(java.lang.Class<?> serviceName) Sets the name of the service that should be tracked.
ServiceDependency	setService(java.lang.Class<?> serviceName, ServiceReference serviceReference) Sets the name of the service that should be tracked.
ServiceDependency	setService(java.lang.Class<?> serviceName, java.lang.String serviceFilter) Sets the name of the service that should be tracked.
ServiceDependency	setService(java.lang.String serviceFilter) Sets the filter for the services that should be tracked.

Methods inherited from interface org.apache.felix.dm.Dependency

getAutoConfigName, getProperties, isAutoConfig, isAvailable, isPropagated, isRequired, overrideServiceProperties

Methods inherited from interface org.apache.felix.dm.ComponentDependencyDeclaration

getFilter, getName, getSimpleName, getState, getType

Method Detail

setCallbacks

ServiceDependency setCallbacks(java.lang.String add,
                               java.lang.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(java.lang.String add,
                               java.lang.String change,
                               java.lang.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(java.lang.String add,
                               java.lang.String change,
                               java.lang.String remove,
                               java.lang.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(java.lang.Object instance,
                               java.lang.String add,
                               java.lang.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(java.lang.Object instance,
                               java.lang.String add,
                               java.lang.String change,
                               java.lang.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(java.lang.Object instance,
                               java.lang.String added,
                               java.lang.String changed,
                               java.lang.String removed,
                               java.lang.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 ConcurrentLinkedQueue<>();
    
    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 ConcurrentLinkedQueue<>();
    
    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.Entry 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(java.lang.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:

setAutoConfig(boolean)

setService

ServiceDependency setService(java.lang.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(java.lang.Class<?> serviceName,
                             java.lang.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(java.lang.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(java.lang.Class<?> serviceName,
                             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(java.lang.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(java.lang.Object instance,
                               java.lang.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(java.lang.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).