1/*
2 * Copyright (c) 2006, 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 com.sun.tools.jconsole;
27
28import javax.management.MBeanServerConnection;
29import java.beans.PropertyChangeListener;
30import javax.swing.event.SwingPropertyChangeSupport;
31
32/**
33 * {@code JConsoleContext} represents a JConsole connection to a target
34 * application.
35 * <p>
36 * {@code JConsoleContext} notifies any {@code PropertyChangeListeners}
37 * about the {@linkplain #CONNECTION_STATE_PROPERTY <i>ConnectionState</i>}
38 * property change to {@link ConnectionState#CONNECTED CONNECTED} and
39 * {@link ConnectionState#DISCONNECTED DISCONNECTED}.
40 * The {@code JConsoleContext} instance will be the source for
41 * any generated events.
42 *
43 * @since 1.6
44 */
45public interface JConsoleContext {
46    /**
47     * The {@link ConnectionState ConnectionState} bound property name.
48     */
49    public static String CONNECTION_STATE_PROPERTY = "connectionState";
50
51    /**
52     * Values for the {@linkplain #CONNECTION_STATE_PROPERTY
53     * <i>ConnectionState</i>} bound property.
54     */
55    public enum ConnectionState {
56        /**
57         * The connection has been successfully established.
58         */
59        CONNECTED,
60        /**
61         * No connection present.
62         */
63        DISCONNECTED,
64        /**
65         * The connection is being attempted.
66         */
67        CONNECTING
68    }
69
70    /**
71     * Returns the {@link MBeanServerConnection MBeanServerConnection} for the
72     * connection to an application.  The returned
73     * {@code MBeanServerConnection} object becomes invalid when
74     * the connection state is changed to the
75     * {@link ConnectionState#DISCONNECTED DISCONNECTED} state.
76     *
77     * @return the {@code MBeanServerConnection} for the
78     * connection to an application.
79     */
80    public MBeanServerConnection getMBeanServerConnection();
81
82    /**
83     * Returns the current connection state.
84     * @return the current connection state.
85     */
86    public ConnectionState getConnectionState();
87
88    /**
89     * Add a {@link java.beans.PropertyChangeListener PropertyChangeListener}
90     * to the listener list.
91     * The listener is registered for all properties.
92     * The same listener object may be added more than once, and will be called
93     * as many times as it is added.
94     * If {@code listener} is {@code null}, no exception is thrown and
95     * no action is taken.
96     *
97     * @param listener  The {@code PropertyChangeListener} to be added
98     */
99    public void addPropertyChangeListener(PropertyChangeListener listener);
100
101    /**
102     * Removes a {@link java.beans.PropertyChangeListener PropertyChangeListener}
103     * from the listener list. This
104     * removes a {@code PropertyChangeListener} that was registered for all
105     * properties. If {@code listener} was added more than once to the same
106     * event source, it will be notified one less time after being removed. If
107     * {@code listener} is {@code null}, or was never added, no exception is
108     * thrown and no action is taken.
109     *
110     * @param listener the {@code PropertyChangeListener} to be removed
111     */
112    public void removePropertyChangeListener(PropertyChangeListener listener);
113}
114