org.osgi.service.wireadmin.WireAdminEvent Maven / Gradle / Ivy
/*
* Copyright (c) OSGi Alliance (2002, 2008). All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.osgi.service.wireadmin;
import org.osgi.framework.ServiceReference;
/**
* 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 {@link #WIRE_CONNECTED} must be delivered before a
* WireAdminEvent of type {@link #WIRE_DISCONNECTED} for a particular
* Wire object.
*
*
* A type code is used to identify the type of event. The following event types
* are defined:
*
* - {@link #WIRE_CREATED}
*
- {@link #WIRE_CONNECTED}
*
- {@link #WIRE_UPDATED}
*
- {@link #WIRE_TRACE}
*
- {@link #WIRE_DISCONNECTED}
*
- {@link #WIRE_DELETED}
*
- {@link #PRODUCER_EXCEPTION}
*
- {@link #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 WireAdminListener
*
* @version $Revision: 5673 $
*/
public class WireAdminEvent {
/**
* The WireAdmin service which created this event.
*/
private ServiceReference reference;
/**
* The Wire object associated with this event.
*/
private Wire wire;
/**
* Type of this event.
*
* @see #getType
*/
private int type;
/**
* Exception associates with this the event.
*/
private Throwable throwable;
/**
* A Producer service method has thrown an exception.
*
*
* This WireAdminEvent type indicates that a Producer service
* method has thrown an exception. The {@link WireAdminEvent#getThrowable}
* method will return the exception that the Producer service method raised.
*
*
* The value of PRODUCER_EXCEPTION is 0x00000001.
*/
public final static int PRODUCER_EXCEPTION = 0x00000001;
/**
* A Consumer service method has thrown an exception.
*
*
* This WireAdminEvent type indicates that a Consumer service
* method has thrown an exception. The {@link WireAdminEvent#getThrowable}
* method will return the exception that the Consumer service method raised.
*
*
* The value of CONSUMER_EXCEPTION is 0x00000002.
*/
public final static int CONSUMER_EXCEPTION = 0x00000002;
/**
* A Wire has been created.
*
*
* This WireAdminEvent type that indicates that a new
* Wire object has been created.
*
* An event is broadcast when {@link WireAdmin#createWire} is called. The
* {@link WireAdminEvent#getWire} method will return the Wire
* object that has just been created.
*
*
* The value of WIRE_CREATED is 0x00000004.
*/
public final static int WIRE_CREATED = 0x00000004;
/**
* 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 {@link WireAdmin#updateWire} is called with a
* valid wire. The {@link WireAdminEvent#getWire} method will return the
* Wire object that has just been updated.
*
*
* The value of WIRE_UPDATED is 0x00000008.
*/
public final static int WIRE_UPDATED = 0x00000008;
/**
* A Wire has been deleted.
*
*
* This WireAdminEvent type that indicates that an existing wire
* has been deleted.
*
* An event is broadcast when {@link WireAdmin#deleteWire} is called with a
* valid wire. {@link WireAdminEvent#getWire} will return the Wire
* object that has just been deleted.
*
*
* The value of WIRE_DELETED is 0x00000010.
*/
public final static int WIRE_DELETED = 0x00000010;
/**
* 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 {@link 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.
*/
public final static int WIRE_CONNECTED = 0x00000020;
/**
* 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 {@link Wire#isConnected} for a
* description of the connected state.
*
*
* The value of WIRE_DISCONNECTED is 0x00000040.
*/
public final static int WIRE_DISCONNECTED = 0x00000040;
/**
* 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 {@link Consumer#updated} method or the Consumer service
* requested a new value with the {@link Wire#poll} method. This is an
* advisory event meaning that when this event is received, another update
* may already have occurred and this the {@link Wire#getLastValue} method
* returns a newer value then the value that was communicated for this
* event.
*
*
* The value of WIRE_TRACE is 0x00000080.
*/
public final static int WIRE_TRACE = 0x00000080;
/**
* Constructs a WireAdminEvent object from the given
* ServiceReference object, event type, Wire object
* and exception.
*
* @param reference The ServiceReference object of the Wire Admin
* service that created this event.
* @param type The event type. See {@link #getType}.
* @param wire The Wire object associated with this event.
* @param exception An exception associated with this event. This may be
* null if no exception is associated with this event.
*/
public WireAdminEvent(ServiceReference reference, int type, Wire wire,
Throwable exception) {
this.reference = reference;
this.wire = wire;
this.type = type;
this.throwable = exception;
}
/**
* Return the ServiceReference object of the Wire Admin service
* that created this event.
*
* @return The ServiceReference object for the Wire Admin service
* that created this event.
*/
public ServiceReference getServiceReference() {
return reference;
}
/**
* Return the Wire object associated with this event.
*
* @return The Wire object associated with this event or
* null when no Wire object is associated with
* the event.
*/
public Wire getWire() {
return wire;
}
/**
* Return the type of this event.
*
* The type values are:
*
* - {@link #WIRE_CREATED}
*
- {@link #WIRE_CONNECTED}
*
- {@link #WIRE_UPDATED}
*
- {@link #WIRE_TRACE}
*
- {@link #WIRE_DISCONNECTED}
*
- {@link #WIRE_DELETED}
*
- {@link #PRODUCER_EXCEPTION}
*
- {@link #CONSUMER_EXCEPTION}
*
*
* @return The type of this event.
*/
public int getType() {
return type;
}
/**
* Returns the exception associated with the event, if any.
*
* @return An exception or null if no exception is associated
* with this event.
*/
public Throwable getThrowable() {
return throwable;
}
}