ResultLogManagerMXBean


1   /*
2    * ResultLogManagerMXBean.java
3    *
4    * Created on July 17, 2006, 1:15 PM
5    *
6    * @(#)ResultLogManagerMXBean.java  1.2 06/08/02
7    *
8    * Copyright (c) 2006 Sun Microsystems, Inc. All Rights Reserved.
9    *
10   * Redistribution and use in source and binary forms, with or without
11   * modification, are permitted provided that the following conditions are met:
12   *
13   * -Redistribution of source code must retain the above copyright notice, this
14   *  list of conditions and the following disclaimer.
15   *
16   * -Redistribution in binary form must reproduce the above copyright notice,
17   *  this list of conditions and the following disclaimer in the documentation
18   *  and/or other materials provided with the distribution.
19   *
20   * Neither the name of Sun Microsystems, Inc. or the names of contributors may
21   * be used to endorse or promote products derived from this software without
22   * specific prior written permission.
23   *
24   * This software is provided "AS IS," without a warranty of any kind. ALL
25   * EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING
26   * ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE
27   * OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN MICROSYSTEMS, INC. ("SUN")
28   * AND ITS LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE
29   * AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS
30   * DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY LOST
31   * REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL,
32   * INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY
33   * OF LIABILITY, ARISING OUT OF THE USE OF OR INABILITY TO USE THIS SOFTWARE,
34   * EVEN IF SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
35   *
36   * You acknowledge that this software is not designed, licensed or intended
37   * for use in the design, construction, operation or maintenance of any
38   * nuclear facility.
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 
259 
260
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags