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.ResultRecord; 44 import java.io.IOException; 45 import javax.management.InstanceNotFoundException; 46 47 /** 48 * The <code>ResultLogManagerMXBean</code> is in charge of managing result logs. 49 * {@link DirectoryScanner DirectoryScanners} can be configured to log a 50 * {@link ResultRecord} whenever they take action upon a file that 51 * matches their set of matching criteria. 52 * The <code>ResultLogManagerMXBean</code> is responsible for storing these 53 * results in its result logs. 54 * <p>The <code>ResultLogManagerMXBean</code> 55 * will let you interactively clear these result logs, change their 56 * capacity, and decide where (memory or file or both) the 57 * {@link ResultRecord ResultRecords} should be stored. 58 * <p>The memory log is useful in so far that its content can be interactively 59 * returned by the <code>ResultLogManagerMXBean</code>. 60 * The file log doesn't have this facility. 61 * <p>The result logs are intended to be used by e.g. an offline program that 62 * would take some actions on the files that were matched by the scanners 63 * criteria: 64 * <p>The <i>scandir</i> application could be configured to only produce logs 65 * (i.e. takes no action but logging the matching files), and the real 66 * action (e.g. mail the result log to the engineer which maintains the lab, 67 * or parse the log and prepare and send a single mail to the matching 68 * files owners, containing the list of file he/she should consider deleting) 69 * could be performed by such another program/module. 70 * 71 * @author Sun Microsystems, 2006 - All rights reserved. 72 */ 73 public interface ResultLogManagerMXBean { 74 75 /** 76 * Creates a new log file in which to store results. 77 * <p>When this method is called, the {@link ResultLogManager} will stop 78 * logging in its current log file and use the new specified file instead. 79 * If that file already exists, it will be renamed by appending a '~' to 80 * its name, and a new empty file with the name specified by 81 * <var>basename</var> will be created. 82 * </p> 83 * <p>Calling this method has no side effect on the {@link 84 * com.sun.jmx.examples.scandir.config.ScanManagerConfig#getInitialResultLogConfig 85 * InitialResultLogConfig} held in the {@link ScanDirConfigMXBean} 86 * configuration. To apply these new values to the 87 * {@link ScanDirConfigMXBean} 88 * configuration, you must call {@link 89 * ScanManagerMXBean#applyCurrentResultLogConfig 90 * ScanManagerMXBean.applyCurrentResultLogConfig}. 91 *<p> 92 * @param basename The name of the new log file. This will be the 93 * new name returned by {@link #getLogFileName}. 94 * @param maxRecord maximum number of records to log in the specified file 95 * before creating a new file. <var>maxRecord</var> will be the 96 * new value returned by {@link #getLogFileCapacity}. 97 * When that maximum number of 98 * records is reached the {@link ResultLogManager} will rename 99 * the file by appending a '~' to its name, and a new empty 100 * log file will be created. 101 * @throws IOException A connection problem occurred when accessing 102 * the underlying resource. 103 * @throws InstanceNotFoundException The underlying MBean is not 104 * registered in the MBeanServer. 105 **/ 106 public void newLogFile(String basename, long maxRecord) 107 throws IOException, InstanceNotFoundException; 108 109 /** 110 * Logs a result record to the active result logs (memory,file,both,or none) 111 * depending on how this MBean is currently configured. 112 * @see #getLogFileName() 113 * @see #getMemoryLogCapacity() 114 * @param record The result record to log. 115 * @throws IOException A connection problem occurred when accessing 116 * the underlying resource. 117 * @throws InstanceNotFoundException The underlying MBean is not 118 * registered in the MBeanServer. 119 */ 120 public void log(ResultRecord record) 121 throws IOException, InstanceNotFoundException; 122 123 /** 124 * Gets the name of the current result log file. 125 * <p><code>null</code> means that no log file is configured: logging 126 * to file is disabled. 127 * </p> 128 * @return The name of the current result log file, or <code>null</code> 129 * if logging to file is disabled. 130 * @throws IOException A connection problem occurred when accessing 131 * the underlying resource. 132 * @throws InstanceNotFoundException The underlying MBean is not 133 * registered in the MBeanServer. 134 **/ 135 public String getLogFileName() 136 throws IOException, InstanceNotFoundException; 137 138 /** 139 * Gets the whole content of the memory log. This cannot exceed 140 * {@link #getMemoryLogCapacity} records. 141 * 142 * @return the whole content of the memory log. 143 * @throws IOException A connection problem occurred when accessing 144 * the underlying resource. 145 * @throws InstanceNotFoundException The underlying MBean is not 146 * registered in the MBeanServer. 147 **/ 148 public ResultRecord[] getMemoryLog() 149 throws IOException, InstanceNotFoundException; 150 151 /** 152 * Gets the maximum number of records that can be logged in the 153 * memory log. 154 * <p> 155 * A non positive value - <code>0</code> or negative - means that 156 * logging in memory is disabled. 157 * </p> 158 * <p>The memory log is a FIFO: when its maximum capacity is reached, its 159 * head element is removed to make place for a new element at its tail. 160 * </p> 161 * @return The maximum number of records that can be logged in the 162 * memory log. A value {@code <= 0} means that logging in memory is 163 * disabled. 164 * @throws IOException A connection problem occurred when accessing 165 * the underlying resource. 166 * @throws InstanceNotFoundException The underlying MBean is not 167 * registered in the MBeanServer. 168 **/ 169 public int getMemoryLogCapacity() 170 throws IOException, InstanceNotFoundException; 171 172 /** 173 * Sets the maximum number of records that can be logged in the 174 * memory log. 175 * <p>The memory log is a FIFO: when its maximum capacity is reached, its 176 * head element is removed to make place for a new element at its tail. 177 * </p> 178 * @param size The maximum number of result records that can be logged in the memory log. <p> 179 * A non positive value - <code>0</code> or negative - means that 180 * logging in memory is disabled. It will also have the side 181 * effect of clearing the memory log. 182 * </p> 183 * 184 * @throws IOException A connection problem occurred when accessing 185 * the underlying resource. 186 * @throws InstanceNotFoundException The underlying MBean is not 187 * registered in the MBeanServer. 188 */ 189 public void setMemoryLogCapacity(int size) 190 throws IOException, InstanceNotFoundException; 191 192 /** 193 * Sets the maximum number of records that can be logged in the result log 194 * file. 195 * <p>When that maximum number of 196 * records is reached the {@link ResultLogManager} will rename 197 * the result log file by appending a '~' to its name, and a new empty 198 * log file will be created. 199 * </p> 200 * <p>If logging to file is disabled calling this method 201 * is irrelevant. 202 * </p> 203 * @param maxRecord maximum number of records to log in the result log file. 204 * @see #getLogFileName() 205 * @throws IOException A connection problem occurred when accessing 206 * the underlying resource. 207 * @throws InstanceNotFoundException The underlying MBean is not 208 * registered in the MBeanServer. 209 **/ 210 public void setLogFileCapacity(long maxRecord) 211 throws IOException, InstanceNotFoundException; 212 213 /** 214 * Gets the maximum number of records that can be logged in the result log 215 * file. 216 * <p>When that maximum number of 217 * records is reached the {@link ResultLogManager} will rename 218 * the result log file by appending a '~' to its name, and a new empty 219 * log file will be created. 220 * </p> 221 * @see #getLogFileName() 222 * @return The maximum number of records that can be logged in the result 223 * log file. 224 * @throws IOException A connection problem occurred when accessing 225 * the underlying resource. 226 * @throws InstanceNotFoundException The underlying MBean is not 227 * registered in the MBeanServer. 228 **/ 229 public long getLogFileCapacity() 230 throws IOException, InstanceNotFoundException; 231 232 /** 233 * Gets The number of records that have been logged in the 234 * current result log file. This will always be less than 235 * {@link #getLogFileCapacity()}. 236 * @return The number of records in the 237 * current result log file. 238 * 239 * @throws IOException A connection problem occurred when accessing 240 * the underlying resource. 241 * @throws InstanceNotFoundException The underlying MBean is not 242 * registered in the MBeanServer. 243 **/ 244 public long getLoggedCount() 245 throws IOException, InstanceNotFoundException; 246 247 /** 248 * Clears the memory log and result log file. 249 * 250 * @throws IOException A connection problem occurred when accessing 251 * the underlying resource. 252 * @throws InstanceNotFoundException The underlying MBean is not 253 * registered in the MBeanServer. 254 **/ 255 public void clearLogs() 256 throws IOException, InstanceNotFoundException; 257 } 258
