OSGi™ Enterprise
Release 5

org.osgi.service.blueprint.container
Class BlueprintEvent

java.lang.Object
  extended by 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:

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
Immutable

Field Summary
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
BlueprintEvent(BlueprintEvent event, boolean replay)
          Create a new BlueprintEvent from the specified BlueprintEvent.
BlueprintEvent(int type, Bundle bundle, Bundle extenderBundle)
          Create a simple BlueprintEvent object.
BlueprintEvent(int type, Bundle bundle, Bundle extenderBundle, java.lang.String[] dependencies)
          Create a BlueprintEvent object associated with a set of dependencies.
BlueprintEvent(int type, Bundle bundle, 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, Bundle bundle, Bundle extenderBundle, java.lang.Throwable cause)
          Create a BlueprintEvent object associated with a failure cause.
 
Method Summary
 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.
 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,
                      Bundle bundle,
                      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,
                      Bundle bundle,
                      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,
                      Bundle bundle,
                      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,
                      Bundle bundle,
                      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:

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 Bundle getBundle()
Return the Blueprint bundle associated with this event.

Returns:
The Blueprint bundle associated with this event.

getExtenderBundle

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

OSGi™ Enterprise
Release 5

Copyright © OSGi Alliance (2000, 2012). All Rights Reserved. Licensed under the OSGi Specification License, Version 2.0