BlueprintEvent
Date: 2016-06-25

org.osgi.service.blueprint.container

## Class BlueprintEvent

- java.lang.Object
- - org.osgi.service.blueprint.container.BlueprintEvent

-     public class BlueprintEvent
      extends java.lang.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:

  - `CREATING`
  - `CREATED`
  - `DESTROYING`
  - `DESTROYED`
  - `FAILURE`
  - `GRACE_PERIOD`
  - `WAITING`

  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:
    `BlueprintListener`, `EventConstants`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `CREATED` The Blueprint extender has created a Blueprint Container for the bundle.
    `static int` | `CREATING` The Blueprint extender has started creating a Blueprint Container for the bundle.
    `static int` | `DESTROYED` The Blueprint Container for the bundle has been completely destroyed.
    `static int` | `DESTROYING` The Blueprint extender has started destroying the Blueprint Container for the bundle.
    `static int` | `FAILURE` The Blueprint Container creation for the bundle has failed.
    `static int` | `GRACE_PERIOD` The Blueprint Container has entered the grace period.
    `static 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 and Description
    `BlueprintEvent(BlueprintEvent event, boolean replay)` Create a new `BlueprintEvent` from the specified `BlueprintEvent`.
    `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, java.lang.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, java.lang.String[] dependencies, java.lang.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, java.lang.Throwable cause)` Create a `BlueprintEvent` object associated with a failure cause.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `org.osgi.framework.Bundle` | `getBundle()` Return the Blueprint bundle associated with this event.
    `java.lang.Throwable` | `getCause()` Return the cause for this `FAILURE` event.
    `java.lang.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 Detail

    - #### CREATING

          public static final int CREATING

      The Blueprint extender has started creating a Blueprint Container for the bundle.
      See Also:
        Constant Field Values

    - #### 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:
        Constant Field Values

    - #### DESTROYING

          public static final int DESTROYING

      The Blueprint extender has started destroying the Blueprint Container for the bundle.
      See Also:
        Constant Field Values

    - #### 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:
        Constant Field Values

    - #### 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:
        Constant Field Values

    - #### 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:
        Constant Field Values

    - #### 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:
        Constant Field Values

  - ### Constructor Detail

    - #### 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,
                        java.lang.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,
                        java.lang.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,
                        java.lang.String[] dependencies,
                        java.lang.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 Detail

    - #### getType

          public int getType()

      Return the type of this event.

      The type values are:

      - `CREATING`
      - `CREATED`
      - `DESTROYING`
      - `DESTROYED`
      - `FAILURE`
      - `GRACE_PERIOD`
      - `WAITING`
      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 java.lang.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 java.lang.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.