Package org.osgi.service.blueprint.container

Class BlueprintEvent

java.lang.Object
org.osgi.service.blueprint.container.BlueprintEvent
public class BlueprintEvent extends Object
A Blueprint Event.

BlueprintEvent objects are delivered to all registered BlueprintListener services. Blueprint Events must be asynchronously delivered in chronological order with respect to each listener.

In addition, after a Blueprint Listener is registered, the Blueprint extender will synchronously send to this Blueprint Listener the last Blueprint Event for each ready Blueprint bundle managed by this extender. This replay of Blueprint Events is designed so that the new Blueprint Listener can be informed of the state of each Blueprint bundle. Blueprint Events sent during this replay will have the isReplay() flag set. The Blueprint extender must ensure that this replay phase does not interfere with new Blueprint Events so that the chronological order of all Blueprint Events received by the Blueprint Listener is preserved. If the last Blueprint Event for a given Blueprint bundle is DESTROYED, the extender must not send it during this replay phase.

A type code is used to identify the type of event. The following event types are defined:

In addition to calling the registered BlueprintListener services, the Blueprint extender must also send those events to the Event Admin service, if it is available.

See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private final org.osgi.framework.Bundle
    bundle
    The Blueprint bundle.
    private final Throwable
    cause
    Cause of the failure.
    static final int
    CREATED
    The Blueprint extender has created a Blueprint Container for the bundle.
    static final int
    CREATING
    The Blueprint extender has started creating a Blueprint Container for the bundle.
    private final String[]
    dependencies
    An array containing filters identifying the missing dependencies.
    static final int
    DESTROYED
    The Blueprint Container for the bundle has been completely destroyed.
    static final int
    DESTROYING
    The Blueprint extender has started destroying the Blueprint Container for the bundle.
    private final org.osgi.framework.Bundle
    extenderBundle
    The Blueprint extender bundle.
    static final int
    FAILURE
    The Blueprint Container creation for the bundle has failed.
    static final int
    GRACE_PERIOD
    The Blueprint Container has entered the grace period.
    private final boolean
    replay
    Indicate if this event is a replay event or not.
    private final long
    timestamp
    The time when the event occurred.
    private final int
    type
    Type of this event.
    static final int
    WAITING
    The Blueprint Container is waiting on the availability of a service to satisfy an invocation on a referenced service.

  • Constructor Summary

    Constructors
    Constructor
    Description
    BlueprintEvent(int type, org.osgi.framework.Bundle bundle, org.osgi.framework.Bundle extenderBundle)
    Create a simple BlueprintEvent object.
    BlueprintEvent(int type, org.osgi.framework.Bundle bundle, org.osgi.framework.Bundle extenderBundle, String[] dependencies)
    Create a BlueprintEvent object associated with a set of dependencies.
    BlueprintEvent(int type, org.osgi.framework.Bundle bundle, org.osgi.framework.Bundle extenderBundle, String[] dependencies, Throwable cause)
    Create a BlueprintEvent object associated with a failure cause and a set of dependencies.
    BlueprintEvent(int type, org.osgi.framework.Bundle bundle, org.osgi.framework.Bundle extenderBundle, Throwable cause)
    Create a BlueprintEvent object associated with a failure cause.
    BlueprintEvent(BlueprintEvent event, boolean replay)
    Create a new BlueprintEvent from the specified BlueprintEvent.

  • Method Summary

    Modifier and Type
    Method
    Description
    org.osgi.framework.Bundle
    getBundle()
    Return the Blueprint bundle associated with this event.
    Throwable
    getCause()
    Return the cause for this FAILURE event.
    String[]
    getDependencies()
    Return the filters identifying the missing dependencies that caused this event.
    org.osgi.framework.Bundle
    getExtenderBundle()
    Return the Blueprint extender bundle that is generating this event.
    long
    getTimestamp()
    Return the time at which this event was created.
    int
    getType()
    Return the type of this event.
    boolean
    isReplay()
    Return whether this event is a replay event.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • CREATING

      public static final int CREATING
      The Blueprint extender has started creating a Blueprint Container for the bundle.
      See Also:

    • CREATED

      public static final int CREATED
      The Blueprint extender has created a Blueprint Container for the bundle. This event is sent after the Blueprint Container has been registered as a service.
      See Also:

    • DESTROYING

      public static final int DESTROYING
      The Blueprint extender has started destroying the Blueprint Container for the bundle.
      See Also:

    • DESTROYED

      public static final int DESTROYED
      The Blueprint Container for the bundle has been completely destroyed. This event is sent after the Blueprint Container has been unregistered as a service.
      See Also:

    • FAILURE

      public static final int FAILURE
      The Blueprint Container creation for the bundle has failed. If this event is sent after a timeout in the Grace Period, the getDependencies() method must return an array of missing mandatory dependencies. The event must also contain the cause of the failure as a Throwable through the getCause() method.
      See Also:

    • GRACE_PERIOD

      public static final int GRACE_PERIOD
      The Blueprint Container has entered the grace period. The list of missing dependencies must be made available through the getDependencies() method. During the grace period, a GRACE_PERIOD event is sent each time the set of unsatisfied dependencies changes.
      See Also:

    • WAITING

      public static final int WAITING
      The Blueprint Container is waiting on the availability of a service to satisfy an invocation on a referenced service. The missing dependency must be made available through the getDependencies() method which will return an array containing one filter object as a String.
      See Also:

    • type

      private final int type
      Type of this event.
      See Also:

    • timestamp

      private final long timestamp
      The time when the event occurred.
      See Also:

    • bundle

      private final org.osgi.framework.Bundle bundle
      The Blueprint bundle.
      See Also:

    • extenderBundle

      private final org.osgi.framework.Bundle extenderBundle
      The Blueprint extender bundle.
      See Also:

    • dependencies

      private final String[] dependencies
      An array containing filters identifying the missing dependencies. Must not be null when the event type requires it.
      See Also:

    • cause

      private final Throwable cause
      Cause of the failure.
      See Also:

    • replay

      private final boolean replay
      Indicate if this event is a replay event or not.
      See Also:

  • Constructor Details

    • BlueprintEvent

      public BlueprintEvent(int type, org.osgi.framework.Bundle bundle, org.osgi.framework.Bundle extenderBundle)
      Create a simple BlueprintEvent object.
      Parameters:
      type - The type of this event.
      bundle - The Blueprint bundle associated with this event. This parameter must not be null.
      extenderBundle - The Blueprint extender bundle that is generating this event. This parameter must not be null.

    • BlueprintEvent

      public BlueprintEvent(int type, org.osgi.framework.Bundle bundle, org.osgi.framework.Bundle extenderBundle, String[] dependencies)
      Create a BlueprintEvent object associated with a set of dependencies.
      Parameters:
      type - The type of this event.
      bundle - The Blueprint bundle associated with this event. This parameter must not be null.
      extenderBundle - The Blueprint extender bundle that is generating this event. This parameter must not be null.
      dependencies - An array of String filters for each dependency associated with this event. Must be a non-empty array for event types GRACE_PERIOD and WAITING. It is optional for event type FAILURE. Must be null for other event types.

    • BlueprintEvent

      public BlueprintEvent(int type, org.osgi.framework.Bundle bundle, org.osgi.framework.Bundle extenderBundle, Throwable cause)
      Create a BlueprintEvent object associated with a failure cause.
      Parameters:
      type - The type of this event.
      bundle - The Blueprint bundle associated with this event. This parameter must not be null.
      extenderBundle - The Blueprint extender bundle that is generating this event. This parameter must not be null.
      cause - A Throwable object describing the root cause of the event. May be null.

    • BlueprintEvent

      public BlueprintEvent(int type, org.osgi.framework.Bundle bundle, org.osgi.framework.Bundle extenderBundle, String[] dependencies, Throwable cause)
      Create a BlueprintEvent object associated with a failure cause and a set of dependencies.
      Parameters:
      type - The type of this event.
      bundle - The Blueprint bundle associated with this event. This parameter must not be null.
      extenderBundle - The Blueprint extender bundle that is generating this event. This parameter must not be null.
      dependencies - An array of String filters for each dependency associated with this event. Must be a non-empty array for event types GRACE_PERIOD and WAITING. It is optional for event type FAILURE. Must be null for other event types.
      cause - A Throwable object describing the root cause of this event. May be null.

    • BlueprintEvent

      public BlueprintEvent(BlueprintEvent event, boolean replay)
      Create a new BlueprintEvent from the specified BlueprintEvent. The timestamp property will be copied from the original event and only the replay property will be overridden with the given value.
      Parameters:
      event - The original BlueprintEvent to copy. Must not be null.
      replay - true if this event should be used as a replay event.

  • Method Details

    • getType

      public int getType()
      Return the type of this event.

      The type values are:

      Returns:
      The type of this event.

    • getTimestamp

      public long getTimestamp()
      Return the time at which this event was created.
      Returns:
      The time at which this event was created.

    • getBundle

      public org.osgi.framework.Bundle getBundle()
      Return the Blueprint bundle associated with this event.
      Returns:
      The Blueprint bundle associated with this event.

    • getExtenderBundle

      public org.osgi.framework.Bundle getExtenderBundle()
      Return the Blueprint extender bundle that is generating this event.
      Returns:
      The Blueprint extender bundle that is generating this event.

    • getDependencies

      public String[] getDependencies()
      Return the filters identifying the missing dependencies that caused this event.
      Returns:
      The filters identifying the missing dependencies that caused this event if the event type is one of WAITING, GRACE_PERIOD or FAILURE or null for the other event types.

    • getCause

      public Throwable getCause()
      Return the cause for this FAILURE event.
      Returns:
      The cause of the failure for this event. May be null .

    • isReplay

      public boolean isReplay()
      Return whether this event is a replay event.
      Returns:
      true if this event is a replay event and false otherwise.