1 /* 2 * Copyright (c) 2003, 2017, 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 class="striped"> 44 * <caption style="display:none">JMXConnectionNotification Types</caption> 45 * 46 * <thead style="text-align:left"> 47 * <tr> 48 * <th scope="col">Type</th> 49 * <th scope="col">Meaning</th> 50 * </tr> 51 * </thead> 52 * 53 * <tbody style="text-align:left"> 54 * <tr> 55 * <th scope="row"><code>jmx.remote.connection.opened</code></th> 56 * <td>A new client connection has been opened.</td> 57 * </tr> 58 * 59 * <tr> 60 * <th scope="row"><code>jmx.remote.connection.closed</code></th> 61 * <td>A client connection has been closed.</td> 62 * </tr> 63 * 64 * <tr> 65 * <th scope="row"><code>jmx.remote.connection.failed</code></th> 66 * <td>A client connection has failed unexpectedly.</td> 67 * </tr> 68 * 69 * <tr> 70 * <th scope="row"><code>jmx.remote.connection.notifs.lost</code></th> 71 * <td>A client connection has potentially lost notifications. This 72 * notification only appears on the client side.</td> 73 * </tr> 74 * </tbody> 75 * </table> 76 * 77 * <p>The <code>timeStamp</code> of the notification is a time value 78 * (consistent with {@link System#currentTimeMillis()}) indicating 79 * when the notification was constructed.</p> 80 * 81 * @since 1.5 82 */ 83 public class JMXConnectionNotification extends Notification { 84 85 private static final long serialVersionUID = -2331308725952627538L; 86 87 /** 88 * <p>Notification type string for a connection-opened notification. 89 */ 90 public static final String OPENED = "jmx.remote.connection.opened"; 91 92 /** 93 * <p>Notification type string for a connection-closed notification. 94 */ 95 public static final String CLOSED = "jmx.remote.connection.closed"; 96 97 /** 98 * <p>Notification type string for a connection-failed notification. 99 */ 100 public static final String FAILED = "jmx.remote.connection.failed"; 101 102 /** 103 * <p>Notification type string for a connection that has possibly 104 * lost notifications.</p> 105 */ 106 public static final String NOTIFS_LOST = 107 "jmx.remote.connection.notifs.lost"; 108 109 /** 110 * Constructs a new connection notification. The {@link 111 * #getSource() source} of the notification depends on whether it 112 * is being sent by a connector server or a connector client: 113 * 114 * <ul> 115 * 116 * <li>For a connector server, if it is registered in an MBean 117 * server, the source is the {@link ObjectName} under which it is 118 * registered. Otherwise, it is a reference to the connector 119 * server object itself, an instance of a subclass of {@link 120 * JMXConnectorServer}. 121 * 122 * <li>For a connector client, the source is a reference to the 123 * connector client object, an instance of a class implementing 124 * {@link JMXConnector}. 125 * 126 * </ul> 127 * 128 * @param type the type of the notification. This is usually one 129 * of the constants {@link #OPENED}, {@link #CLOSED}, {@link 130 * #FAILED}, {@link #NOTIFS_LOST}. It is not an error for it to 131 * be a different string. 132 * 133 * @param source the connector server or client emitting the 134 * notification. 135 * 136 * @param connectionId the ID of the connection within its 137 * connector server. 138 * 139 * @param sequenceNumber a non-negative integer. It is expected 140 * but not required that this number will be greater than any 141 * previous <code>sequenceNumber</code> in a notification from 142 * this source. 143 * 144 * @param message an unspecified text message, typically containing 145 * a human-readable description of the event. Can be null. 146 * 147 * @param userData an object whose type and meaning is defined by 148 * the connector server. Can be null. 149 * 150 * @exception NullPointerException if <code>type</code>, 151 * <code>source</code>, or <code>connectionId</code> is null. 152 * 153 * @exception IllegalArgumentException if 154 * <code>sequenceNumber</code> is negative. 155 */ JMXConnectionNotification(String type, Object source, String connectionId, long sequenceNumber, String message, Object userData)156 public JMXConnectionNotification(String type, 157 Object source, 158 String connectionId, 159 long sequenceNumber, 160 String message, 161 Object userData) { 162 /* We don't know whether the parent class (Notification) will 163 throw an exception if the type or source is null, because 164 JMX 1.2 doesn't specify that. So we make sure it is not 165 null, in case it would throw the wrong exception 166 (e.g. IllegalArgumentException instead of 167 NullPointerException). Likewise for the sequence number. */ 168 super((String) nonNull(type), 169 nonNull(source), 170 Math.max(0, sequenceNumber), 171 System.currentTimeMillis(), 172 message); 173 if (type == null || source == null || connectionId == null) 174 throw new NullPointerException("Illegal null argument"); 175 if (sequenceNumber < 0) 176 throw new IllegalArgumentException("Negative sequence number"); 177 this.connectionId = connectionId; 178 setUserData(userData); 179 } 180 nonNull(Object arg)181 private static Object nonNull(Object arg) { 182 if (arg == null) 183 return ""; 184 else 185 return arg; 186 } 187 188 /** 189 * <p>The connection ID to which this notification pertains. 190 * 191 * @return the connection ID. 192 */ getConnectionId()193 public String getConnectionId() { 194 return connectionId; 195 } 196 197 /** 198 * @serial The connection ID to which this notification pertains. 199 * @see #getConnectionId() 200 **/ 201 private final String connectionId; 202 } 203