001 /*
002 * Copyright 2003-2007 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.management.remote;
027
028 import javax.management.Notification;
029 import javax.management.ObjectName;
030
031 /**
032 * <p>Notification emitted when a client connection is opened or
033 * closed or when notifications are lost. These notifications are
034 * sent by connector servers (instances of {@link JMXConnectorServer})
035 * and by connector clients (instances of {@link JMXConnector}). For
036 * certain connectors, a session can consist of a sequence of
037 * connections. Connection-opened and connection-closed notifications
038 * will be sent for each one.</p>
039 *
040 * <p>The notification type is one of the following:</p>
041 *
042 * <table>
043 *
044 * <tr>
045 * <th align=left>Type</th>
046 * <th align=left>Meaning</th>
047 * </tr>
048 *
049 * <tr>
050 * <td><code>jmx.remote.connection.opened</code></td>
051 * <td>A new client connection has been opened.</td>
052 * </tr>
053 *
054 * <tr>
055 * <td><code>jmx.remote.connection.closed</code></td>
056 * <td>A client connection has been closed.</td>
057 * </tr>
058 *
059 * <tr>
060 * <td><code>jmx.remote.connection.failed</code></td>
061 * <td>A client connection has failed unexpectedly.</td>
062 * </tr>
063 *
064 * <tr>
065 * <td><code>jmx.remote.connection.notifs.lost</code></td>
066 * <td>A client connection has potentially lost notifications. This
067 * notification only appears on the client side.</td>
068 * </tr>
069 * </table>
070 *
071 * <p>The <code>timeStamp</code> of the notification is a time value
072 * (consistent with {@link System#currentTimeMillis()}) indicating
073 * when the notification was constructed.</p>
074 *
075 * @since 1.5
076 */
077 public class JMXConnectionNotification extends Notification {
078
079 private static final long serialVersionUID = -2331308725952627538L;
080
081 /**
082 * <p>Notification type string for a connection-opened notification.
083 */
084 public static final String OPENED = "jmx.remote.connection.opened";
085
086 /**
087 * <p>Notification type string for a connection-closed notification.
088 */
089 public static final String CLOSED = "jmx.remote.connection.closed";
090
091 /**
092 * <p>Notification type string for a connection-failed notification.
093 */
094 public static final String FAILED = "jmx.remote.connection.failed";
095
096 /**
097 * <p>Notification type string for a connection that has possibly
098 * lost notifications.</p>
099 */
100 public static final String NOTIFS_LOST = "jmx.remote.connection.notifs.lost";
101
102 /**
103 * Constructs a new connection notification. The {@link
104 * #getSource() source} of the notification depends on whether it
105 * is being sent by a connector server or a connector client:
106 *
107 * <ul>
108 *
109 * <li>For a connector server, if it is registered in an MBean
110 * server, the source is the {@link ObjectName} under which it is
111 * registered. Otherwise, it is a reference to the connector
112 * server object itself, an instance of a subclass of {@link
113 * JMXConnectorServer}.
114 *
115 * <li>For a connector client, the source is a reference to the
116 * connector client object, an instance of a class implementing
117 * {@link JMXConnector}.
118 *
119 * </ul>
120 *
121 * @param type the type of the notification. This is usually one
122 * of the constants {@link #OPENED}, {@link #CLOSED}, {@link
123 * #FAILED}, {@link #NOTIFS_LOST}. It is not an error for it to
124 * be a different string.
125 *
126 * @param source the connector server or client emitting the
127 * notification.
128 *
129 * @param connectionId the ID of the connection within its
130 * connector server.
131 *
132 * @param sequenceNumber a non-negative integer. It is expected
133 * but not required that this number will be greater than any
134 * previous <code>sequenceNumber</code> in a notification from
135 * this source.
136 *
137 * @param message an unspecified text message, typically containing
138 * a human-readable description of the event. Can be null.
139 *
140 * @param userData an object whose type and meaning is defined by
141 * the connector server. Can be null.
142 *
143 * @exception NullPointerException if <code>type</code>,
144 * <code>source</code>, or <code>connectionId</code> is null.
145 *
146 * @exception IllegalArgumentException if
147 * <code>sequenceNumber</code> is negative.
148 */
149 public JMXConnectionNotification(String type, Object source,
150 String connectionId, long sequenceNumber, String message,
151 Object userData) {
152 /* We don't know whether the parent class (Notification) will
153 throw an exception if the type or source is null, because
154 JMX 1.2 doesn't specify that. So we make sure it is not
155 null, in case it would throw the wrong exception
156 (e.g. IllegalArgumentException instead of
157 NullPointerException). Likewise for the sequence number. */
158 super ((String) nonNull(type), nonNull(source), Math.max(0,
159 sequenceNumber), System.currentTimeMillis(), message);
160 if (type == null || source == null || connectionId == null)
161 throw new NullPointerException("Illegal null argument");
162 if (sequenceNumber < 0)
163 throw new IllegalArgumentException(
164 "Negative sequence number");
165 this .connectionId = connectionId;
166 setUserData(userData);
167 }
168
169 private static Object nonNull(Object arg) {
170 if (arg == null)
171 return "";
172 else
173 return arg;
174 }
175
176 /**
177 * <p>The connection ID to which this notification pertains.
178 *
179 * @return the connection ID.
180 */
181 public String getConnectionId() {
182 return connectionId;
183 }
184
185 /**
186 * @serial The connection ID to which this notification pertains.
187 * @see #getConnectionId()
188 **/
189 private final String connectionId;
190 }
|