WireAdminEvent


1   /*
2    * $Header: /cvshome/build/org.osgi.service.wireadmin/src/org/osgi/service/wireadmin/WireAdminEvent.java,v 1.9 2006/07/11 00:54:10 hargrave Exp $
3    *
4    * Copyright (c) OSGi Alliance (2002, 2006). All Rights Reserved.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License");
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *      http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  package org.osgi.service.wireadmin;
19  
20  import org.osgi.framework.ServiceReference;
21  
22  /**
23   * A Wire Admin Event.
24   * 
25   * <p>
26   * <code>WireAdminEvent</code> objects are delivered to all registered
27   * <code>WireAdminListener</code> service objects which specify an interest in the
28   * <code>WireAdminEvent</code> type. Events must be delivered in chronological
29   * order with respect to each listener. For example, a <code>WireAdminEvent</code>
30   * of type {@link #WIRE_CONNECTED} must be delivered before a
31   * <code>WireAdminEvent</code> of type {@link #WIRE_DISCONNECTED} for a particular
32   * <code>Wire</code> object.
33   * 
34   * <p>
35   * A type code is used to identify the type of event. The following event types
36   * are defined:
37   * <ul>
38   * <li>{@link #WIRE_CREATED}
39   * <li>{@link #WIRE_CONNECTED}
40   * <li>{@link #WIRE_UPDATED}
41   * <li>{@link #WIRE_TRACE}
42   * <li>{@link #WIRE_DISCONNECTED}
43   * <li>{@link #WIRE_DELETED}
44   * <li>{@link #PRODUCER_EXCEPTION}
45   * <li>{@link #CONSUMER_EXCEPTION}
46   * </ul>
47   * Additional event types may be defined in the future.
48   * 
49   * <p>
50   * Event type values must be unique and disjoint bit values. Event types must be
51   * defined as a bit in a 32 bit integer and can thus be bitwise OR'ed together.
52   * <p>
53   * Security Considerations. <code>WireAdminEvent</code> objects contain
54   * <code>Wire</code> objects. Care must be taken in the sharing of <code>Wire</code>
55   * objects with other bundles.
56   * 
57   * @see WireAdminListener
58   * 
59   * @version $Revision: 1.9 $
60   */
61  public class WireAdminEvent {
62      /**
63       * The WireAdmin service which created this event.
64       */
65      private ServiceReference    reference;
66      /**
67       * The <code>Wire</code> object associated with this event.
68       */
69      private Wire                wire;
70      /**
71       * Type of this event.
72       * 
73       * @see #getType
74       */
75      private int                 type;
76      /**
77       * Exception associates with this the event.
78       */
79      private Throwable             throwable;
80      /**
81       * A Producer service method has thrown an exception.
82       * 
83       * <p>
84       * This <code>WireAdminEvent</code> type indicates that a Producer service
85       * method has thrown an exception. The {@link WireAdminEvent#getThrowable}
86       * method will return the exception that the Producer service method raised.
87       * 
88       * <p>
89       * The value of <code>PRODUCER_EXCEPTION</code> is 0x00000001.
90       */
91      public final static int     PRODUCER_EXCEPTION  = 0x00000001;
92      /**
93       * A Consumer service method has thrown an exception.
94       * 
95       * <p>
96       * This <code>WireAdminEvent</code> type indicates that a Consumer service
97       * method has thrown an exception. The {@link WireAdminEvent#getThrowable}
98       * method will return the exception that the Consumer service method raised.
99       * 
100      * <p>
101      * The value of <code>CONSUMER_EXCEPTION</code> is 0x00000002.
102      */
103     public final static int     CONSUMER_EXCEPTION  = 0x00000002;
104     /**
105      * A <code>Wire</code> has been created.
106      * 
107      * <p>
108      * This <code>WireAdminEvent</code> type that indicates that a new
109      * <code>Wire</code> object has been created.
110      * 
111      * An event is broadcast when {@link WireAdmin#createWire} is called. The
112      * {@link WireAdminEvent#getWire} method will return the <code>Wire</code>
113      * object that has just been created.
114      * 
115      * <p>
116      * The value of <code>WIRE_CREATED</code> is 0x00000004.
117      */
118     public final static int     WIRE_CREATED        = 0x00000004;
119     /**
120      * A <code>Wire</code> has been updated.
121      * 
122      * <p>
123      * This <code>WireAdminEvent</code> type that indicates that an existing
124      * <code>Wire</code> object has been updated with new properties.
125      * 
126      * An event is broadcast when {@link WireAdmin#updateWire} is called with a
127      * valid wire. The {@link WireAdminEvent#getWire} method will return the
128      * <code>Wire</code> object that has just been updated.
129      * 
130      * <p>
131      * The value of <code>WIRE_UPDATED</code> is 0x00000008.
132      */
133     public final static int     WIRE_UPDATED        = 0x00000008;
134     /**
135      * A <code>Wire</code> has been deleted.
136      * 
137      * <p>
138      * This <code>WireAdminEvent</code> type that indicates that an existing wire
139      * has been deleted.
140      * 
141      * An event is broadcast when {@link WireAdmin#deleteWire} is called with a
142      * valid wire. {@link WireAdminEvent#getWire} will return the <code>Wire</code>
143      * object that has just been deleted.
144      * 
145      * <p>
146      * The value of <code>WIRE_DELETED</code> is 0x00000010.
147      */
148     public final static int     WIRE_DELETED        = 0x00000010;
149     /**
150      * The <code>WireAdminEvent</code> type that indicates that an existing
151      * <code>Wire</code> object has become connected.
152      * 
153      * The Consumer object and the Producer object that are associated with the
154      * <code>Wire</code> object have both been registered and the <code>Wire</code>
155      * object is connected. See {@link Wire#isConnected} for a description of
156      * the connected state. This event may come before the
157      * <code>producersConnected</code> and <code>consumersConnected</code> method
158      * have returned or called to allow synchronous delivery of the events. Both
159      * methods can cause other <code>WireAdminEvent</code> s to take place and
160      * requiring this event to be send before these methods are returned would
161      * mandate asynchronous delivery.
162      * 
163      * <p>
164      * The value of <code>WIRE_CONNECTED</code> is 0x00000020.
165      */
166     public final static int     WIRE_CONNECTED      = 0x00000020;
167     /**
168      * The <code>WireAdminEvent</code> type that indicates that an existing
169      * <code>Wire</code> object has become disconnected.
170      * 
171      * The Consumer object or/and Producer object is/are unregistered breaking
172      * the connection between the two. See {@link Wire#isConnected} for a
173      * description of the connected state.
174      * 
175      * <p>
176      * The value of <code>WIRE_DISCONNECTED</code> is 0x00000040.
177      */
178     public final static int     WIRE_DISCONNECTED   = 0x00000040;
179     /**
180      * The <code>WireAdminEvent</code> type that indicates that a new value is
181      * transferred over the <code>Wire</code> object.
182      * 
183      * This event is sent after the Consumer service has been notified by
184      * calling the {@link Consumer#updated} method or the Consumer service
185      * requested a new value with the {@link Wire#poll} method. This is an
186      * advisory event meaning that when this event is received, another update
187      * may already have occurred and this the {@link Wire#getLastValue} method
188      * returns a newer value then the value that was communicated for this
189      * event.
190      * 
191      * <p>
192      * The value of <code>WIRE_TRACE</code> is 0x00000080.
193      */
194     public final static int     WIRE_TRACE          = 0x00000080;
195 
196     /**
197      * Constructs a <code>WireAdminEvent</code> object from the given
198      * <code>ServiceReference</code> object, event type, <code>Wire</code> object
199      * and exception.
200      * 
201      * @param reference The <code>ServiceReference</code> object of the Wire Admin
202      *        service that created this event.
203      * @param type The event type. See {@link #getType}.
204      * @param wire The <code>Wire</code> object associated with this event.
205      * @param exception An exception associated with this event. This may be
206      *        <code>null</code> if no exception is associated with this event.
207      */
208     public WireAdminEvent(ServiceReference reference, int type, Wire wire,
209             Throwable   exception) {
210         this.reference = reference;
211         this.wire = wire;
212         this.type = type;
213         this.throwable = exception;
214     }
215 
216     /**
217      * Return the <code>ServiceReference</code> object of the Wire Admin service
218      * that created this event.
219      * 
220      * @return The <code>ServiceReference</code> object for the Wire Admin service
221      *         that created this event.
222      */
223     public ServiceReference getServiceReference() {
224         return reference;
225     }
226 
227     /**
228      * Return the <code>Wire</code> object associated with this event.
229      * 
230      * @return The <code>Wire</code> object associated with this event or
231      *         <code>null</code> when no <code>Wire</code> object is associated with
232      *         the event.
233      */
234     public Wire getWire() {
235         return wire;
236     }
237 
238     /**
239      * Return the type of this event.
240      * <p>
241      * The type values are:
242      * <ul>
243      * <li>{@link #WIRE_CREATED}
244      * <li>{@link #WIRE_CONNECTED}
245      * <li>{@link #WIRE_UPDATED}
246      * <li>{@link #WIRE_TRACE}
247      * <li>{@link #WIRE_DISCONNECTED}
248      * <li>{@link #WIRE_DELETED}
249      * <li>{@link #PRODUCER_EXCEPTION}
250      * <li>{@link #CONSUMER_EXCEPTION}
251      * </ul>
252      * 
253      * @return The type of this event.
254      */
255     public int getType() {
256         return type;
257     }
258 
259     /**
260      * Returns the exception associated with the event, if any.
261      * 
262      * @return An exception or <code>null</code> if no exception is associated
263      *         with this event.
264      */
265     public Throwable   getThrowable() {
266         return throwable;
267     }
268 }
269
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags