Package org.apache.felix.dm.context

Class AbstractDependency<T extends Dependency>

java.lang.Object
org.apache.felix.dm.context.AbstractDependency<T>
Type Parameters:
T - The type of the interface representing a Dependency Manager Dependency (must extends the Dependency interface).
All Implemented Interfaces:
ComponentDependencyDeclaration, DependencyContext, Dependency
public abstract class AbstractDependency<T extends Dependency> extends Object implements Dependency, DependencyContext, ComponentDependencyDeclaration
Abstract class for implementing Dependencies. You can extends this class in order to supply your own custom dependencies to any Dependency Manager Component.
Author:
Felix Project Team

  • Field Details

    • m_component

      protected ComponentContext m_component
      The Component implementation is exposed to Dependencies through this interface.

    • m_available

      protected volatile boolean m_available
      Is this Dependency available ? Volatile because the getState method (part of the ComponentDependencyDeclaration interface) may be called by any thread, at any time.

    • m_instanceBound

      protected boolean m_instanceBound
      Is this Dependency "instance bound" ? A dependency is "instance bound" if it is defined within the component's init method, meaning that it won't deactivate the component if it is not currently available when being added from the component's init method.

    • m_required

      protected volatile boolean m_required
      Is this dependency required (false by default) ?

    • m_add

      protected volatile String m_add
      Component callback used to inject an added dependency.

    • m_change

      protected volatile String m_change
      Component callback invoked when the dependency has changed.

    • m_remove

      protected volatile String m_remove
      Component callback invoked when the dependency becomes unavailable.

    • m_autoConfig

      protected volatile boolean m_autoConfig
      Can this Dependency be auto configured in the component instance fields ?

    • m_autoConfigInstance

      protected volatile String m_autoConfigInstance
      The Component field name where the Dependency can be injected (null means any field with a compatible type will be injected).

    • m_autoConfigInvoked

      protected volatile boolean m_autoConfigInvoked
      Indicates if the setAutoConfig method has been invoked. This flag is used to force autoconfig to "false" when the setCallbacks method is invoked, unless the setAutoConfig method has been called.

    • m_isStarted

      protected volatile boolean m_isStarted
      Has this Dependency been started by the Component implementation ? Volatile because the getState method (part of the ComponentDependencyDeclaration interface) may be called by any thread, at any time.

    • m_callbackInstance

      protected volatile Object m_callbackInstance
      The object instance on which the dependency callbacks are invoked on. Null means the dependency will be injected to the Component implementation instance(s).

    • m_propagate

      protected volatile boolean m_propagate
      Tells if the dependency service properties have to be propagated to the Component service properties.

    • m_propagateOverrides

      protected volatile boolean m_propagateOverrides
      Tells if the dependency service properties should override default component service properties (false by default).

    • m_propagateCallbackInstance

      protected volatile Object m_propagateCallbackInstance
      The propagate callback instance that is invoked in order to supply dynamically some dependency service properties.

    • m_propagateCallbackMethod

      protected volatile String m_propagateCallbackMethod
      The propagate callback method that is invoked in order to supply dynamically some dependency service properties.

    • EMPTY_PROPERTIES

      protected static final Dictionary<Object,Object> EMPTY_PROPERTIES
      Default empty dependency properties.

  • Constructor Details

    • AbstractDependency

      public AbstractDependency()
      Creates a new Dependency. By default, the dependency is optional and autoconfig.

    • AbstractDependency

      public AbstractDependency(AbstractDependency<T> prototype)
      Create a clone of a given Dependency.
      Parameters:
      prototype - all the fields of the prototype will be copied to this dependency.

  • Method Details

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • isRequired

      public boolean isRequired()
      Is this Dependency required (false by default) ?
      Specified by:
      isRequired in interface Dependency
      Returns:
      true if the dependency is required

    • isAvailable

      public boolean isAvailable()
      Is this Dependency satisfied and available ?
      Specified by:
      isAvailable in interface Dependency
      Returns:
      true if the dependency is available

    • isAutoConfig

      public boolean isAutoConfig()
      Can this dependency be injected in a component class field (by reflexion, true by default) ?
      Specified by:
      isAutoConfig in interface Dependency
      Returns:
      true if auto configuration is enabled for this dependency

    • getAutoConfigName

      public String getAutoConfigName()
      Returns the field name when the dependency can be injected to.
      Specified by:
      getAutoConfigName in interface Dependency
      Returns:
      the name of the member in the class of the component instance to inject into

    • isPropagated

      public boolean isPropagated()
      Returns the propagate callback method that is invoked in order to supply dynamically some dependency service properties.
      Specified by:
      isPropagated in interface Dependency
      Returns:
      true if the properties should be propagated
      See Also:

    • overrideServiceProperties

      public boolean overrideServiceProperties()
      Description copied from interface: Dependency
      Determines if the propagated dependency properties must override the component service properties. By default, propagated service properties don't override the component service properties. It means that a given dependency property does not override the same property in the component service properties.
      Specified by:
      overrideServiceProperties in interface Dependency
      Returns:
      true if the dependency service properties are propagated and override the component service properties.

    • getProperties

      public <K, V> Dictionary<K,V> getProperties()
      Returns the dependency service properties (empty by default).
      Specified by:
      getProperties in interface Dependency
      Returns:
      the properties
      See Also:

    • setComponentContext

      public void setComponentContext(ComponentContext component)
      Called by the Component implementation before the Dependency can be started.
      Specified by:
      setComponentContext in interface DependencyContext
      Parameters:
      component - the Component implementation context

    • invokeCallback

      public void invokeCallback(EventType type, Event... events)
      A Component callback must be invoked with dependency event(s).
      Specified by:
      invokeCallback in interface DependencyContext
      Parameters:
      type - the dependency event type
      events - the dependency service event to inject in the component. The number of events depends on the dependency event type: ADDED/CHANGED/REMOVED types only has one event parameter, but the SWAPPED type has two event parameters: the first one is the old event which must be replaced by the second one.
      See Also:

    • start

      public void start()
      Starts this dependency. Subclasses can override this method but must then call super.start().
      Specified by:
      start in interface DependencyContext

    • stop

      public void stop()
      Starts this dependency. Subclasses can override this method but must then call super.stop().
      Specified by:
      stop in interface DependencyContext

    • isStarted

      public boolean isStarted()
      Indicates if this dependency has been started by the Component implementation.
      Specified by:
      isStarted in interface DependencyContext
      Returns:
      true if the dependency has been started, false if not

    • setAvailable

      public void setAvailable(boolean available)
      Called by the Component implementation when the dependency is considered to be available.
      Specified by:
      setAvailable in interface DependencyContext
      Parameters:
      available - true to mark this dependency as available, false to mark it as unavailable

    • isInstanceBound

      public boolean isInstanceBound()
      Is this Dependency "instance bound" (has been defined within the component's init method) ?
      Specified by:
      isInstanceBound in interface DependencyContext
      Returns:
      true if this dependency is instance bound, false if not

    • setInstanceBound

      public void setInstanceBound(boolean instanceBound)
      Called by the Component implementation when the dependency is declared within the Component's init method.
      Specified by:
      setInstanceBound in interface DependencyContext

    • needsInstance

      public boolean needsInstance()
      Tells if the Component must be first instantiated before starting this dependency (false by default).
      Specified by:
      needsInstance in interface DependencyContext
      Returns:
      true if the dependency need the component instances before it can be started, false if not.

    • getAutoConfigType

      public abstract Class<?> getAutoConfigType()
      Returns the type of the field where this dependency can be injected (auto config), or return null if autoconfig is not supported.
      Specified by:
      getAutoConfigType in interface DependencyContext
      Returns:
      the type of the field which can be injected with the dependency service, or null if the dependency does not support auto config mode.

    • getService

      public Event getService()
      Get the highest ranked available dependency service, or null.
      Specified by:
      getService in interface DependencyContext
      Returns:
      the highest ranked available dependency service instance, or null

    • copyToCollection

      public void copyToCollection(Collection<Object> services)
      Copy all dependency service instances to the given collection.
      Specified by:
      copyToCollection in interface DependencyContext
      Parameters:
      services - the collection where the dependency service instances will be copied

    • copyToMap

      public void copyToMap(Map<Object,Dictionary<?,?>> map)
      Copy all dependency service instances to the given map (key = dependency service, value = dependency service properties.
      Specified by:
      copyToMap in interface DependencyContext
      Parameters:
      map - the map where the dependency service instances (with the corresponding service properties)

    • createCopy

      public abstract DependencyContext createCopy()
      Creates a copy of this Dependency.
      Specified by:
      createCopy in interface DependencyContext
      Returns:
      a clone of this dependency.

    • getName

      public String getName()
      Returns a description of this dependency (like the dependency service class name with associated filters)
      Specified by:
      getName in interface ComponentDependencyDeclaration

    • getSimpleName

      public abstract String getSimpleName()
      Returns a simple name for this dependency (like the dependency service class name).
      Specified by:
      getSimpleName in interface ComponentDependencyDeclaration

    • getType

      public abstract String getType()
      Returns the dependency symbolic type.
      Specified by:
      getType in interface ComponentDependencyDeclaration

    • getFilter

      public String getFilter()
      Returns the dependency filter, if any.
      Specified by:
      getFilter in interface ComponentDependencyDeclaration

    • getState

      public int getState()
      Returns this dependency state.
      Specified by:
      getState in interface ComponentDependencyDeclaration

    • setPropagate

      public T setPropagate(boolean propagate)
      Activates Dependency service properties propagation (to the service properties of the component to which this dependency is added).
      Parameters:
      propagate - true if the dependency service properties must be propagated to the service properties of the component to which this dependency is added.
      Returns:
      this dependency instance

    • setPropagate

      public T setPropagate(boolean propagate, boolean overrideServiceProperties)

    • setPropagate

      public T setPropagate(Object instance, String method)
      Sets a callback instance which can ba invoked with the given method in order to dynamically retrieve the dependency service properties.
      Parameters:
      instance - the callback instance
      method - the method to invoke on the callback instance
      Returns:
      this dependency instance

    • setCallbacks

      public T setCallbacks(String add, String remove)
      Sets the add/remove callbacks.
      Parameters:
      add - the callback to invoke when a dependency is added
      remove - the callback to invoke when a dependency is removed
      Returns:
      this dependency instance

    • setCallbacks

      public T setCallbacks(String add, String change, String remove)
      Sets the add/change/remove callbacks.
      Parameters:
      add - the callback to invoke when a dependency is added
      change - the callback to invoke when a dependency has changed
      remove - the callback to invoke when a dependency is removed
      Returns:
      this dependency instance

    • setCallbacks

      public T 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

      public T 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

    • getInstances

      public Object[] getInstances()
      Returns the dependency callback instances
      Returns:
      the dependency callback instances

    • setRequired

      public T setRequired(boolean required)

    • setAutoConfig

      public T setAutoConfig(boolean autoConfig)

    • setAutoConfig

      public T setAutoConfig(String instanceName)

    • getComponentContext

      public ComponentContext getComponentContext()
      Returns the component implementation context
      Specified by:
      getComponentContext in interface DependencyContext
      Returns:
      the component implementation context

    • getDefaultService

      protected Object getDefaultService(boolean nullObject)
      Returns the default service, or null.
      Parameters:
      nullObject - if true, a null object may be returned.
      Returns:
      the default service

    • ensureNotActive

      protected void ensureNotActive()
      Checks if the component dependency is not started.