001 /*
002 * Copyright (c) OSGi Alliance (2002, 2008). All Rights Reserved.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.osgi.service.wireadmin;
017
018 import org.osgi.framework.ServiceReference;
019
020 /**
021 * A Wire Admin Event.
022 *
023 * <p>
024 * <code>WireAdminEvent</code> objects are delivered to all registered
025 * <code>WireAdminListener</code> service objects which specify an interest in the
026 * <code>WireAdminEvent</code> type. Events must be delivered in chronological
027 * order with respect to each listener. For example, a <code>WireAdminEvent</code>
028 * of type {@link #WIRE_CONNECTED} must be delivered before a
029 * <code>WireAdminEvent</code> of type {@link #WIRE_DISCONNECTED} for a particular
030 * <code>Wire</code> object.
031 *
032 * <p>
033 * A type code is used to identify the type of event. The following event types
034 * are defined:
035 * <ul>
036 * <li>{@link #WIRE_CREATED}
037 * <li>{@link #WIRE_CONNECTED}
038 * <li>{@link #WIRE_UPDATED}
039 * <li>{@link #WIRE_TRACE}
040 * <li>{@link #WIRE_DISCONNECTED}
041 * <li>{@link #WIRE_DELETED}
042 * <li>{@link #PRODUCER_EXCEPTION}
043 * <li>{@link #CONSUMER_EXCEPTION}
044 * </ul>
045 * Additional event types may be defined in the future.
046 *
047 * <p>
048 * Event type values must be unique and disjoint bit values. Event types must be
049 * defined as a bit in a 32 bit integer and can thus be bitwise OR'ed together.
050 * <p>
051 * Security Considerations. <code>WireAdminEvent</code> objects contain
052 * <code>Wire</code> objects. Care must be taken in the sharing of <code>Wire</code>
053 * objects with other bundles.
054 *
055 * @see WireAdminListener
056 *
057 * @version $Revision: 5673 $
058 */
059 public class WireAdminEvent {
060 /**
061 * The WireAdmin service which created this event.
062 */
063 private ServiceReference reference;
064 /**
065 * The <code>Wire</code> object associated with this event.
066 */
067 private Wire wire;
068 /**
069 * Type of this event.
070 *
071 * @see #getType
072 */
073 private int type;
074 /**
075 * Exception associates with this the event.
076 */
077 private Throwable throwable;
078 /**
079 * A Producer service method has thrown an exception.
080 *
081 * <p>
082 * This <code>WireAdminEvent</code> type indicates that a Producer service
083 * method has thrown an exception. The {@link WireAdminEvent#getThrowable}
084 * method will return the exception that the Producer service method raised.
085 *
086 * <p>
087 * The value of <code>PRODUCER_EXCEPTION</code> is 0x00000001.
088 */
089 public final static int PRODUCER_EXCEPTION = 0x00000001;
090 /**
091 * A Consumer service method has thrown an exception.
092 *
093 * <p>
094 * This <code>WireAdminEvent</code> type indicates that a Consumer service
095 * method has thrown an exception. The {@link WireAdminEvent#getThrowable}
096 * method will return the exception that the Consumer service method raised.
097 *
098 * <p>
099 * The value of <code>CONSUMER_EXCEPTION</code> is 0x00000002.
100 */
101 public final static int CONSUMER_EXCEPTION = 0x00000002;
102 /**
103 * A <code>Wire</code> has been created.
104 *
105 * <p>
106 * This <code>WireAdminEvent</code> type that indicates that a new
107 * <code>Wire</code> object has been created.
108 *
109 * An event is broadcast when {@link WireAdmin#createWire} is called. The
110 * {@link WireAdminEvent#getWire} method will return the <code>Wire</code>
111 * object that has just been created.
112 *
113 * <p>
114 * The value of <code>WIRE_CREATED</code> is 0x00000004.
115 */
116 public final static int WIRE_CREATED = 0x00000004;
117 /**
118 * A <code>Wire</code> has been updated.
119 *
120 * <p>
121 * This <code>WireAdminEvent</code> type that indicates that an existing
122 * <code>Wire</code> object has been updated with new properties.
123 *
124 * An event is broadcast when {@link WireAdmin#updateWire} is called with a
125 * valid wire. The {@link WireAdminEvent#getWire} method will return the
126 * <code>Wire</code> object that has just been updated.
127 *
128 * <p>
129 * The value of <code>WIRE_UPDATED</code> is 0x00000008.
130 */
131 public final static int WIRE_UPDATED = 0x00000008;
132 /**
133 * A <code>Wire</code> has been deleted.
134 *
135 * <p>
136 * This <code>WireAdminEvent</code> type that indicates that an existing wire
137 * has been deleted.
138 *
139 * An event is broadcast when {@link WireAdmin#deleteWire} is called with a
140 * valid wire. {@link WireAdminEvent#getWire} will return the <code>Wire</code>
141 * object that has just been deleted.
142 *
143 * <p>
144 * The value of <code>WIRE_DELETED</code> is 0x00000010.
145 */
146 public final static int WIRE_DELETED = 0x00000010;
147 /**
148 * The <code>WireAdminEvent</code> type that indicates that an existing
149 * <code>Wire</code> object has become connected.
150 *
151 * The Consumer object and the Producer object that are associated with the
152 * <code>Wire</code> object have both been registered and the <code>Wire</code>
153 * object is connected. See {@link Wire#isConnected} for a description of
154 * the connected state. This event may come before the
155 * <code>producersConnected</code> and <code>consumersConnected</code> method
156 * have returned or called to allow synchronous delivery of the events. Both
157 * methods can cause other <code>WireAdminEvent</code> s to take place and
158 * requiring this event to be send before these methods are returned would
159 * mandate asynchronous delivery.
160 *
161 * <p>
162 * The value of <code>WIRE_CONNECTED</code> is 0x00000020.
163 */
164 public final static int WIRE_CONNECTED = 0x00000020;
165 /**
166 * The <code>WireAdminEvent</code> type that indicates that an existing
167 * <code>Wire</code> object has become disconnected.
168 *
169 * The Consumer object or/and Producer object is/are unregistered breaking
170 * the connection between the two. See {@link Wire#isConnected} for a
171 * description of the connected state.
172 *
173 * <p>
174 * The value of <code>WIRE_DISCONNECTED</code> is 0x00000040.
175 */
176 public final static int WIRE_DISCONNECTED = 0x00000040;
177 /**
178 * The <code>WireAdminEvent</code> type that indicates that a new value is
179 * transferred over the <code>Wire</code> object.
180 *
181 * This event is sent after the Consumer service has been notified by
182 * calling the {@link Consumer#updated} method or the Consumer service
183 * requested a new value with the {@link Wire#poll} method. This is an
184 * advisory event meaning that when this event is received, another update
185 * may already have occurred and this the {@link Wire#getLastValue} method
186 * returns a newer value then the value that was communicated for this
187 * event.
188 *
189 * <p>
190 * The value of <code>WIRE_TRACE</code> is 0x00000080.
191 */
192 public final static int WIRE_TRACE = 0x00000080;
193
194 /**
195 * Constructs a <code>WireAdminEvent</code> object from the given
196 * <code>ServiceReference</code> object, event type, <code>Wire</code> object
197 * and exception.
198 *
199 * @param reference The <code>ServiceReference</code> object of the Wire Admin
200 * service that created this event.
201 * @param type The event type. See {@link #getType}.
202 * @param wire The <code>Wire</code> object associated with this event.
203 * @param exception An exception associated with this event. This may be
204 * <code>null</code> if no exception is associated with this event.
205 */
206 public WireAdminEvent(ServiceReference reference, int type, Wire wire,
207 Throwable exception) {
208 this.reference = reference;
209 this.wire = wire;
210 this.type = type;
211 this.throwable = exception;
212 }
213
214 /**
215 * Return the <code>ServiceReference</code> object of the Wire Admin service
216 * that created this event.
217 *
218 * @return The <code>ServiceReference</code> object for the Wire Admin service
219 * that created this event.
220 */
221 public ServiceReference getServiceReference() {
222 return reference;
223 }
224
225 /**
226 * Return the <code>Wire</code> object associated with this event.
227 *
228 * @return The <code>Wire</code> object associated with this event or
229 * <code>null</code> when no <code>Wire</code> object is associated with
230 * the event.
231 */
232 public Wire getWire() {
233 return wire;
234 }
235
236 /**
237 * Return the type of this event.
238 * <p>
239 * The type values are:
240 * <ul>
241 * <li>{@link #WIRE_CREATED}
242 * <li>{@link #WIRE_CONNECTED}
243 * <li>{@link #WIRE_UPDATED}
244 * <li>{@link #WIRE_TRACE}
245 * <li>{@link #WIRE_DISCONNECTED}
246 * <li>{@link #WIRE_DELETED}
247 * <li>{@link #PRODUCER_EXCEPTION}
248 * <li>{@link #CONSUMER_EXCEPTION}
249 * </ul>
250 *
251 * @return The type of this event.
252 */
253 public int getType() {
254 return type;
255 }
256
257 /**
258 * Returns the exception associated with the event, if any.
259 *
260 * @return An exception or <code>null</code> if no exception is associated
261 * with this event.
262 */
263 public Throwable getThrowable() {
264 return throwable;
265 }
266 }