/*
* 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</code> is responsible for applying a
* configuration, starting and scheduling directory scans, and reporting
* application state.
* <p>
* The <code>ScanManagerMXBean</code> 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</code> is the entry point of the <i>scandir</i>
* 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=</code> 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</code>
* 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=</code> 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;
}