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