001: /*
002: * Copyright 2004 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package sun.jvmstat.monitor;
027:
028: import java.util.List;
029:
030: import sun.jvmstat.monitor.event.VmListener;
031:
032: /**
033: * Interface for interacting with a monitorable Java Virtual Machine.
034: * The MonitoredVm interface provides methods for discovery of exported
035: * instrumentation, for attaching event listeners, and for overall
036: * maintenance of the connection to the target.
037: *
038: * @author Brian Doherty
039: * @version 1.9, 05/09/07
040: * @since 1.5
041: */
042: public interface MonitoredVm {
043:
044: /**
045: * Get the VmIdentifier associated with this MonitoredVm
046: *
047: * @return VmIdentifier - the fully resolved Vm identifier associated
048: * with this MonitoredVm.
049: */
050: VmIdentifier getVmIdentifier();
051:
052: /**
053: * Find a named Instrumentation object.
054: *
055: * This method will look for the named instrumentation object in the
056: * instrumentation exported by this Java Virtual Machine. If an
057: * instrumentation object with the given name exists, a Monitor interface
058: * to that object will be return. Otherwise, the method returns
059: * <tt>null</tt>.
060: *
061: * @param name the name of the Instrumentation object to find.
062: * @return Monitor - the {@link Monitor} object that can be used to
063: * monitor the the named instrumentation object, or
064: * <tt>null</tt> if the named object doesn't exist.
065: * @throws MonitorException Thrown if an error occurs while communicating
066: * with the target Java Virtual Machine.
067: */
068: Monitor findByName(String name) throws MonitorException;
069:
070: /**
071: * Find all Instrumentation objects with names matching the given pattern.
072: *
073: * This method returns a {@link List} of Monitor objects such that
074: * the name of each object matches the given pattern.
075: *
076: * @param patternString a string containing a pattern as described in
077: * {@link java.util.regex.Pattern}.
078: * @return List<Monitor> - a List of {@link Monitor} objects that can be used to
079: * monitor the instrumentation objects whose names match
080: * the given pattern. If no instrumentation objects have`
081: * names matching the given pattern, then an empty List
082: * is returned.
083: * @throws MonitorException Thrown if an error occurs while communicating
084: * with the target Java Virtual Machine.
085: * @see java.util.regex.Pattern
086: */
087: List<Monitor> findByPattern(String patternString)
088: throws MonitorException;
089:
090: /**
091: * Detach from target Java Virtual Machine.
092: *
093: * After calling this method, updates of the instrumentation data values
094: * may be halted. All event notifications are halted. Further interactions
095: * with this object should be avoided.
096: */
097: void detach();
098:
099: /* ---- Methods to support polled MonitoredVm Implementations ---- */
100:
101: /**
102: * Set the polling interval to <code>interval</code> 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: */
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: */
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: */
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 <tt>null</tt> if no such error has occurred.
140: *
141: * @return Exception - the last exception that occurred during polling
142: * or <tt>null</tt> if no error condition exists.
143: * @see #isErrored
144: * @see #setLastException
145: */
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: */
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: */
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: */
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: */
192: void removeVmListener(VmListener listener) throws MonitorException;
193: }
|