001 /* Notification.java -- A notification emitted by a bean.
002 Copyright (C) 2006 Free Software Foundation, Inc.
003
004 This file is part of GNU Classpath.
005
006 GNU Classpath is free software; you can redistribute it and/or modify
007 it under the terms of the GNU General Public License as published by
008 the Free Software Foundation; either version 2, or (at your option)
009 any later version.
010
011 GNU Classpath is distributed in the hope that it will be useful, but
012 WITHOUT ANY WARRANTY; without even the implied warranty of
013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014 General Public License for more details.
015
016 You should have received a copy of the GNU General Public License
017 along with GNU Classpath; see the file COPYING. If not, write to the
018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019 02110-1301 USA.
020
021 Linking this library statically or dynamically with other modules is
022 making a combined work based on this library. Thus, the terms and
023 conditions of the GNU General Public License cover the whole
024 combination.
025
026 As a special exception, the copyright holders of this library give you
027 permission to link this library with independent modules to produce an
028 executable, regardless of the license terms of these independent
029 modules, and to copy and distribute the resulting executable under
030 terms of your choice, provided that you also meet, for each linked
031 independent module, the terms and conditions of the license of that
032 module. An independent module is a module which is not derived from
033 or based on this library. If you modify this library, you may extend
034 this exception to your version of the library, but you are not
035 obligated to do so. If you do not wish to do so, delete this
036 exception statement from your version. */
037
038 package javax.management;
039
040 import java.io.IOException;
041 import java.io.ObjectOutputStream;
042
043 import java.util.Date;
044 import java.util.EventObject;
045
046 /**
047 * <p>
048 * A notification message that may be emitted by a bean.
049 * Notifications have both a message and a type, so individual
050 * notifications can be grouped by type. They also incorporate
051 * sequencing, so that the recipient can order the delivered
052 * messages correctly (there is no guarantee that they will
053 * be delivered in order).
054 * </p>
055 * <p>
056 * Notifications also include a reference to the source of
057 * the notification. The source bean is represented either
058 * by an {@link ObjectName} or by a direct reference to the
059 * bean. The former is preferable, and notifications emitted
060 * via a {@link MBeanServer} will automatically have the source
061 * transformed into an {@link ObjectName}.
062 * </p>
063 *
064 * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
065 * @since 1.5
066 */
067 public class Notification
068 extends EventObject
069 {
070
071 /**
072 * Compatible with JDK 1.6
073 */
074 private static final long serialVersionUID = -7516092053498031989L;
075
076 /**
077 * The notification message.
078 *
079 * @serial the notification message.
080 */
081 private String message;
082
083 /**
084 * The notification's sequence number, relative to the notifications
085 * emitted by the bean.
086 *
087 * @serial the notification sequence number.
088 */
089 private long sequenceNumber;
090
091 /**
092 * The source of the notification. This is redeclared in order to
093 * replace the <code>source</code> variable in {@link java.util.EventObject}
094 * with a non-transient version.
095 *
096 * @serial the notification source.
097 */
098 protected Object source;
099
100 /**
101 * The time the notification was generated.
102 *
103 * @serial the notification timestamp.
104 */
105 private long timeStamp;
106
107 /**
108 * The type of notification sent. This utilises the same style
109 * as Java property and package names. For example,
110 * <code>gnu.gcj.compiler</code> may be one type of notifications.
111 *
112 * @serial the notification type.
113 */
114 private String type;
115
116 /**
117 * The user data associated with the notification. This includes
118 * any additional data which should be transmitted with the notification,
119 * but can't be achieved using the {@link java.lang.String} format
120 * of the <code>message</code>.
121 *
122 * @serial the notification user data.
123 */
124 private Object userData;
125
126 /**
127 * Creates a new {@link Notification} object with the specified type,
128 * source and sequence number. The timestamp is created using the
129 * current date and time.
130 *
131 * @param type the type of the notification.
132 * @param source the source of the notification.
133 * @param sequenceNumber the sequence number of the notifcation.
134 */
135 public Notification(String type, Object source, long sequenceNumber)
136 {
137 this(type, source, sequenceNumber, new Date().getTime());
138 }
139
140 /**
141 * Creates a new {@link Notification} object with the specified type,
142 * source, sequence number and timestamp.
143 *
144 * @param type the type of the notification.
145 * @param source the source of the notification.
146 * @param sequenceNumber the sequence number of the notifcation.
147 * @param timeStamp the time the notification was emitted.
148 */
149 public Notification(String type, Object source, long sequenceNumber,
150 long timeStamp)
151 {
152 this(type, source, sequenceNumber, timeStamp, "");
153 }
154
155 /**
156 * Creates a new {@link Notification} object with the specified type,
157 * source, sequence number, timestamp and message.
158 *
159 * @param type the type of the notification.
160 * @param source the source of the notification.
161 * @param sequenceNumber the sequence number of the notifcation.
162 * @param timeStamp the time the notification was emitted.
163 * @param message the message contained in the notification.
164 */
165 public Notification(String type, Object source, long sequenceNumber,
166 long timeStamp, String message)
167 {
168 super(source);
169 this.type = type;
170 this.source = source;
171 this.sequenceNumber = sequenceNumber;
172 this.timeStamp = timeStamp;
173 this.message = message;
174 }
175
176 /**
177 * Creates a new {@link Notification} object with the specified type,
178 * source, sequence number and message. The timestamp is created using
179 * the current date and time.
180 *
181 * @param type the type of the notification.
182 * @param source the source of the notification.
183 * @param sequenceNumber the sequence number of the notifcation.
184 * @param message the message contained in the notification.
185 */
186 public Notification(String type, Object source, long sequenceNumber,
187 String message)
188 {
189 this(type, source, sequenceNumber, new Date().getTime(), message);
190 }
191
192 /**
193 * Returns the message contained in this notification. The message
194 * is in {@link java.lang.String} form, and is thus intended for
195 * display to the end-user. Data transferred as part of the notification
196 * which shouldn't be displayed is included in the <code>userData</code>
197 * field.
198 *
199 * @return the notification message.
200 * @see #getUserData()
201 * @see #setUserData(java.lang.Object)
202 */
203 public String getMessage()
204 {
205 return message;
206 }
207
208 /**
209 * Returns the sequence number of this notification. This
210 * can be used to determine the order in which notifications
211 * were emitted by the broadcasting bean.
212 *
213 * @return the sequence number.
214 * @see #setSequenceNumber(long)
215 */
216 public long getSequenceNumber()
217 {
218 return sequenceNumber;
219 }
220
221 /**
222 * Returns the date and time at which this notification was
223 * emitted.
224 *
225 * @return the notification timestamp.
226 * @see #setTimeStamp(long)
227 */
228 public long getTimeStamp()
229 {
230 return timeStamp;
231 }
232
233 /**
234 * Returns the type of this notification. Types take the same
235 * form as Java package and property names.
236 *
237 * @return the type of the notification.
238 */
239 public String getType()
240 {
241 return type;
242 }
243
244 /**
245 * Returns the additional user data associated with the notification.
246 * This is used to attach additional non-textual information to the
247 * notification.
248 *
249 * @return the user data associated with the notification.
250 * @see #setUserData(java.lang.Object)
251 */
252 public Object getUserData()
253 {
254 return userData;
255 }
256
257 /**
258 * Sets the sequence number to the value specified.
259 *
260 * @param sequenceNumber the new sequence number.
261 * @see #getSequenceNumber()
262 */
263 public void setSequenceNumber(long sequenceNumber)
264 {
265 this.sequenceNumber = sequenceNumber;
266 }
267
268 /**
269 * Sets the source of this notification to the value
270 * specified.
271 *
272 * @param source the new source of the notification.
273 * @see java.util.EventSource#getSource()
274 */
275 public void setSource(Object source)
276 {
277 this.source = source;
278 }
279
280 /**
281 * Sets the date and time at which this notification
282 * was emitted.
283 *
284 * @param timeStamp the new time stamp of the notification.
285 * @see #getTimeStamp()
286 */
287 public void setTimeStamp(long timeStamp)
288 {
289 this.timeStamp = timeStamp;
290 }
291
292 /**
293 * Sets the additional user data associated with the notification
294 * to the specified value. This is used to attach additional
295 * non-textual information to the notification.
296 *
297 * @param userData the new user data associated with the notification.
298 * @see #getUserData()
299 */
300 public void setUserData(Object userData)
301 {
302 this.userData = userData;
303 }
304
305 /**
306 * A textual representation of the notification.
307 *
308 * @return the notification in {@link java.lang.String} form.
309 */
310 public String toString()
311 {
312 return getClass().getName()
313 + "[message=" + message
314 + ", sequenceNumber=" + sequenceNumber
315 + ", source=" + source
316 + ", timeStamp=" + timeStamp
317 + ", type=" + type
318 + ", userData=" + userData
319 + "]";
320 }
321
322 /**
323 * Serialize the {@link Notification}.
324 *
325 * @param out the output stream to write to.
326 * @throws IOException if an I/O error occurs.
327 */
328 private void writeObject(ObjectOutputStream out)
329 throws IOException
330 {
331 out.defaultWriteObject();
332 }
333
334 }