Java example source code file (ScanManagerMXBean.java)

This example Java source code file (ScanManagerMXBean.java) is included in the alvinalexander.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Learn more about this Java project at its project page.

Java - Java tags/keywords

closed, completed, instancenotfoundexception, ioexception, jmexception, management, map, running, scandirconfigmxbean, scanmanagermxbean, scanstate, scheduled, stopped, string, util

The ScanManagerMXBean.java Java example source code

/*
 * Copyright (c) 2006, 2011, Oracle and/or its affiliates. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 *   - Redistributions of source code must retain the above copyright
 *     notice, this list of conditions and the following disclaimer.
 *
 *   - Redistributions in binary form must reproduce the above copyright
 *     notice, this list of conditions and the following disclaimer in the
 *     documentation and/or other materials provided with the distribution.
 *
 *   - Neither the name of Oracle nor the names of its
 *     contributors may be used to endorse or promote products derived
 *     from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
 * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

/*
 * This source code is provided to illustrate the usage of a given feature
 * or technique and has been deliberately simplified. Additional steps
 * required for a production-quality application, such as security checks,
 * input validation and proper error handling, might not be present in
 * this sample code.
 */


package com.sun.jmx.examples.scandir;

import java.io.IOException;
import java.util.Map;
import javax.management.InstanceNotFoundException;
import javax.management.JMException;

/**
 * The <code>ScanManagerMXBean is responsible for applying a
 * configuration, starting and scheduling directory scans, and reporting
 * application state.
 * <p>
 * The <code>ScanManagerMXBean is a singleton MBean: there can be
 * at most one instance of such an MBean registered in a given MBeanServer.
 * The name of that MBean is a constant defined in
 * {@link ScanManager#SCAN_MANAGER_NAME ScanManager.SCAN_MANAGER_NAME}.
 * </p>
 * <p>
 * The <code>ScanManagerMXBean is the entry point of the scandir
 * application management interface. It is from this MBean that all other
 * MBeans will be created and registered.
 * </p>
 *
 * @author Sun Microsystems, 2006 - All rights reserved.
 **/
public interface ScanManagerMXBean {
    /**
     * This state tells whether directory scans are running, scheduled,
     * successfully completed, or stopped.
     * <p>
     * The {@link #CLOSED} state means
     * that the {@link ScanManagerMXBean} was closed and is no longer usable.
     * This state is used when the {@link ScanManagerMXBean} needs to be
     * unregistered.
     * </p>
     **/
    public enum ScanState {
        /**
         * Scanning of directories is in process.
         **/
        RUNNING,

        /**
         * Scanning of directories is not in process, but is scheduled
         * for a later date.
         **/
        SCHEDULED,

        /**
         * Scanning is successfully completed.
         **/
        COMPLETED,

        /**
         * Scanning is stopped. No scanning is scheduled.
         **/
        STOPPED,

        /**
         * close() was called.
         **/
        CLOSED

    }

    /**
     * Returns the current state of the application.
     * @return the current state of the application.
     * @throws IOException A connection problem occurred when accessing
     *                     the underlying resource.
     * @throws InstanceNotFoundException The underlying MBean is not
     *         registered in the MBeanServer.
     **/
    public ScanState getState()
        throws IOException, InstanceNotFoundException;

    /**
     * Schedule a scan session for a later date.
     * <p>
     * A scan session is a background task that will sequentially call {@link
     * DirectoryScannerMXBean#scan scan()} on every {@link
     * DirectoryScannerMXBean} configured for this MBean.
     * </p>
     * @see #getDirectoryScanners
     * @param delay The first scan session will be started after
     *        the given delay. 0 means start now.
     * @param interval Scan session will be rescheduled periodically
     *        at the specified interval. The interval starts at the
     *        the end of the scan session: if a scan session takes
     *        on average x milliseconds to complete, then a scan session will
     *        be started on average every x+interval milliseconds.
     *        if (interval == 0) then scan session will not be
     *        rescheduled, and will run only once.
     * @throws IllegalStateException if a scan session is already
     *         running or scheduled, or the MBean is closed.
     * @throws IOException A connection problem occurred when accessing
     *                     the underlying resource.
     * @throws InstanceNotFoundException The underlying MBean is not
     *         registered in the MBeanServer.
     **/
    public void schedule(long delay, long interval)
        throws IOException, InstanceNotFoundException;


