View Javadoc
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 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 }