| /* |
| * Copyright (c) 2006, 2007, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| |
| package com.sun.tools.jconsole; |
| |
| import java.beans.PropertyChangeEvent; |
| import java.beans.PropertyChangeListener; |
| import java.util.ArrayList; |
| import java.util.List; |
| import javax.swing.JPanel; |
| import javax.swing.SwingWorker; |
| |
| /** |
| * A JConsole plugin class. JConsole uses the |
| * <a href="{@docRoot}/../../../../api/java/util/ServiceLoader.html"> |
| * service provider</a> mechanism to search the JConsole plugins. |
| * Users can provide their JConsole plugins in a jar file |
| * containing a file named |
| * |
| * <blockquote><pre> |
| * META-INF/services/com.sun.tools.jconsole.JConsolePlugin</pre></blockquote> |
| * |
| * <p> This file contains one line for each plugin, for example, |
| * |
| * <blockquote><pre> |
| * com.sun.example.JTop</pre></blockquote> |
| * <p> which is the fully qualified class name of the class implementing |
| * {@code JConsolePlugin}. |
| * |
| * <p> To load the JConsole plugins in JConsole, run: |
| * |
| * <blockquote><pre> |
| * jconsole -pluginpath <plugin-path> </pre></blockquote> |
| * |
| * <p> where <tt><plugin-path></tt> specifies the paths of JConsole |
| * plugins to look up which can be a directory or a jar file. Multiple |
| * paths are separated by the path separator character of the platform. |
| * |
| * <p> When a new JConsole window is created for a connection, |
| * an instance of each {@code JConsolePlugin} will be created. |
| * The {@code JConsoleContext} object is not available at its |
| * construction time. |
| * JConsole will set the {@link JConsoleContext} object for |
| * a plugin after the plugin object is created. It will then |
| * call its {@link #getTabs getTabs} method and add the returned |
| * tabs to the JConsole window. |
| * |
| * @see <a href="{@docRoot}/../../../../api/java/util/ServiceLoader.html"> |
| * java.util.ServiceLoader</a> |
| * |
| * @since 1.6 |
| */ |
| public abstract class JConsolePlugin { |
| private volatile JConsoleContext context = null; |
| private List<PropertyChangeListener> listeners = null; |
| |
| /** |
| * Constructor. |
| */ |
| protected JConsolePlugin() { |
| } |
| |
| /** |
| * Sets the {@link JConsoleContext JConsoleContext} object representing |
| * the connection to an application. This method will be called |
| * only once after the plugin is created and before the {@link #getTabs} |
| * is called. The given {@code context} can be in any |
| * {@link JConsoleContext#getConnectionState connection state} when |
| * this method is called. |
| * |
| * @param context a {@code JConsoleContext} object |
| */ |
| public final synchronized void setContext(JConsoleContext context) { |
| this.context = context; |
| if (listeners != null) { |
| for (PropertyChangeListener l : listeners) { |
| context.addPropertyChangeListener(l); |
| } |
| // throw away the listener list |
| listeners = null; |
| } |
| } |
| |
| /** |
| * Returns the {@link JConsoleContext JConsoleContext} object representing |
| * the connection to an application. This method may return <tt>null</tt> |
| * if it is called before the {@link #setContext context} is initialized. |
| * |
| * @return the {@link JConsoleContext JConsoleContext} object representing |
| * the connection to an application. |
| */ |
| public final JConsoleContext getContext() { |
| return context; |
| } |
| |
| /** |
| * Returns the tabs to be added in JConsole window. |
| * <p> |
| * The returned map contains one entry for each tab |
| * to be added in the tabbed pane in a JConsole window with |
| * the tab name as the key |
| * and the {@link JPanel} object as the value. |
| * This method returns an empty map if no tab is added by this plugin. |
| * This method will be called from the <i>Event Dispatch Thread</i> |
| * once at the new connection time. |
| * |
| * @return a map of a tab name and a {@link JPanel} object |
| * representing the tabs to be added in the JConsole window; |
| * or an empty map. |
| */ |
| public abstract java.util.Map<String, JPanel> getTabs(); |
| |
| /** |
| * Returns a {@link SwingWorker} to perform |
| * the GUI update for this plugin at the same interval |
| * as JConsole updates the GUI. |
| * <p> |
| * JConsole schedules the GUI update at an interval specified |
| * for a connection. This method will be called at every |
| * update to obtain a {@code SwingWorker} for each plugin. |
| * <p> |
| * JConsole will invoke the {@link SwingWorker#execute execute()} |
| * method to schedule the returned {@code SwingWorker} for execution |
| * if: |
| * <ul> |
| * <li> the <tt>SwingWorker</tt> object has not been executed |
| * (i.e. the {@link SwingWorker#getState} method |
| * returns {@link javax.swing.SwingWorker.StateValue#PENDING PENDING} |
| * state); and</li> |
| * <li> the <tt>SwingWorker</tt> object returned in the previous |
| * update has completed the task if it was not <tt>null</tt> |
| * (i.e. the {@link SwingWorker#isDone SwingWorker.isDone} method |
| * returns <tt>true</tt>).</li> |
| * </ul> |
| * <br> |
| * Otherwise, <tt>SwingWorker</tt> object will not be scheduled to work. |
| * |
| * <p> |
| * A plugin can schedule its own GUI update and this method |
| * will return <tt>null</tt>. |
| * |
| * @return a <tt>SwingWorker</tt> to perform the GUI update; or |
| * <tt>null</tt>. |
| */ |
| public abstract SwingWorker<?,?> newSwingWorker(); |
| |
| /** |
| * Dispose this plugin. This method is called by JConsole to inform |
| * that this plugin will be discarded and that it should free |
| * any resources that it has allocated. |
| * The {@link #getContext JConsoleContext} can be in any |
| * {@link JConsoleContext#getConnectionState connection state} when |
| * this method is called. |
| */ |
| public void dispose() { |
| // Default nop implementation |
| } |
| |
| /** |
| * Adds a {@link PropertyChangeListener PropertyChangeListener} |
| * to the {@link #getContext JConsoleContext} object for this plugin. |
| * This method is a convenient method for this plugin to register |
| * a listener when the {@code JConsoleContext} object may or |
| * may not be available. |
| * |
| * <p>For example, a plugin constructor can |
| * call this method to register a listener to listen to the |
| * {@link JConsoleContext.ConnectionState connectionState} |
| * property changes and the listener will be added to the |
| * {@link JConsoleContext#addPropertyChangeListener JConsoleContext} |
| * object when it is available. |
| * |
| * @param listener The {@code PropertyChangeListener} to be added |
| * |
| * @throws NullPointerException if {@code listener} is {@code null}. |
| */ |
| public final void addContextPropertyChangeListener(PropertyChangeListener listener) { |
| if (listener == null) { |
| throw new NullPointerException("listener is null"); |
| } |
| |
| if (context == null) { |
| // defer registration of the listener until setContext() is called |
| synchronized (this) { |
| // check again if context is not set |
| if (context == null) { |
| // maintain a listener list to be added later |
| if (listeners == null) { |
| listeners = new ArrayList<PropertyChangeListener>(); |
| } |
| listeners.add(listener); |
| return; |
| } |
| } |
| } |
| context.addPropertyChangeListener(listener); |
| } |
| |
| /** |
| * Removes a {@link PropertyChangeListener PropertyChangeListener} |
| * from the listener list of the {@link #getContext JConsoleContext} |
| * object for this plugin. |
| * If {@code listener} was never added, no exception is |
| * thrown and no action is taken. |
| * |
| * @param listener the {@code PropertyChangeListener} to be removed |
| * |
| * @throws NullPointerException if {@code listener} is {@code null}. |
| */ |
| public final void removeContextPropertyChangeListener(PropertyChangeListener listener) { |
| if (listener == null) { |
| throw new NullPointerException("listener is null"); |
| } |
| |
| if (context == null) { |
| // defer registration of the listener until setContext() is called |
| synchronized (this) { |
| // check again if context is not set |
| if (context == null) { |
| if (listeners != null) { |
| listeners.remove(listener); |
| } |
| return; |
| } |
| } |
| } |
| context.removePropertyChangeListener(listener); |
| } |
| } |