    /**
     * Stops current running or scheduled scan sessions if any.
     * <p>
     * A scan session is a background task that will sequentially call {@link
     * DirectoryScannerMXBean#scan scan()} on every {@link
     * DirectoryScannerMXBean} configured for this MBean.
     * </p>
     * <p>
     * Scan sessions are started/scheduled by calls to {@link #start start} or
     * {@link #schedule schedule}.
     * </p>
     * After this method completes the state of the application will
     * be {@link ScanState#STOPPED}.
     * @throws IOException A connection problem occurred when accessing
     *                     the underlying resource.
     * @throws InstanceNotFoundException The underlying MBean is not
     *         registered in the MBeanServer.
     **/
    public void stop()
        throws IOException, InstanceNotFoundException;

    /**
     * Switches the state to CLOSED.
     * When closed, this MBean cannot be used any more.
     * @throws IOException A connection problem occurred when accessing
     *                     the underlying resource.
     * @throws InstanceNotFoundException The underlying MBean is not
     *         registered in the MBeanServer.
     **/
    public void close()
        throws IOException, InstanceNotFoundException;

    /**
     * Starts a scan session immediately.
     * This is equivalent to {@link #schedule(long,long) schedule(0,0)}.
     * @throws IllegalStateException if a scan session is already
     *         running or scheduled, or the MBean is closed.
     * @throws IOException A connection problem occurred when accessing
     *                     the underlying resource.
     * @throws InstanceNotFoundException The underlying MBean is not
     *         registered in the MBeanServer.
     **/
    public void start()
        throws IOException, InstanceNotFoundException;

    /**
     * Gets the list of directory scanners configured for this MBean.
     * @return A {@code Map<String,DirectoryScannerMXBean>} where the
     *         key in the map is the value of the <code>name= key
     *         of the {@link DirectoryScannerMXBean} ObjectName.
     * @throws IOException A connection problem occurred when accessing
     *                     the underlying resource.
     * @throws JMException The MBeanServer failed to call the underlying MBean.
     **/
    public Map<String,DirectoryScannerMXBean> getDirectoryScanners()
        throws IOException, JMException;

    /**
     * Apply the configuration handled by the {@link
     * #getConfigurationMBean configuration MBean}.
     * <p>
     * When the configuration is applied, all the {@link DirectoryScannerMXBean}
     * created by this MBean will be unregistered, and new {@link
     * DirectoryScannerMXBean} will be created and registered from the
     * new {@link ScanDirConfigMXBean#getConfiguration configuration data}.
     * </p>
     * <p>
     * The initial result log configuration held by the {@link
     * #getConfigurationMBean configuration MBean} will also be pushed to the
     * {@link ResultLogManagerMXBean}. If you don't want to lose your current
     * {@link ResultLogManagerMXBean} configuration, you should therefore call
     * {@link #applyCurrentResultLogConfig
     * applyCurrentResultLogConfig} before calling
     * {@link #applyConfiguration applyConfiguration}
     * </p>
     * @param fromMemory if {@code true}, the configuration will be applied
     *        from memory. if {@code false}, the {@code ScanManagerMXBean} will
     *        ask the {@link
     * #getConfigurationMBean configuration MBean} to {@link
     * ScanDirConfigMXBean#load reload its configuration} before applying
     * it.
     * @throws IllegalStateException if a scan session is
     *         running or scheduled, or the MBean is closed.
     * @throws IOException A connection problem occurred when accessing
     *                     the underlying resource.
     * @throws JMException The MBeanServer failed to call the underlying MBean.
     **/
    public void applyConfiguration(boolean fromMemory)
        throws IOException, JMException;
    /**
     * Replaces the {@link
     * #getConfigurationMBean configuration MBean}'s {@link
     * com.sun.jmx.examples.scandir.config.ScanManagerConfig#getInitialResultLogConfig
     * initial result log configuration} with the current {@link
     * ResultLogManagerMXBean}
     * configuration. This prevents the <code>ResultLogManagerMXBean
     * current configuration from being reset when {@link #applyConfiguration
     * applyConfiguration} is called.
     * @param toMemory if {@code true} only replaces the initial result log
     *                 configuration held in memory.
     *                 if {@code false}, the {@link
     * #getConfigurationMBean configuration MBean} will be asked to commit
     * the whole configuration to the configuration file.
     *
     * @throws IOException A connection problem occurred when accessing
     *                     the underlying resource.
     * @throws JMException The MBeanServer failed to call the underlying MBean.
     **/
    public void applyCurrentResultLogConfig(boolean toMemory)
        throws IOException, JMException;

