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 com.sun.jmx.examples.scandir.config.DirectoryScannerConfig; 44 import com.sun.jmx.examples.scandir.config.ScanManagerConfig; 45 import java.io.IOException; 46 import javax.management.InstanceNotFoundException; 47 48 /** 49 * <p>The <code>ScanDirConfigMXBean</code> is in charge of the 50 * <i>scandir</i> application configuration. 51 * </p> 52 * <p>The <code>ScanDirConfigMXBean</code> is an MBean which is able to 53 * load and save the <i>scandir</i> application configuration to and from an 54 * XML file. 55 * </p> 56 * <p> 57 * It will let you also interactively modify that configuration, which you 58 * can later save to the file, by calling {@link #save}, or discard, by 59 * reloading the file without saving - see {@link #load}. 60 * </p> 61 * <p> 62 * There can be as many <code>ScanDirConfigMXBean</code> registered 63 * in the MBeanServer as you like, but only one of them will be identified as 64 * the current configuration of the {@link ScanManagerMXBean}. 65 * You can switch to another configuration by calling {@link 66 * ScanManagerMXBean#setConfigurationMBean 67 * ScanManagerMXBean.setConfigurationMBean}. 68 * </p> 69 * <p> 70 * Once the current configuration has been loaded (by calling {@link #load}) 71 * or modified (by calling one of {@link #addDirectoryScanner 72 * addDirectoryScanner}, {@link #removeDirectoryScanner removeDirectoryScanner} 73 * or {@link #setConfiguration setConfiguration}) it can be pushed 74 * to the {@link ScanManagerMXBean} by calling {@link 75 * ScanManagerMXBean#applyConfiguration 76 * ScanManagerMXBean.applyConfiguration(true)} - 77 * <code>true</code> means that we apply the configuration from memory, 78 * without first reloading the file. 79 * </p> 80 * 81 * @author Sun Microsystems, 2006 - All rights reserved. 82 */ 83 public interface ScanDirConfigMXBean { 84 /** 85 * This state tells whether the configuration reflected by the 86 * {@link ScanDirConfigMXBean} was loaded in memory, saved to the 87 * configuration file, or modified since last saved. 88 * Note that this state doesn't tell whether the configuration was 89 * applied by the {@link ScanManagerMXBean}. 90 **/ 91 public enum SaveState { 92 /** 93 * Initial state: the {@link ScanDirConfigMXBean} is created, but 94 * neither {@link #load} or {@link #save} was yet called. 95 **/ 96 CREATED, 97 98 /** 99 * The configuration reflected by the {@link ScanDirConfigMXBean} has 100 * been loaded, but not modified yet. 101 **/ 102 LOADED, 103 104 /** 105 * The configuration was modified. The modifications are held in memory. 106 * Call {@link #save} to save them to the file, or {@link #load} to 107 * reload the file and discard them. 108 **/ 109 MODIFIED, 110 111 /** 112 * The configuration was saved. 113 **/ 114 SAVED 115 }; 116 117 /** 118 * Loads the configuration from the {@link 119 * #getConfigFilename configuration file}. 120 * <p>Any unsaved modification will be lost. The {@link #getSaveState state} 121 * is switched to {@link SaveState#LOADED LOADED}. 122 * </p> 123 * <p> 124 * This action has no effect on the {@link ScanManagerMXBean} until 125 * {@link ScanManagerMXBean#getConfigurationMBean ScanManagerMXBean} 126 * points to this MBean and {@link ScanManagerMXBean#applyConfiguration 127 * ScanManagerMXBean.applyConfiguration} is called. 128 * </p> 129 * @see #getSaveState() 130 * @throws IOException The configuration couldn't be loaded from the file, 131 * e.g. because the file doesn't exist or isn't 132 * readable. 133 * @throws IOException A connection problem occurred when accessing 134 * the underlying resource. 135 * @throws InstanceNotFoundException The underlying MBean is not 136 * registered in the MBeanServer. 137 **/ load()138 public void load() 139 throws IOException, InstanceNotFoundException; 140 141 /** 142 * Saves the configuration to the {@link 143 * #getConfigFilename configuration file}. 144 * 145 * <p>If the configuration file doesn't exists, this method will 146 * attempt to create it. Otherwise, the existing file will 147 * be renamed by appending a '~' to its name, and a new file 148 * will be created, in which the configuration will be saved. 149 * The {@link #getSaveState state} 150 * is switched to {@link SaveState#SAVED SAVED}. 151 * </p> 152 * <p> 153 * This action has no effect on the {@link ScanManagerMXBean}. 154 * </p> 155 * @see #getSaveState() 156 * 157 * @throws IOException The configuration couldn't be saved to the file, 158 * e.g. because the file couldn't be created. 159 * @throws IOException A connection problem occurred when accessing 160 * the underlying resource. 161 * @throws InstanceNotFoundException The underlying MBean is not 162 * registered in the MBeanServer. 163 **/ save()164 public void save() 165 throws IOException, InstanceNotFoundException; 166 167 /** 168 * Gets the name of the configuration file. 169 * <p>If the configuration file doesn't exists, {@link #load} will fail 170 * and {@link #save} will attempt to create the file. 171 * </p> 172 * 173 * @return The configuration file name for this MBean. 174 * @throws IOException A connection problem occurred when accessing 175 * the underlying resource. 176 * @throws InstanceNotFoundException The underlying MBean is not 177 * registered in the MBeanServer. 178 **/ getConfigFilename()179 public String getConfigFilename() 180 throws IOException, InstanceNotFoundException; 181 182 /** 183 * Gets the current configuration data. 184 * <p> 185 * This method returns the configuration data which is currently held 186 * in memory. 187 * </p> 188 * <p>Call {@link #load} to reload the data from the configuration 189 * file, and {@link #save} to save the data to the configuration 190 * file. 191 * </p> 192 * @see #getSaveState() 193 * @return The current configuration data in memory. 194 * @throws IOException A connection problem occurred when accessing 195 * the underlying resource. 196 * @throws InstanceNotFoundException The underlying MBean is not 197 * registered in the MBeanServer. 198 **/ getConfiguration()199 public ScanManagerConfig getConfiguration() 200 throws IOException, InstanceNotFoundException; 201 202 /** 203 * Sets the current configuration data. 204 * <p> 205 * This method replaces the configuration data in memory. 206 * The {@link #getSaveState state} is switched to {@link 207 * SaveState#MODIFIED MODIFIED}. 208 * </p> 209 * <p>Calling {@link #load} will reload the data from the configuration 210 * file, and all modifications will be lost. 211 * Calling {@link #save} will save the modified data to the configuration 212 * file. 213 * </p> 214 * <p> 215 * This action has no effect on the {@link ScanManagerMXBean} until 216 * {@link ScanManagerMXBean#getConfigurationMBean ScanManagerMXBean} 217 * points to this MBean and {@link ScanManagerMXBean#applyConfiguration 218 * ScanManagerMXBean.applyConfiguration} is called. 219 * </p> 220 * @param config The new configuration data. 221 * @see #getSaveState() 222 * @throws IOException A connection problem occurred when accessing 223 * the underlying resource. 224 * @throws InstanceNotFoundException The underlying MBean is not 225 * registered in the MBeanServer. 226 */ setConfiguration(ScanManagerConfig config)227 public void setConfiguration(ScanManagerConfig config) 228 throws IOException, InstanceNotFoundException; 229 230 /** 231 * Adds a new directory scanner to the current configuration data. 232 * <p> 233 * This method updates the configuration data in memory, adding 234 * a {@link DirectoryScannerConfig} to the {@link 235 * ScanManagerConfig#getScanList directory scanner list}. 236 * The {@link #getSaveState state} is switched to {@link 237 * SaveState#MODIFIED MODIFIED}. 238 * </p> 239 * <p>Calling {@link #load} will reload the data from the configuration 240 * file, and all modifications will be lost. 241 * Calling {@link #save} will save the modified data to the configuration 242 * file. 243 * </p> 244 * <p> 245 * This action has no effect on the {@link ScanManagerMXBean} until 246 * {@link ScanManagerMXBean#getConfigurationMBean ScanManagerMXBean} 247 * points to this MBean and {@link ScanManagerMXBean#applyConfiguration 248 * ScanManagerMXBean.applyConfiguration} is called. 249 * </p> 250 * @param name A name for the new directory scanner. This is the value 251 * that will be later used in the {@link DirectoryScannerMXBean} 252 * ObjectName for the <code>name=</code> key. 253 * @param dir The root directory at which this scanner will start scanning. 254 * @param filePattern A {@link java.util.regex.Pattern regular expression} 255 * to match against a selected file name. 256 * @param sizeExceedsMaxBytes Only file whose size exceeds that limit will 257 * be selected. <code.0</code> or a 258 * negative value means no limit. 259 * @param sinceLastModified Select files which haven't been modified for 260 * that number of milliseconds - i.e. 261 * {@code sinceLastModified=3600000} will exclude files which 262 * have been modified in the last hour. 263 * The date of last modification is ignored if <code>0</code> or a 264 * negative value is provided. 265 * @see #getSaveState() 266 * @return The added <code>DirectoryScannerConfig</code>. 267 * @throws IOException A connection problem occurred when accessing 268 * the underlying resource. 269 * @throws InstanceNotFoundException The underlying MBean is not 270 * registered in the MBeanServer. 271 **/ 272 public DirectoryScannerConfig addDirectoryScanner(String name, String dir, String filePattern, long sizeExceedsMaxBytes, long sinceLastModified)273 addDirectoryScanner(String name, String dir, String filePattern, 274 long sizeExceedsMaxBytes, long sinceLastModified) 275 throws IOException, InstanceNotFoundException; 276 277 /** 278 * Removes a directory scanner from the current configuration data. 279 * <p> 280 * This method updates the configuration data in memory, removing 281 * a {@link DirectoryScannerConfig} from the {@link 282 * ScanManagerConfig#getScanList directory scanner list}. 283 * The {@link #getSaveState state} is switched to {@link 284 * SaveState#MODIFIED MODIFIED}. 285 * </p> 286 * <p>Calling {@link #load} will reload the data from the configuration 287 * file, and all modifications will be lost. 288 * Calling {@link #save} will save the modified data to the configuration 289 * file. 290 * </p> 291 * <p> 292 * This action has no effect on the {@link ScanManagerMXBean} until 293 * {@link ScanManagerMXBean#getConfigurationMBean ScanManagerMXBean} 294 * points to this MBean and {@link ScanManagerMXBean#applyConfiguration 295 * ScanManagerMXBean.applyConfiguration} is called. 296 * </p> 297 * @param name The name of the new directory scanner. This is the value 298 * that is used in the {@link DirectoryScannerMXBean} 299 * ObjectName for the <code>name=</code> key. 300 * @return The removed <code>DirectoryScannerConfig</code>. 301 * @throws IllegalArgumentException if there's no directory scanner by 302 * that name in the current configuration data. 303 * @throws IOException A connection problem occurred when accessing 304 * the underlying resource. 305 * @throws InstanceNotFoundException The underlying MBean is not 306 * registered in the MBeanServer. 307 **/ 308 public DirectoryScannerConfig removeDirectoryScanner(String name)309 removeDirectoryScanner(String name) 310 throws IOException, InstanceNotFoundException; 311 312 /** 313 * Gets the save state of the current configuration data. 314 * <p> 315 * {@link SaveState#CREATED CREATED} means that the configuration data was just 316 * created. It has not been loaded from the configuration file. 317 * Calling {@link #load} will load the data from the configuration file. 318 * Calling {@link #save} will write the empty data to the configuration 319 * file. 320 * </p> 321 * <p> 322 * {@link SaveState#LOADED LOADED} means that the configuration data 323 * was loaded from the configuration file. 324 * </p> 325 * <p> 326 * {@link SaveState#MODIFIED MODIFIED} means that the configuration data 327 * was modified since it was last loaded or saved. 328 * Calling {@link #load} will reload the data from the configuration file, 329 * and all modifications will be lost. 330 * Calling {@link #save} will write the modified data to the configuration 331 * file. 332 * </p> 333 * <p> 334 * {@link SaveState#SAVED SAVED} means that the configuration data 335 * was saved to the configuration file. 336 * </p> 337 * <p> 338 * This state doesn't indicate whether this MBean configuration data 339 * was {@link ScanManagerMXBean#applyConfiguration applied} by the 340 * {@link ScanManagerMXBean}. 341 * </p> 342 * @throws IOException A connection problem occurred when accessing 343 * the underlying resource. 344 * @throws InstanceNotFoundException The underlying MBean is not 345 * registered in the MBeanServer. 346 * @return The save state of the {@code ScanDirConfigMXBean}. 347 */ getSaveState()348 public SaveState getSaveState() 349 throws IOException, InstanceNotFoundException; 350 351 } 352