/*

 * Copyright (c) 2004, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package sun.jvmstat.monitor;

import java.util.List;

import sun.jvmstat.monitor.event.VmListener;

/**

 * Interface for interacting with a monitorable Java Virtual Machine.

 * The MonitoredVm interface provides methods for discovery of exported

 * instrumentation, for attaching event listeners, and for overall

 * maintenance of the connection to the target.

 *

 * @author Brian Doherty

 * @since 1.5

 */

public interface MonitoredVm {

    /**

     * Get the VmIdentifier associated with this MonitoredVm

     *

     * @return VmIdentifier - the fully resolved Vm identifier associated

     *                        with this MonitoredVm.

     */

    VmIdentifier getVmIdentifier();

    /**

     * Find a named Instrumentation object.

     *

     * This method will look for the named instrumentation object in the

     * instrumentation exported by this Java Virtual Machine. If an

     * instrumentation object with the given name exists, a Monitor interface

     * to that object will be return. Otherwise, the method returns

     * <tt>null</tt>.

     *

     * @param name the name of the Instrumentation object to find.

     * @return Monitor - the {@link Monitor} object that can be used to

     *                   <tt>null</tt> if the named object doesn't exist.

     * @throws MonitorException Thrown if an error occurs while communicating

     *                          with the target Java Virtual Machine.

     */

    Monitor findByName(String name) throws MonitorException;

    /**

     * Find all Instrumentation objects with names matching the given pattern.

     *

     * This method returns a {@link List} of Monitor objects such that

     * the name of each object matches the given pattern.

     *

     * @param patternString a string containing a pattern as described in

     *                      {@link java.util.regex.Pattern}.

     * @return List<Monitor> - a List of {@link Monitor} objects that can be used to

     *                monitor the instrumentation objects whose names match

     *                the given pattern. If no instrumentation objects have`

     *                names matching the given pattern, then an empty List

     *                is returned.

     * @throws MonitorException Thrown if an error occurs while communicating

     *                          with the target Java Virtual Machine.

     * @see java.util.regex.Pattern

     */

    List<Monitor> findByPattern(String patternString) throws MonitorException;

    /**

     * Detach from target Java Virtual Machine.

     *

     * After calling this method, updates of the instrumentation data values

     * may be halted. All event notifications are halted. Further interactions

     * with this object should be avoided.

     */

    void detach();

    /* ---- Methods to support polled MonitoredVm Implementations ---- */

    /**

     * Set the polling interval to <code>interval</code> milliseconds.

     *

     * Polling based monitoring implementations need to refresh the

     * instrumentation data on a periodic basis. This interface allows

     * the interval to override the implementation specific default

     * interval.

     *

     * @param interval the polling interval in milliseconds

     */

    void setInterval(int interval);

    /**

     * Get the polling interval.

     *

     * @return int - the current polling interval in milliseconds.

     * @see #setInterval

     */

    int getInterval();

    /**

     * Set the last exception encountered while polling this MonitoredVm.

     *

     * Polling implementations may choose to poll asynchronously. This

     * method allows an asynchronous task to communicate any polling related

     * exceptions with the application. When an a non-null exception is reported

     * through this interface, the MonitoredVm instance is considered to

     * be in the <em>errored</em> state.

     *

     * @param cause the exception to record.

     * @see #isErrored

     */

    void setLastException(Exception cause);

    /**

     * Get the last exception encountered while polling this MonitoredVm.

     *

     * Returns the last exception observed by the implementation dependent

     * polling task or <tt>null</tt> if no such error has occurred.

     *

     * @return Exception - the last exception that occurred during polling

     *                     or <tt>null</tt> if no error condition exists.

     * @see #isErrored

     * @see #setLastException

     */

    Exception getLastException();

    /**

     * Clear the last exception.

     *

     * Calling this method will clear the <em>errored</em> state of this

     * MonitoredVm. However, there is no guarantee that clearing the

     * the errored state return the asynchronous polling task to an

     * operational state.

     *

     */

    void clearLastException();

    /**

     * Test if this MonitoredVm is in the errored state.

     * The errored state exists only if an error was reported with

     * call to {@link #setLastException} and only if the parameter to

     * that call was non-null and no subsequent calls are made to

     * {@link #clearLastException}.

     *

     * @return boolean - true if the instance has a non-null error condition

     *                   set, false otherwise.

     *

     * @see #setLastException

     * @see #getLastException

     */

    boolean isErrored();

    /**

     * Add a VmListener. The given listener is added to the list of

     * VmListener objects to be notified of MonitoredVm related events.

     *

     * @param listener the VmListener to add.

     * @throws MonitorException Thrown if any problems occur while attempting

     *                          to add this listener.

     */

    void addVmListener(VmListener listener) throws MonitorException;

    /**

     * Remove a VmListener. The given listener is removed from the list of

     * VmListener objects to be notified of MonitoredVm related events.

     *

     * @param listener the VmListener to be removed.

     * @throws MonitorException Thrown if any problems occur while attempting

     *                            to remove this listener.

     */

    void removeVmListener(VmListener listener) throws MonitorException;

}