1/*
2 * Copyright (c) 1999, 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
26package javax.management;
27
28
29/**
30 * Represents a notification emitted by the MBean Server through the MBeanServerDelegate MBean.
31 * The MBean Server emits the following types of notifications: MBean registration, MBean
32 * unregistration.
33 * <P>
34 * To receive MBeanServerNotifications, you need to register a listener with
35 * the {@link MBeanServerDelegate MBeanServerDelegate} MBean
36 * that represents the MBeanServer. The ObjectName of the MBeanServerDelegate is
37 * {@link MBeanServerDelegate#DELEGATE_NAME}, which is
38 * <CODE>JMImplementation:type=MBeanServerDelegate</CODE>.
39 *
40 * <p>The following code prints a message every time an MBean is registered
41 * or unregistered in the MBean Server {@code mbeanServer}:</p>
42 *
43 * <pre>
44 * private static final NotificationListener printListener = new NotificationListener() {
45 *     public void handleNotification(Notification n, Object handback) {
46 *         if (!(n instanceof MBeanServerNotification)) {
47 *             System.out.println("Ignored notification of class " + n.getClass().getName());
48 *             return;
49 *         }
50 *         MBeanServerNotification mbsn = (MBeanServerNotification) n;
51 *         String what;
52 *         if (n.getType().equals(MBeanServerNotification.REGISTRATION_NOTIFICATION))
53 *             what = "MBean registered";
54 *         else if (n.getType().equals(MBeanServerNotification.UNREGISTRATION_NOTIFICATION))
55 *             what = "MBean unregistered";
56 *         else
57 *             what = "Unknown type " + n.getType();
58 *         System.out.println("Received MBean Server notification: " + what + ": " +
59 *                 mbsn.getMBeanName());
60 *     }
61 * };
62 *
63 * ...
64 *     mbeanServer.addNotificationListener(
65 *             MBeanServerDelegate.DELEGATE_NAME, printListener, null, null);
66 * </pre>
67 *
68 * <p id="group">
69 * An MBean which is not an {@link MBeanServerDelegate} may also emit
70 * MBeanServerNotifications. In particular, there is a convention for
71 * MBeans to emit an MBeanServerNotification for a group of MBeans.</p>
72 *
73 * <p>An MBeanServerNotification emitted to denote the registration or
74 * unregistration of a group of MBeans has the following characteristics:
75 * <ul><li>Its {@linkplain Notification#getType() notification type} is
76 *     {@code "JMX.mbean.registered.group"} or
77 *     {@code "JMX.mbean.unregistered.group"}, which can also be written {@link
78 *     MBeanServerNotification#REGISTRATION_NOTIFICATION}{@code + ".group"} or
79 *     {@link
80 *     MBeanServerNotification#UNREGISTRATION_NOTIFICATION}{@code + ".group"}.
81 * </li>
82 * <li>Its {@linkplain #getMBeanName() MBean name} is an ObjectName pattern
83 *     that selects the set (or a superset) of the MBeans being registered
84 *     or unregistered</li>
85 * <li>Its {@linkplain Notification#getUserData() user data} can optionally
86 *     be set to an array of ObjectNames containing the names of all MBeans
87 *     being registered or unregistered.</li>
88 * </ul>
89 *
90 * <p>
91 * MBeans which emit these group registration/unregistration notifications will
92 * declare them in their {@link MBeanInfo#getNotifications()
93 * MBeanNotificationInfo}.
94 * </p>
95 *
96 * @since 1.5
97 */
98public class MBeanServerNotification extends Notification {
99
100
101    /* Serial version */
102    private static final long serialVersionUID = 2876477500475969677L;
103    /**
104     * Notification type denoting that an MBean has been registered.
105     * Value is "JMX.mbean.registered".
106     */
107    public static final String REGISTRATION_NOTIFICATION =
108            "JMX.mbean.registered";
109    /**
110     * Notification type denoting that an MBean has been unregistered.
111     * Value is "JMX.mbean.unregistered".
112     */
113    public static final String UNREGISTRATION_NOTIFICATION =
114            "JMX.mbean.unregistered";
115    /**
116     * @serial The object names of the MBeans concerned by this notification
117     */
118    private final ObjectName objectName;
119
120    /**
121     * Creates an MBeanServerNotification object specifying object names of
122     * the MBeans that caused the notification and the specified notification
123     * type.
124     *
125     * @param type A string denoting the type of the
126     * notification. Set it to one these values: {@link
127     * #REGISTRATION_NOTIFICATION}, {@link
128     * #UNREGISTRATION_NOTIFICATION}.
129     * @param source The MBeanServerNotification object responsible
130     * for forwarding MBean server notification.
131     * @param sequenceNumber A sequence number that can be used to order
132     * received notifications.
133     * @param objectName The object name of the MBean that caused the
134     * notification.
135     *
136     */
137    public MBeanServerNotification(String type, Object source,
138            long sequenceNumber, ObjectName objectName) {
139        super(type, source, sequenceNumber);
140        this.objectName = objectName;
141    }
142
143    /**
144     * Returns the  object name of the MBean that caused the notification.
145     *
146     * @return the object name of the MBean that caused the notification.
147     */
148    public ObjectName getMBeanName() {
149        return objectName;
150    }
151
152    @Override
153    public String toString() {
154        return super.toString() + "[mbeanName=" + objectName + "]";
155
156    }
157
158 }
159