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 {@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 */
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 */
96 void detach();
97
98
99 /* ---- 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 }