ScanDirConfigMXBean


1   /*
2    * ScanDirConfigMXBean.java
3    *
4    * Created on July 12, 2006, 7:43 PM
5    *
6    * @(#)ScanDirConfigMXBean.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.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      **/
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      **/
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      **/
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      **/
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      */
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 
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 
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      */
348     public SaveState getSaveState()
349         throws IOException  , InstanceNotFoundException  ;
350     
351 }
352 
353 
354
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags