1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
|
/*
* Copyright (c) OSGi Alliance (2002, 2013). 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.
*
* <p>
* {@code WireAdminEvent} objects are delivered to all registered
* {@code WireAdminListener} service objects which specify an interest in the
* {@code WireAdminEvent} type. Events must be delivered in chronological order
* with respect to each listener. For example, a {@code WireAdminEvent} of type
* {@link #WIRE_CONNECTED} must be delivered before a {@code WireAdminEvent} of
* type {@link #WIRE_DISCONNECTED} for a particular {@code Wire} object.
*
* <p>
* A type code is used to identify the type of event. The following event types
* are defined:
* <ul>
* <li>{@link #WIRE_CREATED}</li>
* <li>{@link #WIRE_CONNECTED}</li>
* <li>{@link #WIRE_UPDATED}</li>
* <li>{@link #WIRE_TRACE}</li>
* <li>{@link #WIRE_DISCONNECTED}</li>
* <li>{@link #WIRE_DELETED}</li>
* <li>{@link #PRODUCER_EXCEPTION}</li>
* <li>{@link #CONSUMER_EXCEPTION}</li>
* </ul>
* Additional event types may be defined in the future.
*
* <p>
* 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.
* <p>
* Security Considerations. {@code WireAdminEvent} objects contain {@code Wire}
* objects. Care must be taken in the sharing of {@code Wire} objects with other
* bundles.
*
* @see WireAdminListener
* @Immutable
* @author $Id$
*/
public class WireAdminEvent {
/**
* The WireAdmin service which created this event.
*/
private final ServiceReference reference;
/**
* The {@code Wire} object associated with this event.
*/
private final Wire wire;
/**
* Type of this event.
*
* @see #getType()
*/
private final int type;
/**
* Exception associates with this the event.
*/
private final Throwable throwable;
/**
* A Producer service method has thrown an exception.
*
* <p>
* This {@code 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.
*
* <p>
* The value of {@code PRODUCER_EXCEPTION} is 0x00000001.
*/
public final static int PRODUCER_EXCEPTION = 0x00000001;
/**
* A Consumer service method has thrown an exception.
*
* <p>
* This {@code 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.
*
* <p>
* The value of {@code CONSUMER_EXCEPTION} is 0x00000002.
*/
public final static int CONSUMER_EXCEPTION = 0x00000002;
/**
* A {@code Wire} has been created.
*
* <p>
* This {@code WireAdminEvent} type that indicates that a new {@code Wire}
* object has been created.
*
* An event is broadcast when
* {@link WireAdmin#createWire(String, String, java.util.Dictionary)} is
* called. The {@link WireAdminEvent#getWire()} method will return the
* {@code Wire} object that has just been created.
*
* <p>
* The value of {@code WIRE_CREATED} is 0x00000004.
*/
public final static int WIRE_CREATED = 0x00000004;
/**
* A {@code Wire} has been updated.
*
* <p>
* This {@code WireAdminEvent} type that indicates that an existing
* {@code Wire} object has been updated with new properties.
*
* An event is broadcast when
* {@link WireAdmin#updateWire(Wire, java.util.Dictionary)} is called with a
* valid wire. The {@link WireAdminEvent#getWire()} method will return the
* {@code Wire} object that has just been updated.
*
* <p>
* The value of {@code WIRE_UPDATED} is 0x00000008.
*/
public final static int WIRE_UPDATED = 0x00000008;
/**
* A {@code Wire} has been deleted.
*
* <p>
* This {@code WireAdminEvent} type that indicates that an existing wire has
* been deleted.
*
* An event is broadcast when {@link WireAdmin#deleteWire(Wire)} is called
* with a valid wire. {@link WireAdminEvent#getWire()} will return the
* {@code Wire} object that has just been deleted.
*
* <p>
* The value of {@code WIRE_DELETED} is 0x00000010.
*/
public final static int WIRE_DELETED = 0x00000010;
/**
* The {@code WireAdminEvent} type that indicates that an existing
* {@code Wire} object has become connected.
*
* The Consumer object and the Producer object that are associated with the
* {@code Wire} object have both been registered and the {@code Wire} object
* is connected. See {@link Wire#isConnected()} for a description of the
* connected state. This event may come before the
* {@code producersConnected} and {@code consumersConnected} method have
* returned or called to allow synchronous delivery of the events. Both
* methods can cause other {@code WireAdminEvent} s to take place and
* requiring this event to be send before these methods are returned would
* mandate asynchronous delivery.
*
* <p>
* The value of {@code WIRE_CONNECTED} is 0x00000020.
*/
public final static int WIRE_CONNECTED = 0x00000020;
/**
* The {@code WireAdminEvent} type that indicates that an existing
* {@code 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.
*
* <p>
* The value of {@code WIRE_DISCONNECTED} is 0x00000040.
*/
public final static int WIRE_DISCONNECTED = 0x00000040;
/**
* The {@code WireAdminEvent} type that indicates that a new value is
* transferred over the {@code Wire} object.
*
* This event is sent after the Consumer service has been notified by
* calling the {@link Consumer#updated(Wire, Object)} 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.
*
* <p>
* The value of {@code WIRE_TRACE} is 0x00000080.
*/
public final static int WIRE_TRACE = 0x00000080;
/**
* Constructs a {@code WireAdminEvent} object from the given
* {@code ServiceReference} object, event type, {@code Wire} object and
* exception.
*
* @param reference The {@code ServiceReference} object of the Wire Admin
* service that created this event.
* @param type The event type. See {@link #getType()}.
* @param wire The {@code Wire} object associated with this event.
* @param exception An exception associated with this event. This may be
* {@code 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 {@code ServiceReference} object of the Wire Admin service that
* created this event.
*
* @return The {@code ServiceReference} object for the Wire Admin service
* that created this event.
*/
public ServiceReference getServiceReference() {
return reference;
}
/**
* Return the {@code Wire} object associated with this event.
*
* @return The {@code Wire} object associated with this event or
* {@code null} when no {@code Wire} object is associated with the
* event.
*/
public Wire getWire() {
return wire;
}
/**
* Return the type of this event.
* <p>
* The type values are:
* <ul>
* <li>{@link #WIRE_CREATED}</li>
* <li>{@link #WIRE_CONNECTED}</li>
* <li>{@link #WIRE_UPDATED}</li>
* <li>{@link #WIRE_TRACE}</li>
* <li>{@link #WIRE_DISCONNECTED}</li>
* <li>{@link #WIRE_DELETED}</li>
* <li>{@link #PRODUCER_EXCEPTION}</li>
* <li>{@link #CONSUMER_EXCEPTION}</li>
* </ul>
*
* @return The type of this event.
*/
public int getType() {
return type;
}
/**
* Returns the exception associated with the event, if any.
*
* @return An exception or {@code null} if no exception is associated with
* this event.
*/
public Throwable getThrowable() {
return throwable;
}
}
|
