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 */
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 * <tt>null</tt>.
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 * <tt>null</tt> 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 */
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 List<Monitor> - a List of {@link Monitor} objects that can be used to
78 * monitor the instrumentation objects whose names match
79 * the given pattern. If no instrumentation objects have`
80 * names matching the given pattern, then an empty List
81 * is returned.
82 * @throws MonitorException Thrown if an error occurs while communicating
83 * with the target Java Virtual Machine.
84 * @see java.util.regex.Pattern
85 */
86 List<Monitor> findByPattern(String patternString) throws MonitorException;
87
88 /**
89 * Detach from target Java Virtual Machine.
90 *
91 * After calling this method, updates of the instrumentation data values
92 * may be halted. All event notifications are halted. Further interactions
93 * with this object should be avoided.
94 */
95 void detach();
96
97
98 /* ---- Methods to support polled MonitoredVm Implementations ---- */
99
100 /**
101 * Set the polling interval to <code>interval</code> milliseconds.
102 *
103 * Polling based monitoring implementations need to refresh the
104 * instrumentation data on a periodic basis. This interface allows
105 * the interval to override the implementation specific default
106 * interval.
107 *
108 * @param interval the polling interval in milliseconds
109 */
110 void setInterval(int interval);
111
112 /**
113 * Get the polling interval.
114 *
115 * @return int - the current polling interval in milliseconds.
116 * @see #setInterval
117 */
118 int getInterval();
119
120 /**
121 * Set the last exception encountered while polling this MonitoredVm.
122 *
123 * Polling implementations may choose to poll asynchronously. This
124 * method allows an asynchronous task to communicate any polling related
125 * exceptions with the application. When an a non-null exception is reported
126 * through this interface, the MonitoredVm instance is considered to
127 * be in the <em>errored</em> state.
128 *
129 * @param cause the exception to record.
130 * @see #isErrored
131 */
132 void setLastException(Exception cause);
133
134 /**
135 * Get the last exception encountered while polling this MonitoredVm.
136 *
137 * Returns the last exception observed by the implementation dependent
138 * polling task or <tt>null</tt> if no such error has occurred.
139 *
140 * @return Exception - the last exception that occurred during polling
141 * or <tt>null</tt> if no error condition exists.
142 * @see #isErrored
143 * @see #setLastException
144 */
145 Exception getLastException();
146
147 /**
148 * Clear the last exception.
149 *
150 * Calling this method will clear the <em>errored</em> state of this
151 * MonitoredVm. However, there is no guarantee that clearing the
152 * the errored state return the asynchronous polling task to an
153 * operational state.
154 *
155 */
156 void clearLastException();
157
158 /**
159 * Test if this MonitoredVm is in the errored state.
160 * The errored state exists only if an error was reported with
161 * call to {@link #setLastException} and only if the parameter to
162 * that call was non-null and no subsequent calls are made to
163 * {@link #clearLastException}.
164 *
165 * @return boolean - true if the instance has a non-null error condition
166 * set, false otherwise.
167 *
168 * @see #setLastException
169 * @see #getLastException
170 */
171 boolean isErrored();
172
173 /**
174 * Add a VmListener. The given listener is added to the list of
175 * VmListener objects to be notified of MonitoredVm related events.
176 *
177 * @param listener the VmListener to add.
178 * @throws MonitorException Thrown if any problems occur while attempting
179 * to add this listener.
180 */
181 void addVmListener(VmListener listener) throws MonitorException;
182
183 /**
184 * Remove a VmListener. The given listener is removed from the list of
185 * VmListener objects to be notified of MonitoredVm related events.
186 *
187 * @param listener the VmListener to be removed.
188 * @throws MonitorException Thrown if any problems occur while attempting
189 * to remove this listener.
190 */
191 void removeVmListener(VmListener listener) throws MonitorException;
192 }