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.util.Date;
  41: import java.util.EventObject;
  42: 
  43: /**
  44:  * <p>
  45:  * A notification message that may be emitted by a bean.
  46:  * Notifications have both a message and a type, so individual
  47:  * notifications can be grouped by type.  They also incorporate
  48:  * sequencing, so that the recipient can order the delivered
  49:  * messages correctly (there is no guarantee that they will
  50:  * be delivered in order).
  51:  * </p>
  52:  * <p>
  53:  * Notifications also include a reference to the source of
  54:  * the notification.  The source bean is represented either
  55:  * by an {@link ObjectName} or by a direct reference to the
  56:  * bean.  The former is preferable, and notifications emitted
  57:  * via a {@link MBeanServer} will automatically have the source
  58:  * transformed into an {@link ObjectName}.
  59:  * </p>
  60:  *
  61:  * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
  62:  * @since 1.5
  63:  */
  64: public class Notification
  65:   extends EventObject
  66: {
  67: 
  68:   /**
  69:    * The notification message.
  70:    *
  71:    * @serial the notification message.
  72:    */
  73:   private String message;
  74: 
  75:   /**
  76:    * The notification's sequence number, relative to the notifications
  77:    * emitted by the bean.
  78:    *
  79:    * @serial the notification sequence number.
  80:    */
  81:   private long sequenceNumber;
  82: 
  83:   /**
  84:    * The source of the notification.  This is redeclared in order to
  85:    * replace the <code>source</code> variable in {@link java.util.EventObject}
  86:    * with a non-transient version.
  87:    *
  88:    * @serial the notification source.
  89:    */
  90:   protected Object source;
  91: 
  92:   /**
  93:    * The time the notification was generated.
  94:    *
  95:    * @serial the notification timestamp.
  96:    */
  97:   private long timeStamp;
  98: 
  99:   /**
 100:    * The type of notification sent.  This utilises the same style
 101:    * as Java property and package names.  For example,
 102:    * <code>gnu.gcj.compiler</code> may be one type of notifications.
 103:    *
 104:    * @serial the notification type.
 105:    */
 106:   private String type;
 107: 
 108:   /**
 109:    * The user data associated with the notification.  This includes
 110:    * any additional data which should be transmitted with the notification,
 111:    * but can't be achieved using the {@link java.lang.String} format
 112:    * of the <code>message</code>.
 113:    *
 114:    * @serial the notification user data.
 115:    */
 116:   private Object userData;
 117: 
 118:   /**
 119:    * Creates a new {@link Notification} object with the specified type,
 120:    * source and sequence number.  The timestamp is created using the
 121:    * current date and time.
 122:    *
 123:    * @param type the type of the notification.
 124:    * @param source the source of the notification.
 125:    * @param sequenceNumber the sequence number of the notifcation.
 126:    */
 127:   public Notification(String type, Object source, long sequenceNumber)
 128:   {
 129:     this(type, source, sequenceNumber, new Date().getTime());
 130:   }
 131: 
 132:   /**
 133:    * Creates a new {@link Notification} object with the specified type,
 134:    * source, sequence number and timestamp.  
 135:    *
 136:    * @param type the type of the notification.
 137:    * @param source the source of the notification.
 138:    * @param sequenceNumber the sequence number of the notifcation.
 139:    * @param timeStamp the time the notification was emitted.
 140:    */
 141:   public Notification(String type, Object source, long sequenceNumber,
 142:               long timeStamp)
 143:   {
 144:     this(type, source, sequenceNumber, timeStamp, null);
 145:   }
 146: 
 147:   /**
 148:    * Creates a new {@link Notification} object with the specified type,
 149:    * source, sequence number, timestamp and message.  
 150:    *
 151:    * @param type the type of the notification.
 152:    * @param source the source of the notification.
 153:    * @param sequenceNumber the sequence number of the notifcation.
 154:    * @param timeStamp the time the notification was emitted.
 155:    * @param message the message contained in the notification.
 156:    */
 157:   public Notification(String type, Object source, long sequenceNumber,
 158:               long timeStamp, String message)
 159:   {
 160:     super(source);
 161:     this.type = type;
 162:     this.sequenceNumber = sequenceNumber;
 163:     this.timeStamp = timeStamp;
 164:     this.message = message;
 165:   }
 166: 
 167:   /**
 168:    * Creates a new {@link Notification} object with the specified type,
 169:    * source, sequence number and message.  The timestamp is created using
 170:    * the current date and time.
 171:    *
 172:    * @param type the type of the notification.
 173:    * @param source the source of the notification.
 174:    * @param sequenceNumber the sequence number of the notifcation.
 175:    * @param message the message contained in the notification.
 176:    */
 177:   public Notification(String type, Object source, long sequenceNumber,
 178:               String message)
 179:   {
 180:     this(type, source, sequenceNumber, new Date().getTime(), message);
 181:   }
 182: 
 183:   /**
 184:    * Returns the message contained in this notification.  The message
 185:    * is in {@link java.lang.String} form, and is thus intended for
 186:    * display to the end-user.  Data transferred as part of the notification
 187:    * which shouldn't be displayed is included in the <code>userData</code>
 188:    * field.
 189:    *
 190:    * @return the notification message.
 191:    * @see #getUserData()
 192:    * @see #setUserData(java.lang.Object)
 193:    */
 194:   public String getMessage()
 195:   {
 196:     return message;
 197:   }
 198: 
 199:   /**
 200:    * Returns the sequence number of this notification.  This
 201:    * can be used to determine the order in which notifications
 202:    * were emitted by the broadcasting bean.
 203:    *
 204:    * @return the sequence number.
 205:    * @see #setSequenceNumber(long)
 206:    */
 207:   public long getSequenceNumber()
 208:   {
 209:     return sequenceNumber;
 210:   }
 211: 
 212:   /**
 213:    * Returns the date and time at which this notification was
 214:    * emitted.
 215:    *
 216:    * @return the notification timestamp.
 217:    * @see #setTimeStamp(long)
 218:    */
 219:   public long getTimeStamp()
 220:   {
 221:     return timeStamp;
 222:   }
 223: 
 224:   /**
 225:    * Returns the type of this notification.  Types take the same
 226:    * form as Java package and property names.
 227:    *
 228:    * @return the type of the notification.
 229:    */
 230:   public String getType()
 231:   {
 232:     return type;
 233:   }
 234: 
 235:   /**
 236:    * Returns the additional user data associated with the notification.
 237:    * This is used to attach additional non-textual information to the
 238:    * notification.
 239:    *
 240:    * @return the user data associated with the notification.
 241:    * @see #setUserData(java.lang.Object)
 242:    */
 243:   public Object getUserData()
 244:   {
 245:     return userData;
 246:   }
 247: 
 248:   /**
 249:    * Sets the sequence number to the value specified.
 250:    *
 251:    * @param sequenceNumber the new sequence number.
 252:    * @see #getSequenceNumber()
 253:    */
 254:   public void setSequenceNumber(long sequenceNumber)
 255:   {
 256:     this.sequenceNumber = sequenceNumber;
 257:   }
 258: 
 259:   /**
 260:    * Sets the source of this notification to the value
 261:    * specified.
 262:    *
 263:    * @param source the new source of the notification.
 264:    * @see java.util.EventSource#getSource()
 265:    */
 266:   public void setSource(Object source)
 267:   {
 268:     this.source = source;
 269:   }
 270: 
 271:   /**
 272:    * Sets the date and time at which this notification
 273:    * was emitted.
 274:    *
 275:    * @param timeStamp the new time stamp of the notification.
 276:    * @see #getTimeStamp()
 277:    */
 278:   public void setTimeStamp(long timeStamp)
 279:   {
 280:     this.timeStamp = timeStamp;
 281:   }
 282: 
 283:   /**
 284:    * Sets the additional user data associated with the notification
 285:    * to the specified value.  This is used to attach additional
 286:    * non-textual information to the notification.
 287:    *
 288:    * @param userData the new user data associated with the notification.
 289:    * @see #getUserData()
 290:    */
 291:   public void setUserData(Object userData)
 292:   {
 293:     this.userData = userData;
 294:   }
 295: 
 296:   /**
 297:    * A textual representation of the notification.
 298:    * 
 299:    * @return the notification in {@link java.lang.String} form.
 300:    */
 301:   public String toString()
 302:   {
 303:     return getClass().getName()
 304:       + "[message=" + message 
 305:       + ", sequenceNumber=" + sequenceNumber 
 306:       + ", source=" + source 
 307:       + ", timeStamp=" + timeStamp
 308:       + ", type=" + type
 309:       + ", userData=" + userData
 310:       + "]";
 311:   }
 312: 
 313: }