WireAdminEvent
Date: 2016-06-25

org.osgi.service.wireadmin

## Class WireAdminEvent

- java.lang.Object
- - org.osgi.service.wireadmin.WireAdminEvent

-     public class WireAdminEvent
      extends java.lang.Object

  A Wire Admin Event.

  `WireAdminEvent` objects are delivered to all registered `WireAdminListener` service objects which specify an interest in the `WireAdminEvent` type. Events must be delivered in chronological order with respect to each listener. For example, a `WireAdminEvent` of type `WIRE_CONNECTED` must be delivered before a `WireAdminEvent` of type `WIRE_DISCONNECTED` for a particular `Wire` object.

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

  - `WIRE_CREATED`
  - `WIRE_CONNECTED`
  - `WIRE_UPDATED`
  - `WIRE_TRACE`
  - `WIRE_DISCONNECTED`
  - `WIRE_DELETED`
  - `PRODUCER_EXCEPTION`
  - `CONSUMER_EXCEPTION`
  Additional event types may be defined in the future.

  Event type values must be unique and disjoint bit values. Event types must be defined as a bit in a 32 bit integer and can thus be bitwise OR'ed together.

  Security Considerations. `WireAdminEvent` objects contain `Wire` objects. Care must be taken in the sharing of `Wire` objects with other bundles.

  See Also:
    `WireAdminListener`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `CONSUMER_EXCEPTION` A Consumer service method has thrown an exception.
    `static int` | `PRODUCER_EXCEPTION` A Producer service method has thrown an exception.
    `static int` | `WIRE_CONNECTED` The `WireAdminEvent` type that indicates that an existing `Wire` object has become connected.
    `static int` | `WIRE_CREATED` A `Wire` has been created.
    `static int` | `WIRE_DELETED` A `Wire` has been deleted.
    `static int` | `WIRE_DISCONNECTED` The `WireAdminEvent` type that indicates that an existing `Wire` object has become disconnected.
    `static int` | `WIRE_TRACE` The `WireAdminEvent` type that indicates that a new value is transferred over the `Wire` object.
    `static int` | `WIRE_UPDATED` A `Wire` has been updated.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `WireAdminEvent(org.osgi.framework.ServiceReference reference, int type, Wire wire, java.lang.Throwable exception)` Constructs a `WireAdminEvent` object from the given `ServiceReference` object, event type, `Wire` object and exception.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `org.osgi.framework.ServiceReference` | `getServiceReference()` Return the `ServiceReference` object of the Wire Admin service that created this event.
    `java.lang.Throwable` | `getThrowable()` Returns the exception associated with the event, if any.
    `int` | `getType()` Return the type of this event.
    `Wire` | `getWire()` Return the `Wire` object associated with this event.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### PRODUCER_EXCEPTION

          public static final int PRODUCER_EXCEPTION

      A Producer service method has thrown an exception.

      This `WireAdminEvent` type indicates that a Producer service method has thrown an exception. The `getThrowable()` method will return the exception that the Producer service method raised.

      The value of `PRODUCER_EXCEPTION` is 0x00000001.

      See Also:
        Constant Field Values

    - #### CONSUMER_EXCEPTION

          public static final int CONSUMER_EXCEPTION

      A Consumer service method has thrown an exception.

      This `WireAdminEvent` type indicates that a Consumer service method has thrown an exception. The `getThrowable()` method will return the exception that the Consumer service method raised.

      The value of `CONSUMER_EXCEPTION` is 0x00000002.

      See Also:
        Constant Field Values

    - #### WIRE_CREATED

          public static final int WIRE_CREATED

      A `Wire` has been created.

      This `WireAdminEvent` type that indicates that a new `Wire` object has been created. An event is broadcast when `WireAdmin.createWire(String, String, java.util.Dictionary)` is called. The `getWire()` method will return the `Wire` object that has just been created.

      The value of `WIRE_CREATED` is 0x00000004.

      See Also:
        Constant Field Values

    - #### WIRE_UPDATED

          public static final int WIRE_UPDATED

      A `Wire` has been updated.

      This `WireAdminEvent` type that indicates that an existing `Wire` object has been updated with new properties. An event is broadcast when `WireAdmin.updateWire(Wire, java.util.Dictionary)` is called with a valid wire. The `getWire()` method will return the `Wire` object that has just been updated.

      The value of `WIRE_UPDATED` is 0x00000008.

      See Also:
        Constant Field Values

    - #### WIRE_DELETED

          public static final int WIRE_DELETED

      A `Wire` has been deleted.

      This `WireAdminEvent` type that indicates that an existing wire has been deleted. An event is broadcast when `WireAdmin.deleteWire(Wire)` is called with a valid wire. `getWire()` will return the `Wire` object that has just been deleted.

      The value of `WIRE_DELETED` is 0x00000010.

      See Also:
        Constant Field Values

    - #### WIRE_CONNECTED

          public static final int WIRE_CONNECTED

      The `WireAdminEvent` type that indicates that an existing `Wire` object has become connected. The Consumer object and the Producer object that are associated with the `Wire` object have both been registered and the `Wire` object is connected. See `Wire.isConnected()` for a description of the connected state. This event may come before the `producersConnected` and `consumersConnected` method have returned or called to allow synchronous delivery of the events. Both methods can cause other `WireAdminEvent` s to take place and requiring this event to be send before these methods are returned would mandate asynchronous delivery.

      The value of `WIRE_CONNECTED` is 0x00000020.

      See Also:
        Constant Field Values

    - #### WIRE_DISCONNECTED

          public static final int WIRE_DISCONNECTED

      The `WireAdminEvent` type that indicates that an existing `Wire` object has become disconnected. The Consumer object or/and Producer object is/are unregistered breaking the connection between the two. See `Wire.isConnected()` for a description of the connected state.

      The value of `WIRE_DISCONNECTED` is 0x00000040.

      See Also:
        Constant Field Values

    - #### WIRE_TRACE

          public static final int WIRE_TRACE

      The `WireAdminEvent` type that indicates that a new value is transferred over the `Wire` object. This event is sent after the Consumer service has been notified by calling the `Consumer.updated(Wire, Object)` method or the Consumer service requested a new value with the `Wire.poll()` method. This is an advisory event meaning that when this event is received, another update may already have occurred and this the `Wire.getLastValue()` method returns a newer value then the value that was communicated for this event.

      The value of `WIRE_TRACE` is 0x00000080.

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### WireAdminEvent

          public WireAdminEvent(org.osgi.framework.ServiceReference reference,
                        int type,
                        Wire wire,
                        java.lang.Throwable exception)

      Constructs a `WireAdminEvent` object from the given `ServiceReference` object, event type, `Wire` object and exception.
      Parameters:
        `reference` - The `ServiceReference` object of the Wire Admin service that created this event.
        `type` - The event type. See `getType()`.
        `wire` - The `Wire` object associated with this event.
        `exception` - An exception associated with this event. This may be `null` if no exception is associated with this event.

  - ### Method Detail

    - #### getServiceReference

          public org.osgi.framework.ServiceReference getServiceReference()

      Return the `ServiceReference` object of the Wire Admin service that created this event.
      Returns:
        The `ServiceReference` object for the Wire Admin service that created this event.

    - #### getWire

          public Wire getWire()

      Return the `Wire` object associated with this event.
      Returns:
        The `Wire` object associated with this event or `null` when no `Wire` object is associated with the event.

    - #### getType

          public int getType()

      Return the type of this event.

      The type values are:

      - `WIRE_CREATED`
      - `WIRE_CONNECTED`
      - `WIRE_UPDATED`
      - `WIRE_TRACE`
      - `WIRE_DISCONNECTED`
      - `WIRE_DELETED`
      - `PRODUCER_EXCEPTION`
      - `CONSUMER_EXCEPTION`
      Returns:
        The type of this event.

    - #### getThrowable

          public java.lang.Throwable getThrowable()

      Returns the exception associated with the event, if any.
      Returns:
        An exception or `null` if no exception is associated with this event.