1 /* 2 * Copyright (c) 2006, 2011, Oracle and/or its affiliates. All rights reserved. 3 * 4 * Redistribution and use in source and binary forms, with or without 5 * modification, are permitted provided that the following conditions 6 * are met: 7 * 8 * - Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer. 10 * 11 * - Redistributions in binary form must reproduce the above copyright 12 * notice, this list of conditions and the following disclaimer in the 13 * documentation and/or other materials provided with the distribution. 14 * 15 * - Neither the name of Oracle nor the names of its 16 * contributors may be used to endorse or promote products derived 17 * from this software without specific prior written permission. 18 * 19 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS 20 * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 21 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 22 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 23 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 24 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 25 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 26 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 27 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 28 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 29 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30 */ 31 32 /* 33 * This source code is provided to illustrate the usage of a given feature 34 * or technique and has been deliberately simplified. Additional steps 35 * required for a production-quality application, such as security checks, 36 * input validation and proper error handling, might not be present in 37 * this sample code. 38 */ 39 40 41 package com.sun.jmx.examples.scandir; 42 43 import java.io.IOException; 44 import java.util.Map; 45 import javax.management.InstanceNotFoundException; 46 import javax.management.JMException; 47 48 /** 49 * The <code>ScanManagerMXBean</code> is responsible for applying a 50 * configuration, starting and scheduling directory scans, and reporting 51 * application state. 52 * <p> 53 * The <code>ScanManagerMXBean</code> is a singleton MBean: there can be 54 * at most one instance of such an MBean registered in a given MBeanServer. 55 * The name of that MBean is a constant defined in 56 * {@link ScanManager#SCAN_MANAGER_NAME ScanManager.SCAN_MANAGER_NAME}. 57 * </p> 58 * <p> 59 * The <code>ScanManagerMXBean</code> is the entry point of the <i>scandir</i> 60 * application management interface. It is from this MBean that all other 61 * MBeans will be created and registered. 62 * </p> 63 * 64 * @author Sun Microsystems, 2006 - All rights reserved. 65 **/ 66 public interface ScanManagerMXBean { 67 /** 68 * This state tells whether directory scans are running, scheduled, 69 * successfully completed, or stopped. 70 * <p> 71 * The {@link #CLOSED} state means 72 * that the {@link ScanManagerMXBean} was closed and is no longer usable. 73 * This state is used when the {@link ScanManagerMXBean} needs to be 74 * unregistered. 75 * </p> 76 **/ 77 public enum ScanState { 78 /** 79 * Scanning of directories is in process. 80 **/ 81 RUNNING, 82 83 /** 84 * Scanning of directories is not in process, but is scheduled 85 * for a later date. 86 **/ 87 SCHEDULED, 88 89 /** 90 * Scanning is successfully completed. 91 **/ 92 COMPLETED, 93 94 /** 95 * Scanning is stopped. No scanning is scheduled. 96 **/ 97 STOPPED, 98 99 /** 100 * close() was called. 101 **/ 102 CLOSED 103 104 } 105 106 /** 107 * Returns the current state of the application. 108 * @return the current state of the application. 109 * @throws IOException A connection problem occurred when accessing 110 * the underlying resource. 111 * @throws InstanceNotFoundException The underlying MBean is not 112 * registered in the MBeanServer. 113 **/ getState()114 public ScanState getState() 115 throws IOException, InstanceNotFoundException; 116 117 /** 118 * Schedule a scan session for a later date. 119 * <p> 120 * A scan session is a background task that will sequentially call {@link 121 * DirectoryScannerMXBean#scan scan()} on every {@link 122 * DirectoryScannerMXBean} configured for this MBean. 123 * </p> 124 * @see #getDirectoryScanners 125 * @param delay The first scan session will be started after 126 * the given delay. 0 means start now. 127 * @param interval Scan session will be rescheduled periodically 128 * at the specified interval. The interval starts at the 129 * the end of the scan session: if a scan session takes 130 * on average x milliseconds to complete, then a scan session will 131 * be started on average every x+interval milliseconds. 132 * if (interval == 0) then scan session will not be 133 * rescheduled, and will run only once. 134 * @throws IllegalStateException if a scan session is already 135 * running or scheduled, or the MBean is closed. 136 * @throws IOException A connection problem occurred when accessing 137 * the underlying resource. 138 * @throws InstanceNotFoundException The underlying MBean is not 139 * registered in the MBeanServer. 140 **/ schedule(long delay, long interval)141 public void schedule(long delay, long interval) 142 throws IOException, InstanceNotFoundException; 143 144 145 /** 146 * Stops current running or scheduled scan sessions if any. 147 * <p> 148 * A scan session is a background task that will sequentially call {@link 149 * DirectoryScannerMXBean#scan scan()} on every {@link 150 * DirectoryScannerMXBean} configured for this MBean. 151 * </p> 152 * <p> 153 * Scan sessions are started/scheduled by calls to {@link #start start} or 154 * {@link #schedule schedule}. 155 * </p> 156 * After this method completes the state of the application will 157 * be {@link ScanState#STOPPED}. 158 * @throws IOException A connection problem occurred when accessing 159 * the underlying resource. 160 * @throws InstanceNotFoundException The underlying MBean is not 161 * registered in the MBeanServer. 162 **/ stop()163 public void stop() 164 throws IOException, InstanceNotFoundException; 165 166 /** 167 * Switches the state to CLOSED. 168 * When closed, this MBean cannot be used any more. 169 * @throws IOException A connection problem occurred when accessing 170 * the underlying resource. 171 * @throws InstanceNotFoundException The underlying MBean is not 172 * registered in the MBeanServer. 173 **/ close()174 public void close() 175 throws IOException, InstanceNotFoundException; 176 177 /** 178 * Starts a scan session immediately. 179 * This is equivalent to {@link #schedule(long,long) schedule(0,0)}. 180 * @throws IllegalStateException if a scan session is already 181 * running or scheduled, or the MBean is closed. 182 * @throws IOException A connection problem occurred when accessing 183 * the underlying resource. 184 * @throws InstanceNotFoundException The underlying MBean is not 185 * registered in the MBeanServer. 186 **/ start()187 public void start() 188 throws IOException, InstanceNotFoundException; 189 190 /** 191 * Gets the list of directory scanners configured for this MBean. 192 * @return A {@code Map<String,DirectoryScannerMXBean>} where the 193 * key in the map is the value of the <code>name=</code> key 194 * of the {@link DirectoryScannerMXBean} ObjectName. 195 * @throws IOException A connection problem occurred when accessing 196 * the underlying resource. 197 * @throws JMException The MBeanServer failed to call the underlying MBean. 198 **/ getDirectoryScanners()199 public Map<String,DirectoryScannerMXBean> getDirectoryScanners() 200 throws IOException, JMException; 201 202 /** 203 * Apply the configuration handled by the {@link 204 * #getConfigurationMBean configuration MBean}. 205 * <p> 206 * When the configuration is applied, all the {@link DirectoryScannerMXBean} 207 * created by this MBean will be unregistered, and new {@link 208 * DirectoryScannerMXBean} will be created and registered from the 209 * new {@link ScanDirConfigMXBean#getConfiguration configuration data}. 210 * </p> 211 * <p> 212 * The initial result log configuration held by the {@link 213 * #getConfigurationMBean configuration MBean} will also be pushed to the 214 * {@link ResultLogManagerMXBean}. If you don't want to lose your current 215 * {@link ResultLogManagerMXBean} configuration, you should therefore call 216 * {@link #applyCurrentResultLogConfig 217 * applyCurrentResultLogConfig} before calling 218 * {@link #applyConfiguration applyConfiguration} 219 * </p> 220 * @param fromMemory if {@code true}, the configuration will be applied 221 * from memory. if {@code false}, the {@code ScanManagerMXBean} will 222 * ask the {@link 223 * #getConfigurationMBean configuration MBean} to {@link 224 * ScanDirConfigMXBean#load reload its configuration} before applying 225 * it. 226 * @throws IllegalStateException if a scan session is 227 * running or scheduled, or the MBean is closed. 228 * @throws IOException A connection problem occurred when accessing 229 * the underlying resource. 230 * @throws JMException The MBeanServer failed to call the underlying MBean. 231 **/ applyConfiguration(boolean fromMemory)232 public void applyConfiguration(boolean fromMemory) 233 throws IOException, JMException; 234 /** 235 * Replaces the {@link 236 * #getConfigurationMBean configuration MBean}'s {@link 237 * com.sun.jmx.examples.scandir.config.ScanManagerConfig#getInitialResultLogConfig 238 * initial result log configuration} with the current {@link 239 * ResultLogManagerMXBean} 240 * configuration. This prevents the <code>ResultLogManagerMXBean</code> 241 * current configuration from being reset when {@link #applyConfiguration 242 * applyConfiguration} is called. 243 * @param toMemory if {@code true} only replaces the initial result log 244 * configuration held in memory. 245 * if {@code false}, the {@link 246 * #getConfigurationMBean configuration MBean} will be asked to commit 247 * the whole configuration to the configuration file. 248 * 249 * @throws IOException A connection problem occurred when accessing 250 * the underlying resource. 251 * @throws JMException The MBeanServer failed to call the underlying MBean. 252 **/ applyCurrentResultLogConfig(boolean toMemory)253 public void applyCurrentResultLogConfig(boolean toMemory) 254 throws IOException, JMException; 255 256 /** 257 * Instruct the {@code ScanManagerMXBean} to use another {@link 258 * ScanDirConfigMXBean configuration MBean}. 259 * <p>This method doesn't {@link #applyConfiguration apply} the new 260 * configuration. If you want to apply the new configuration, you should 261 * additionally call {@link #applyConfiguration 262 * applyConfiguration(true|false)}. Note that you cannot apply a 263 * configuration as long as a scan session is scheduled or running. 264 * In that case you will need to wait for that session to complete 265 * or call {@link #stop} to stop it. 266 * </p> 267 * @param config A proxy to the {@link ScanDirConfigMXBean} that holds 268 * the new configuration for the application. 269 * @throws IOException A connection problem occurred when accessing 270 * the underlying resource. 271 * @throws InstanceNotFoundException The underlying MBean is not 272 * registered in the MBeanServer. 273 */ setConfigurationMBean(ScanDirConfigMXBean config)274 public void setConfigurationMBean(ScanDirConfigMXBean config) 275 throws IOException, InstanceNotFoundException; 276 /** 277 * Gets the current configuration MBean. 278 * @return A proxy to the current configuration MBean. 279 * @throws IOException A connection problem occurred when accessing 280 * the underlying resource. 281 * @throws InstanceNotFoundException The underlying MBean is not 282 * registered in the MBeanServer. 283 **/ getConfigurationMBean()284 public ScanDirConfigMXBean getConfigurationMBean() 285 throws IOException, InstanceNotFoundException; 286 /** 287 * This method creates a new alternate {@link ScanDirConfigMXBean}. 288 * 289 * <p>You will need to call {@link #setConfigurationMBean 290 * setConfigurationMBean} if you 291 * want this new {@link ScanDirConfigMXBean} to become the 292 * current configuration MBean. 293 * </p> 294 * <p> 295 * This new {@link ScanDirConfigMXBean} will be unregistered automatically 296 * by the {@code ScanManagerMXBean} when the {@code ScanManagerMXBean} 297 * is unregistered. 298 * </p> 299 * @param name The short name for the new {@link ScanDirConfigMXBean}. 300 * This name will be used in the ObjectName <code>name=</code> key 301 * of the new {@link ScanDirConfigMXBean}. 302 * @param filename The path of the file from which the new {@link 303 * ScanDirConfigMXBean} can {@link ScanDirConfigMXBean#load load} or 304 * {@link ScanDirConfigMXBean#save save} its configuration data. 305 * Note that even if the file exists and contain a valid 306 * configuration, you will still need to call {@link 307 * ScanDirConfigMXBean#load load} to make the {@link 308 * ScanDirConfigMXBean} load its configuration data. 309 * @throws IOException A connection problem occurred when accessing 310 * the underlying resource. 311 * @throws JMException The MBeanServer failed to call the underlying MBean. 312 * @return A proxy to the created {@link ScanDirConfigMXBean}. 313 */ createOtherConfigurationMBean(String name, String filename)314 public ScanDirConfigMXBean createOtherConfigurationMBean(String name, 315 String filename) 316 throws JMException, IOException; 317 } 318