View Javadoc
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      **/
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 }