| /* |
| * Copyright (c) 2004, 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 sun.jvmstat.monitor; |
| |
| import java.util.List; |
| |
| import sun.jvmstat.monitor.event.VmListener; |
| |
| /** |
| * Interface for interacting with a monitorable Java Virtual Machine. |
| * The MonitoredVm interface provides methods for discovery of exported |
| * instrumentation, for attaching event listeners, and for overall |
| * maintenance of the connection to the target. |
| * |
| * @author Brian Doherty |
| * @since 1.5 |
| */ |
| public interface MonitoredVm { |
| |
| /** |
| * Get the VmIdentifier associated with this MonitoredVm |
| * |
| * @return VmIdentifier - the fully resolved Vm identifier associated |
| * with this MonitoredVm. |
| */ |
| VmIdentifier getVmIdentifier(); |
| |
| /** |
| * Find a named Instrumentation object. |
| * |
| * This method will look for the named instrumentation object in the |
| * instrumentation exported by this Java Virtual Machine. If an |
| * instrumentation object with the given name exists, a Monitor interface |
| * to that object will be return. Otherwise, the method returns |
| * <tt>null</tt>. |
| * |
| * @param name the name of the Instrumentation object to find. |
| * @return Monitor - the {@link Monitor} object that can be used to |
| * monitor the the named instrumentation object, or |
| * <tt>null</tt> if the named object doesn't exist. |
| * @throws MonitorException Thrown if an error occurs while communicating |
| * with the target Java Virtual Machine. |
| */ |
| Monitor findByName(String name) throws MonitorException; |
| |
| /** |
| * Find all Instrumentation objects with names matching the given pattern. |
| * |
| * This method returns a {@link List} of Monitor objects such that |
| * the name of each object matches the given pattern. |
| * |
| * @param patternString a string containing a pattern as described in |
| * {@link java.util.regex.Pattern}. |
| * @return List<Monitor> - a List of {@link Monitor} objects that can be used to |
| * monitor the instrumentation objects whose names match |
| * the given pattern. If no instrumentation objects have` |
| * names matching the given pattern, then an empty List |
| * is returned. |
| * @throws MonitorException Thrown if an error occurs while communicating |
| * with the target Java Virtual Machine. |
| * @see java.util.regex.Pattern |
| */ |
| List<Monitor> findByPattern(String patternString) throws MonitorException; |
| |
| /** |
| * Detach from target Java Virtual Machine. |
| * |
| * After calling this method, updates of the instrumentation data values |
| * may be halted. All event notifications are halted. Further interactions |
| * with this object should be avoided. |
| */ |
| void detach(); |
| |
| |
| /* ---- Methods to support polled MonitoredVm Implementations ---- */ |
| |
| /** |
| * Set the polling interval to <code>interval</code> milliseconds. |
| * |
| * Polling based monitoring implementations need to refresh the |
| * instrumentation data on a periodic basis. This interface allows |
| * the interval to override the implementation specific default |
| * interval. |
| * |
| * @param interval the polling interval in milliseconds |
| */ |
| void setInterval(int interval); |
| |
| /** |
| * Get the polling interval. |
| * |
| * @return int - the current polling interval in milliseconds. |
| * @see #setInterval |
| */ |
| int getInterval(); |
| |
| /** |
| * Set the last exception encountered while polling this MonitoredVm. |
| * |
| * Polling implementations may choose to poll asynchronously. This |
| * method allows an asynchronous task to communicate any polling related |
| * exceptions with the application. When an a non-null exception is reported |
| * through this interface, the MonitoredVm instance is considered to |
| * be in the <em>errored</em> state. |
| * |
| * @param cause the exception to record. |
| * @see #isErrored |
| */ |
| void setLastException(Exception cause); |
| |
| /** |
| * Get the last exception encountered while polling this MonitoredVm. |
| * |
| * Returns the last exception observed by the implementation dependent |
| * polling task or <tt>null</tt> if no such error has occurred. |
| * |
| * @return Exception - the last exception that occurred during polling |
| * or <tt>null</tt> if no error condition exists. |
| * @see #isErrored |
| * @see #setLastException |
| */ |
| Exception getLastException(); |
| |
| /** |
| * Clear the last exception. |
| * |
| * Calling this method will clear the <em>errored</em> state of this |
| * MonitoredVm. However, there is no guarantee that clearing the |
| * the errored state return the asynchronous polling task to an |
| * operational state. |
| * |
| */ |
| void clearLastException(); |
| |
| /** |
| * Test if this MonitoredVm is in the errored state. |
| * The errored state exists only if an error was reported with |
| * call to {@link #setLastException} and only if the parameter to |
| * that call was non-null and no subsequent calls are made to |
| * {@link #clearLastException}. |
| * |
| * @return boolean - true if the instance has a non-null error condition |
| * set, false otherwise. |
| * |
| * @see #setLastException |
| * @see #getLastException |
| */ |
| boolean isErrored(); |
| |
| /** |
| * Add a VmListener. The given listener is added to the list of |
| * VmListener objects to be notified of MonitoredVm related events. |
| * |
| * @param listener the VmListener to add. |
| * @throws MonitorException Thrown if any problems occur while attempting |
| * to add this listener. |
| */ |
| void addVmListener(VmListener listener) throws MonitorException; |
| |
| /** |
| * Remove a VmListener. The given listener is removed from the list of |
| * VmListener objects to be notified of MonitoredVm related events. |
| * |
| * @param listener the VmListener to be removed. |
| * @throws MonitorException Thrown if any problems occur while attempting |
| * to remove this listener. |
| */ |
| void removeVmListener(VmListener listener) throws MonitorException; |
| } |