1 /* 2 * Copyright (c) 2004, 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 package sun.jvmstat.monitor; 27 28 import java.util.List; 29 30 import sun.jvmstat.monitor.event.VmListener; 31 32 /** 33 * Interface for interacting with a monitorable Java Virtual Machine. 34 * The MonitoredVm interface provides methods for discovery of exported 35 * instrumentation, for attaching event listeners, and for overall 36 * maintenance of the connection to the target. 37 * 38 * @author Brian Doherty 39 * @since 1.5 40 */ 41 public interface MonitoredVm { 42 43 /** 44 * Get the VmIdentifier associated with this MonitoredVm 45 * 46 * @return VmIdentifier - the fully resolved Vm identifier associated 47 * with this MonitoredVm. 48 */ getVmIdentifier()49 VmIdentifier getVmIdentifier(); 50 51 /** 52 * Find a named Instrumentation object. 53 * 54 * This method will look for the named instrumentation object in the 55 * instrumentation exported by this Java Virtual Machine. If an 56 * instrumentation object with the given name exists, a Monitor interface 57 * to that object will be return. Otherwise, the method returns 58 * {@code null}. 59 * 60 * @param name the name of the Instrumentation object to find. 61 * @return Monitor - the {@link Monitor} object that can be used to 62 * monitor the named instrumentation object, or 63 * {@code null} if the named object doesn't exist. 64 * @throws MonitorException Thrown if an error occurs while communicating 65 * with the target Java Virtual Machine. 66 */ findByName(String name)67 Monitor findByName(String name) throws MonitorException; 68 69 /** 70 * Find all Instrumentation objects with names matching the given pattern. 71 * 72 * This method returns a {@link List} of Monitor objects such that 73 * the name of each object matches the given pattern. 74 * 75 * @param patternString a string containing a pattern as described in 76 * {@link java.util.regex.Pattern}. 77 * @return {@code List<Monitor>} - a List of {@link Monitor} 78 * objects that can be used to 79 * monitor the instrumentation objects whose names match 80 * the given pattern. If no instrumentation objects have 81 * names matching the given pattern, then an empty List 82 * is returned. 83 * @throws MonitorException Thrown if an error occurs while communicating 84 * with the target Java Virtual Machine. 85 * @see java.util.regex.Pattern 86 */ findByPattern(String patternString)87 List<Monitor> findByPattern(String patternString) throws MonitorException; 88 89 /** 90 * Detach from target Java Virtual Machine. 91 * 92 * After calling this method, updates of the instrumentation data values 93 * may be halted. All event notifications are halted. Further interactions 94 * with this object should be avoided. 95 */ detach()96 void detach(); 97 98 99 /* ---- Methods to support polled MonitoredVm Implementations ---- */ 100 101 /** 102 * Set the polling interval to {@code interval} milliseconds. 103 * 104 * Polling based monitoring implementations need to refresh the 105 * instrumentation data on a periodic basis. This interface allows 106 * the interval to override the implementation specific default 107 * interval. 108 * 109 * @param interval the polling interval in milliseconds 110 */ setInterval(int interval)111 void setInterval(int interval); 112 113 /** 114 * Get the polling interval. 115 * 116 * @return int - the current polling interval in milliseconds. 117 * @see #setInterval 118 */ getInterval()119 int getInterval(); 120 121 /** 122 * Set the last exception encountered while polling this MonitoredVm. 123 * 124 * Polling implementations may choose to poll asynchronously. This 125 * method allows an asynchronous task to communicate any polling related 126 * exceptions with the application. When an a non-null exception is reported 127 * through this interface, the MonitoredVm instance is considered to 128 * be in the <em>errored</em> state. 129 * 130 * @param cause the exception to record. 131 * @see #isErrored 132 */ setLastException(Exception cause)133 void setLastException(Exception cause); 134 135 /** 136 * Get the last exception encountered while polling this MonitoredVm. 137 * 138 * Returns the last exception observed by the implementation dependent 139 * polling task or {@code null} if no such error has occurred. 140 * 141 * @return Exception - the last exception that occurred during polling 142 * or {@code null} if no error condition exists. 143 * @see #isErrored 144 * @see #setLastException 145 */ getLastException()146 Exception getLastException(); 147 148 /** 149 * Clear the last exception. 150 * 151 * Calling this method will clear the <em>errored</em> state of this 152 * MonitoredVm. However, there is no guarantee that clearing the 153 * the errored state return the asynchronous polling task to an 154 * operational state. 155 * 156 */ clearLastException()157 void clearLastException(); 158 159 /** 160 * Test if this MonitoredVm is in the errored state. 161 * The errored state exists only if an error was reported with 162 * call to {@link #setLastException} and only if the parameter to 163 * that call was non-null and no subsequent calls are made to 164 * {@link #clearLastException}. 165 * 166 * @return boolean - true if the instance has a non-null error condition 167 * set, false otherwise. 168 * 169 * @see #setLastException 170 * @see #getLastException 171 */ isErrored()172 boolean isErrored(); 173 174 /** 175 * Add a VmListener. The given listener is added to the list of 176 * VmListener objects to be notified of MonitoredVm related events. 177 * 178 * @param listener the VmListener to add. 179 * @throws MonitorException Thrown if any problems occur while attempting 180 * to add this listener. 181 */ addVmListener(VmListener listener)182 void addVmListener(VmListener listener) throws MonitorException; 183 184 /** 185 * Remove a VmListener. The given listener is removed from the list of 186 * VmListener objects to be notified of MonitoredVm related events. 187 * 188 * @param listener the VmListener to be removed. 189 * @throws MonitorException Thrown if any problems occur while attempting 190 * to remove this listener. 191 */ removeVmListener(VmListener listener)192 void removeVmListener(VmListener listener) throws MonitorException; 193 } 194