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    }
335