001/* Notification.java -- A notification emitted by a bean.
002   Copyright (C) 2006 Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038package javax.management;
039
040import java.io.IOException;
041import java.io.ObjectOutputStream;
042
043import java.util.Date;
044import 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 */
067public 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}
335