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
26package sun.jvmstat.monitor;
27
28import java.util.List;
29
30import 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 */
41public 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     * {@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     */
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} 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 {@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     */
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}
194