Source for javax.management.Notification

   1: /* Notification.java -- A notification emitted by a bean.
   2:    Copyright (C) 2006 Free Software Foundation, Inc.
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10: 
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: package javax.management;
  39: 
  40: import java.io.IOException;
  41: import java.io.ObjectOutputStream;
  42: 
  43: import java.util.Date;
  44: import java.util.EventObject;
  45: 
  46: /**
  47:  * <p>
  48:  * A notification message that may be emitted by a bean.
  49:  * Notifications have both a message and a type, so individual
  50:  * notifications can be grouped by type.  They also incorporate
  51:  * sequencing, so that the recipient can order the delivered
  52:  * messages correctly (there is no guarantee that they will
  53:  * be delivered in order).
  54:  * </p>
  55:  * <p>
  56:  * Notifications also include a reference to the source of
  57:  * the notification.  The source bean is represented either
  58:  * by an {@link ObjectName} or by a direct reference to the
  59:  * bean.  The former is preferable, and notifications emitted
  60:  * via a {@link MBeanServer} will automatically have the source
  61:  * transformed into an {@link ObjectName}.
  62:  * </p>
  63:  *
  64:  * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
  65:  * @since 1.5
  66:  */
  67: public class Notification
  68:   extends EventObject
  69: {
  70: 
  71:   /**
  72:    * Compatible with JDK 1.6
  73:    */
  74:   private static final long serialVersionUID = -7516092053498031989L;
  75: 
  76:   /**
  77:    * The notification message.
  78:    *
  79:    * @serial the notification message.
  80:    */
  81:   private String message;
  82: 
  83:   /**
  84:    * The notification's sequence number, relative to the notifications
  85:    * emitted by the bean.
  86:    *
  87:    * @serial the notification sequence number.
  88:    */
  89:   private long sequenceNumber;
  90: 
  91:   /**
  92:    * The source of the notification.  This is redeclared in order to
  93:    * replace the <code>source</code> variable in {@link java.util.EventObject}
  94:    * with a non-transient version.
  95:    *
  96:    * @serial the notification source.
  97:    */
  98:   protected Object source;
  99: 
 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: }