    /**
     * Instruct the {@code ScanManagerMXBean} to use another {@link
     * ScanDirConfigMXBean configuration MBean}.
     * <p>This method doesn't {@link #applyConfiguration apply} the new
     * configuration. If you want to apply the new configuration, you should
     * additionally call {@link #applyConfiguration
     * applyConfiguration(true|false)}. Note that you cannot apply a
     * configuration as long as a scan session is scheduled or running.
     * In that case you will need to wait for that session to complete
     * or call {@link #stop} to stop it.
     * </p>
     * @param config A proxy to the {@link ScanDirConfigMXBean} that holds
     * the new configuration for the application.
     * @throws IOException A connection problem occurred when accessing
     *                     the underlying resource.
     * @throws InstanceNotFoundException The underlying MBean is not
     *         registered in the MBeanServer.
     */
    public void setConfigurationMBean(ScanDirConfigMXBean config)
        throws IOException, InstanceNotFoundException;
    /**
     * Gets the current configuration MBean.
     * @return A proxy to the current configuration MBean.
     * @throws IOException A connection problem occurred when accessing
     *                     the underlying resource.
     * @throws InstanceNotFoundException The underlying MBean is not
     *         registered in the MBeanServer.
     **/
    public ScanDirConfigMXBean getConfigurationMBean()
        throws IOException, InstanceNotFoundException;
    /**
     * This method creates a new alternate {@link ScanDirConfigMXBean}.
     *
     * <p>You will need to call {@link #setConfigurationMBean
     * setConfigurationMBean} if you
     * want this new {@link ScanDirConfigMXBean} to become the
     * current configuration MBean.
     * </p>
     * <p>
     * This new {@link ScanDirConfigMXBean} will be unregistered automatically
     * by the {@code ScanManagerMXBean} when the {@code ScanManagerMXBean}
     * is unregistered.
     * </p>
     * @param name The short name for the new {@link ScanDirConfigMXBean}.
     *        This name will be used in the ObjectName <code>name= key
     *        of the new {@link ScanDirConfigMXBean}.
     * @param filename The path of the file from which the new {@link
     *        ScanDirConfigMXBean} can {@link ScanDirConfigMXBean#load load} or
     *        {@link ScanDirConfigMXBean#save save} its configuration data.
     *        Note that even if the file exists and contain a valid
     *        configuration, you will still need to call {@link
     *        ScanDirConfigMXBean#load load} to make the {@link
     *        ScanDirConfigMXBean} load its configuration data.
     * @throws IOException A connection problem occurred when accessing
     *                     the underlying resource.
     * @throws JMException The MBeanServer failed to call the underlying MBean.
     * @return A proxy to the created {@link ScanDirConfigMXBean}.
     */
    public ScanDirConfigMXBean createOtherConfigurationMBean(String name,
            String filename)
        throws JMException, IOException;
}