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 }