| /* |
| * 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 com.sun.jmx.examples.scandir.config.ResultRecord; |
| import java.io.IOException; |
| import javax.management.InstanceNotFoundException; |
| |
| /** |
| * The <code>ResultLogManagerMXBean</code> is in charge of managing result logs. |
| * {@link DirectoryScanner DirectoryScanners} can be configured to log a |
| * {@link ResultRecord} whenever they take action upon a file that |
| * matches their set of matching criteria. |
| * The <code>ResultLogManagerMXBean</code> is responsible for storing these |
| * results in its result logs. |
| * <p>The <code>ResultLogManagerMXBean</code> |
| * will let you interactively clear these result logs, change their |
| * capacity, and decide where (memory or file or both) the |
| * {@link ResultRecord ResultRecords} should be stored. |
| * <p>The memory log is useful in so far that its content can be interactively |
| * returned by the <code>ResultLogManagerMXBean</code>. |
| * The file log doesn't have this facility. |
| * <p>The result logs are intended to be used by e.g. an offline program that |
| * would take some actions on the files that were matched by the scanners |
| * criteria: |
| * <p>The <i>scandir</i> application could be configured to only produce logs |
| * (i.e. takes no action but logging the matching files), and the real |
| * action (e.g. mail the result log to the engineer which maintains the lab, |
| * or parse the log and prepare and send a single mail to the matching |
| * files owners, containing the list of file he/she should consider deleting) |
| * could be performed by such another program/module. |
| * |
| * @author Sun Microsystems, 2006 - All rights reserved. |
| */ |
| public interface ResultLogManagerMXBean { |
| |
| /** |
| * Creates a new log file in which to store results. |
| * <p>When this method is called, the {@link ResultLogManager} will stop |
| * logging in its current log file and use the new specified file instead. |
| * If that file already exists, it will be renamed by appending a '~' to |
| * its name, and a new empty file with the name specified by |
| * <var>basename</var> will be created. |
| * </p> |
| * <p>Calling this method has no side effect on the {@link |
| * com.sun.jmx.examples.scandir.config.ScanManagerConfig#getInitialResultLogConfig |
| * InitialResultLogConfig} held in the {@link ScanDirConfigMXBean} |
| * configuration. To apply these new values to the |
| * {@link ScanDirConfigMXBean} |
| * configuration, you must call {@link |
| * ScanManagerMXBean#applyCurrentResultLogConfig |
| * ScanManagerMXBean.applyCurrentResultLogConfig}. |
| *<p> |
| * @param basename The name of the new log file. This will be the |
| * new name returned by {@link #getLogFileName}. |
| * @param maxRecord maximum number of records to log in the specified file |
| * before creating a new file. <var>maxRecord</var> will be the |
| * new value returned by {@link #getLogFileCapacity}. |
| * When that maximum number of |
| * records is reached the {@link ResultLogManager} will rename |
| * the file by appending a '~' to its name, and a new empty |
| * log file will be created. |
| * @throws IOException A connection problem occurred when accessing |
| * the underlying resource. |
| * @throws InstanceNotFoundException The underlying MBean is not |
| * registered in the MBeanServer. |
| **/ |
| public void newLogFile(String basename, long maxRecord) |
| throws IOException, InstanceNotFoundException; |
| |
| /** |
| * Logs a result record to the active result logs (memory,file,both,or none) |
| * depending on how this MBean is currently configured. |
| * @see #getLogFileName() |
| * @see #getMemoryLogCapacity() |
| * @param record The result record to log. |
| * @throws IOException A connection problem occurred when accessing |
| * the underlying resource. |
| * @throws InstanceNotFoundException The underlying MBean is not |
| * registered in the MBeanServer. |
| */ |
| public void log(ResultRecord record) |
| throws IOException, InstanceNotFoundException; |
| |
| /** |
| * Gets the name of the current result log file. |
| * <p><code>null</code> means that no log file is configured: logging |
| * to file is disabled. |
| * </p> |
| * @return The name of the current result log file, or <code>null</code> |
| * if logging to file is disabled. |
| * @throws IOException A connection problem occurred when accessing |
| * the underlying resource. |
| * @throws InstanceNotFoundException The underlying MBean is not |
| * registered in the MBeanServer. |
| **/ |
| public String getLogFileName() |
| throws IOException, InstanceNotFoundException; |
| |
| /** |
| * Gets the whole content of the memory log. This cannot exceed |
| * {@link #getMemoryLogCapacity} records. |
| * |
| * @return the whole content of the memory log. |
| * @throws IOException A connection problem occurred when accessing |
| * the underlying resource. |
| * @throws InstanceNotFoundException The underlying MBean is not |
| * registered in the MBeanServer. |
| **/ |
| public ResultRecord[] getMemoryLog() |
| throws IOException, InstanceNotFoundException; |
| |
| /** |
| * Gets the maximum number of records that can be logged in the |
| * memory log. |
| * <p> |
| * A non positive value - <code>0</code> or negative - means that |
| * logging in memory is disabled. |
| * </p> |
| * <p>The memory log is a FIFO: when its maximum capacity is reached, its |
| * head element is removed to make place for a new element at its tail. |
| * </p> |
| * @return The maximum number of records that can be logged in the |
| * memory log. A value {@code <= 0} means that logging in memory is |
| * disabled. |
| * @throws IOException A connection problem occurred when accessing |
| * the underlying resource. |
| * @throws InstanceNotFoundException The underlying MBean is not |
| * registered in the MBeanServer. |
| **/ |
| public int getMemoryLogCapacity() |
| throws IOException, InstanceNotFoundException; |
| |
| /** |
| * Sets the maximum number of records that can be logged in the |
| * memory log. |
| * <p>The memory log is a FIFO: when its maximum capacity is reached, its |
| * head element is removed to make place for a new element at its tail. |
| * </p> |
| * @param size The maximum number of result records that can be logged in the memory log. <p> |
| * A non positive value - <code>0</code> or negative - means that |
| * logging in memory is disabled. It will also have the side |
| * effect of clearing the memory log. |
| * </p> |
| * |
| * @throws IOException A connection problem occurred when accessing |
| * the underlying resource. |
| * @throws InstanceNotFoundException The underlying MBean is not |
| * registered in the MBeanServer. |
| */ |
| public void setMemoryLogCapacity(int size) |
| throws IOException, InstanceNotFoundException; |
| |
| /** |
| * Sets the maximum number of records that can be logged in the result log |
| * file. |
| * <p>When that maximum number of |
| * records is reached the {@link ResultLogManager} will rename |
| * the result log file by appending a '~' to its name, and a new empty |
| * log file will be created. |
| * </p> |
| * <p>If logging to file is disabled calling this method |
| * is irrelevant. |
| * </p> |
| * @param maxRecord maximum number of records to log in the result log file. |
| * @see #getLogFileName() |
| * @throws IOException A connection problem occurred when accessing |
| * the underlying resource. |
| * @throws InstanceNotFoundException The underlying MBean is not |
| * registered in the MBeanServer. |
| **/ |
| public void setLogFileCapacity(long maxRecord) |
| throws IOException, InstanceNotFoundException; |
| |
| /** |
| * Gets the maximum number of records that can be logged in the result log |
| * file. |
| * <p>When that maximum number of |
| * records is reached the {@link ResultLogManager} will rename |
| * the result log file by appending a '~' to its name, and a new empty |
| * log file will be created. |
| * </p> |
| * @see #getLogFileName() |
| * @return The maximum number of records that can be logged in the result |
| * log file. |
| * @throws IOException A connection problem occurred when accessing |
| * the underlying resource. |
| * @throws InstanceNotFoundException The underlying MBean is not |
| * registered in the MBeanServer. |
| **/ |
| public long getLogFileCapacity() |
| throws IOException, InstanceNotFoundException; |
| |
| /** |
| * Gets The number of records that have been logged in the |
| * current result log file. This will always be less than |
| * {@link #getLogFileCapacity()}. |
| * @return The number of records in the |
| * current result log file. |
| * |
| * @throws IOException A connection problem occurred when accessing |
| * the underlying resource. |
| * @throws InstanceNotFoundException The underlying MBean is not |
| * registered in the MBeanServer. |
| **/ |
| public long getLoggedCount() |
| throws IOException, InstanceNotFoundException; |
| |
| /** |
| * Clears the memory log and result log file. |
| * |
| * @throws IOException A connection problem occurred when accessing |
| * the underlying resource. |
| * @throws InstanceNotFoundException The underlying MBean is not |
| * registered in the MBeanServer. |
| **/ |
| public void clearLogs() |
| throws IOException, InstanceNotFoundException; |
| } |
