/*
 * 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
     *                   monitor the the named instrumentation object, or
     *                   <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;
}