1 /* 2 * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 27 package javax.management.remote; 28 29 import javax.management.Notification; 30 import javax.management.ObjectName; 31 32 /** 33 * <p>Notification emitted when a client connection is opened or 34 * closed or when notifications are lost. These notifications are 35 * sent by connector servers (instances of {@link JMXConnectorServer}) 36 * and by connector clients (instances of {@link JMXConnector}). For 37 * certain connectors, a session can consist of a sequence of 38 * connections. Connection-opened and connection-closed notifications 39 * will be sent for each one.</p> 40 * 41 * <p>The notification type is one of the following:</p> 42 * 43 * <table summary="JMXConnectionNotification Types"> 44 * 45 * <tr> 46 * <th align=left>Type</th> 47 * <th align=left>Meaning</th> 48 * </tr> 49 * 50 * <tr> 51 * <td><code>jmx.remote.connection.opened</code></td> 52 * <td>A new client connection has been opened.</td> 53 * </tr> 54 * 55 * <tr> 56 * <td><code>jmx.remote.connection.closed</code></td> 57 * <td>A client connection has been closed.</td> 58 * </tr> 59 * 60 * <tr> 61 * <td><code>jmx.remote.connection.failed</code></td> 62 * <td>A client connection has failed unexpectedly.</td> 63 * </tr> 64 * 65 * <tr> 66 * <td><code>jmx.remote.connection.notifs.lost</code></td> 67 * <td>A client connection has potentially lost notifications. This 68 * notification only appears on the client side.</td> 69 * </tr> 70 * </table> 71 * 72 * <p>The <code>timeStamp</code> of the notification is a time value 73 * (consistent with {@link System#currentTimeMillis()}) indicating 74 * when the notification was constructed.</p> 75 * 76 * @since 1.5 77 */ 78 public class JMXConnectionNotification extends Notification { 79 80 private static final long serialVersionUID = -2331308725952627538L; 81 82 /** 83 * <p>Notification type string for a connection-opened notification. 84 */ 85 public static final String OPENED = "jmx.remote.connection.opened"; 86 87 /** 88 * <p>Notification type string for a connection-closed notification. 89 */ 90 public static final String CLOSED = "jmx.remote.connection.closed"; 91 92 /** 93 * <p>Notification type string for a connection-failed notification. 94 */ 95 public static final String FAILED = "jmx.remote.connection.failed"; 96 97 /** 98 * <p>Notification type string for a connection that has possibly 99 * lost notifications.</p> 100 */ 101 public static final String NOTIFS_LOST = 102 "jmx.remote.connection.notifs.lost"; 103 104 /** 105 * Constructs a new connection notification. The {@link 106 * #getSource() source} of the notification depends on whether it 107 * is being sent by a connector server or a connector client: 108 * 109 * <ul> 110 * 111 * <li>For a connector server, if it is registered in an MBean 112 * server, the source is the {@link ObjectName} under which it is 113 * registered. Otherwise, it is a reference to the connector 114 * server object itself, an instance of a subclass of {@link 115 * JMXConnectorServer}. 116 * 117 * <li>For a connector client, the source is a reference to the 118 * connector client object, an instance of a class implementing 119 * {@link JMXConnector}. 120 * 121 * </ul> 122 * 123 * @param type the type of the notification. This is usually one 124 * of the constants {@link #OPENED}, {@link #CLOSED}, {@link 125 * #FAILED}, {@link #NOTIFS_LOST}. It is not an error for it to 126 * be a different string. 127 * 128 * @param source the connector server or client emitting the 129 * notification. 130 * 131 * @param connectionId the ID of the connection within its 132 * connector server. 133 * 134 * @param sequenceNumber a non-negative integer. It is expected 135 * but not required that this number will be greater than any 136 * previous <code>sequenceNumber</code> in a notification from 137 * this source. 138 * 139 * @param message an unspecified text message, typically containing 140 * a human-readable description of the event. Can be null. 141 * 142 * @param userData an object whose type and meaning is defined by 143 * the connector server. Can be null. 144 * 145 * @exception NullPointerException if <code>type</code>, 146 * <code>source</code>, or <code>connectionId</code> is null. 147 * 148 * @exception IllegalArgumentException if 149 * <code>sequenceNumber</code> is negative. 150 */ JMXConnectionNotification(String type, Object source, String connectionId, long sequenceNumber, String message, Object userData)151 public JMXConnectionNotification(String type, 152 Object source, 153 String connectionId, 154 long sequenceNumber, 155 String message, 156 Object userData) { 157 /* We don't know whether the parent class (Notification) will 158 throw an exception if the type or source is null, because 159 JMX 1.2 doesn't specify that. So we make sure it is not 160 null, in case it would throw the wrong exception 161 (e.g. IllegalArgumentException instead of 162 NullPointerException). Likewise for the sequence number. */ 163 super((String) nonNull(type), 164 nonNull(source), 165 Math.max(0, sequenceNumber), 166 System.currentTimeMillis(), 167 message); 168 if (type == null || source == null || connectionId == null) 169 throw new NullPointerException("Illegal null argument"); 170 if (sequenceNumber < 0) 171 throw new IllegalArgumentException("Negative sequence number"); 172 this.connectionId = connectionId; 173 setUserData(userData); 174 } 175 nonNull(Object arg)176 private static Object nonNull(Object arg) { 177 if (arg == null) 178 return ""; 179 else 180 return arg; 181 } 182 183 /** 184 * <p>The connection ID to which this notification pertains. 185 * 186 * @return the connection ID. 187 */ getConnectionId()188 public String getConnectionId() { 189 return connectionId; 190 } 191 192 /** 193 * @serial The connection ID to which this notification pertains. 194 * @see #getConnectionId() 195 **/ 196 private final String connectionId; 197 } 198