ScanManagerMXBean


1   /*
2    * ScanManagerMXBean.java
3    *
4    * Created on July 10, 2006, 2:17 PM
5    *
6    * @(#)ScanManagerMXBean.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 java.io.IOException  ;
44  import java.util.Map  ;
45  import javax.management.InstanceNotFoundException  ;
46  import javax.management.JMException  ;
47  
48  /**
49   * The <code>ScanManagerMXBean</code> is responsible for applying a 
50   * configuration, starting and scheduling directory scans, and reporting 
51   * application state.
52   * <p>
53   * The <code>ScanManagerMXBean</code> is a singleton MBean: there can be 
54   * at most one instance of such an MBean registered in a given MBeanServer.
55   * The name of that MBean is a constant defined in 
56   * {@link ScanManager#SCAN_MANAGER_NAME ScanManager.SCAN_MANAGER_NAME}.
57   * </p>
58   * <p>  
59   * The <code>ScanManagerMXBean</code> is the entry point of the <i>scandir</i>
60   * application management interface. It is from this MBean that all other 
61   * MBeans will be created and registered.
62   * </p>
63   *
64   * @author Sun Microsystems, 2006 - All rights reserved.
65   **/
66  public interface ScanManagerMXBean {
67      /**
68       * This state tells whether directory scans are running, scheduled,
69       * successfully completed, or stopped. 
70       * <p>
71       * The {@link #CLOSED} state means
72       * that the {@link ScanManagerMXBean} was closed and is no longer usable.
73       * This state is used when the {@link ScanManagerMXBean} needs to be 
74       * unregistered.
75       * </p>
76       **/
77      public enum ScanState {
78          /**
79           * Scanning of directories is in process.
80           **/
81          RUNNING,
82          
83          /**
84           * Scanning of directories is not in process, but is scheduled
85           * for a later date.
86           **/
87          SCHEDULED, 
88          
89          /**
90           * Scanning is successfully completed.
91           **/
92          COMPLETED,
93          
94          /**
95           * Scanning is stopped. No scanning is scheduled.
96           **/
97          STOPPED,
98          
99          /**
100          * close() was called.
101          **/
102         CLOSED
103                
104     }
105     
106     /**
107      * Returns the current state of the application.
108      * @return the current state of the application.
109      * @throws IOException A connection problem occurred when accessing
110      *                     the underlying resource.
111      * @throws InstanceNotFoundException The underlying MBean is not
112      *         registered in the MBeanServer.
113      **/
114     public ScanState getState() 
115         throws IOException  , InstanceNotFoundException  ;
116    
117     /**
118      * Schedule a scan session for a later date.
119      * <p>
120      * A scan session is a background task that will sequentially call {@link 
121      * DirectoryScannerMXBean#scan scan()} on every {@link
122      * DirectoryScannerMXBean} configured for this MBean.
123      * </p>
124      * @see #getDirectoryScanners
125      * @param delay The first scan session will be started after
126      *        the given delay. 0 means start now.
127      * @param interval Scan session will be rescheduled periodically
128      *        at the specified interval. The interval starts at the
129      *        the end of the scan session: if a scan session takes
130      *        on average x milliseconds to complete, then a scan session will
131      *        be started on average every x+interval milliseconds.
132      *        if (interval == 0) then scan session will not be
133      *        rescheduled, and will run only once.
134      * @throws IllegalStateException if a scan session is already
135      *         running or scheduled, or the MBean is closed.
136      * @throws IOException A connection problem occurred when accessing
137      *                     the underlying resource.
138      * @throws InstanceNotFoundException The underlying MBean is not
139      *         registered in the MBeanServer.
140      **/
141     public void schedule(long delay, long interval) 
142         throws IOException  , InstanceNotFoundException  ;
143     
144      
145     /**
146      * Stops current running or scheduled scan sessions if any.
147      * <p>
148      * A scan session is a background task that will sequentially call {@link 
149      * DirectoryScannerMXBean#scan scan()} on every {@link
150      * DirectoryScannerMXBean} configured for this MBean.
151      * </p>
152      * <p>
153      * Scan sessions are started/scheduled by calls to {@link #start start} or
154      * {@link #schedule schedule}.
155      * </p>
156      * After this method completes the state of the application will
157      * be {@link ScanState#STOPPED}.
158      * @throws IOException A connection problem occurred when accessing
159      *                     the underlying resource.
160      * @throws InstanceNotFoundException The underlying MBean is not
161      *         registered in the MBeanServer.
162      **/
163     public void stop() 
164         throws IOException  , InstanceNotFoundException  ;
165     
166     /**
167      * Switches the state to CLOSED.
168      * When closed, this MBean cannot be used any more.
169      * @throws IOException A connection problem occurred when accessing
170      *                     the underlying resource.
171      * @throws InstanceNotFoundException The underlying MBean is not
172      *         registered in the MBeanServer.
173      **/
174     public void close() 
175         throws IOException  , InstanceNotFoundException  ;
176     
177     /**
178      * Starts a scan session immediately.
179      * This is equivalent to {@link #schedule(long,long) schedule(0,0)}.
180      * @throws IllegalStateException if a scan session is already
181      *         running or scheduled, or the MBean is closed.
182      * @throws IOException A connection problem occurred when accessing
183      *                     the underlying resource.
184      * @throws InstanceNotFoundException The underlying MBean is not
185      *         registered in the MBeanServer.
186      **/
187     public void start() 
188         throws IOException  , InstanceNotFoundException  ;
189     
190     /**
191      * Gets the list of directory scanners configured for this MBean.
192      * @return A {@code Map<String,DirectoryScannerMXBean>} where the 
193      *         key in the map is the value of the <code>name=</code> key 
194      *         of the {@link DirectoryScannerMXBean} ObjectName.
195      * @throws IOException A connection problem occurred when accessing
196      *                     the underlying resource.
197      * @throws JMException The MBeanServer failed to call the underlying MBean. 
198      **/
199     public Map  <String  ,DirectoryScannerMXBean> getDirectoryScanners() 
200         throws IOException  , JMException  ;
201     
202     /**
203      * Apply the configuration handled by the {@link 
204      * #getConfigurationMBean configuration MBean}.
205      * <p>
206      * When the configuration is applied, all the {@link DirectoryScannerMXBean}
207      * created by this MBean will be unregistered, and new {@link 
208      * DirectoryScannerMXBean} will be created and registered from the 
209      * new {@link ScanDirConfigMXBean#getConfiguration configuration data}.
210      * </p>
211      * <p>
212      * The initial result log configuration held by the {@link 
213      * #getConfigurationMBean configuration MBean} will also be pushed to the
214      * {@link ResultLogManagerMXBean}. If you don't want to lose your current
215      * {@link ResultLogManagerMXBean} configuration, you should therefore call 
216      * {@link #applyCurrentResultLogConfig 
217      * applyCurrentResultLogConfig} before calling 
218      * {@link #applyConfiguration applyConfiguration}
219      * </p>
220      * @param fromMemory if {@code true}, the configuration will be applied
221      *        from memory. if {@code false}, the {@code ScanManagerMXBean} will
222      *        ask the {@link 
223      * #getConfigurationMBean configuration MBean} to {@link 
224      * ScanDirConfigMXBean#load reload its configuration} before applying
225      * it.
226      * @throws IllegalStateException if a scan session is 
227      *         running or scheduled, or the MBean is closed.
228      * @throws IOException A connection problem occurred when accessing
229      *                     the underlying resource.
230      * @throws JMException The MBeanServer failed to call the underlying MBean. 
231      **/
232     public void applyConfiguration(boolean fromMemory) 
233         throws IOException  , JMException  ;
234     /**
235      * Replaces the {@link 
236      * #getConfigurationMBean configuration MBean}'s {@link 
237      * com.sun.jmx.examples.scandir.config.ScanManagerConfig#getInitialResultLogConfig 
238      * initial result log configuration} with the current {@link 
239      * ResultLogManagerMXBean}
240      * configuration. This prevents the <code>ResultLogManagerMXBean</code>
241      * current configuration from being reset when {@link #applyConfiguration 
242      * applyConfiguration} is called.
243      * @param toMemory if {@code true} only replaces the initial result log 
244      *                 configuration held in memory.
245      *                 if {@code false}, the {@link 
246      * #getConfigurationMBean configuration MBean} will be asked to commit
247      * the whole configuration to the configuration file.
248      *
249      * @throws IOException A connection problem occurred when accessing
250      *                     the underlying resource.
251      * @throws JMException The MBeanServer failed to call the underlying MBean. 
252      **/
253     public void applyCurrentResultLogConfig(boolean toMemory)
254         throws IOException  , JMException  ;
255     
256     /**
257      * Instruct the {@code ScanManagerMXBean} to use another {@link 
258      * ScanDirConfigMXBean configuration MBean}.
259      * <p>This method doesn't {@link #applyConfiguration apply} the new
260      * configuration. If you want to apply the new configuration, you should
261      * additionally call {@link #applyConfiguration 
262      * applyConfiguration(true|false)}. Note that you cannot apply a 
263      * configuration as long as a scan session is scheduled or running.
264      * In that case you will need to wait for that session to complete
265      * or call {@link #stop} to stop it.
266      * </p>
267      * @param config A proxy to the {@link ScanDirConfigMXBean} that holds
268      * the new configuration for the application.
269      * @throws IOException A connection problem occurred when accessing
270      *                     the underlying resource.
271      * @throws InstanceNotFoundException The underlying MBean is not
272      *         registered in the MBeanServer.
273      */
274     public void setConfigurationMBean(ScanDirConfigMXBean config)
275         throws IOException  , InstanceNotFoundException  ;
276     /**
277      * Gets the current configuration MBean.
278      * @return A proxy to the current configuration MBean.
279      * @throws IOException A connection problem occurred when accessing
280      *                     the underlying resource.
281      * @throws InstanceNotFoundException The underlying MBean is not
282      *         registered in the MBeanServer.
283      **/
284     public ScanDirConfigMXBean getConfigurationMBean()
285         throws IOException  , InstanceNotFoundException  ;
286     /**
287      * This method creates a new alternate {@link ScanDirConfigMXBean}.
288      * 
289      * <p>You will need to call {@link #setConfigurationMBean 
290      * setConfigurationMBean} if you
291      * want this new {@link ScanDirConfigMXBean} to become the
292      * current configuration MBean.
293      * </p>
294      * <p>
295      * This new {@link ScanDirConfigMXBean} will be unregistered automatically
296      * by the {@code ScanManagerMXBean} when the {@code ScanManagerMXBean}
297      * is unregistered.
298      * </p>
299      * @param name The short name for the new {@link ScanDirConfigMXBean}.
300      *        This name will be used in the ObjectName <code>name=</code> key
301      *        of the new {@link ScanDirConfigMXBean}.
302      * @param filename The path of the file from which the new {@link 
303      *        ScanDirConfigMXBean} can {@link ScanDirConfigMXBean#load load} or
304      *        {@link ScanDirConfigMXBean#save save} its configuration data.
305      *        Note that even if the file exists and contain a valid 
306      *        configuration, you will still need to call {@link 
307      *        ScanDirConfigMXBean#load load} to make the {@link 
308      *        ScanDirConfigMXBean} load its configuration data.
309      * @throws IOException A connection problem occurred when accessing
310      *                     the underlying resource.
311      * @throws JMException The MBeanServer failed to call the underlying MBean.
312      * @return A proxy to the created {@link ScanDirConfigMXBean}.
313      */
314     public ScanDirConfigMXBean createOtherConfigurationMBean(String   name, 
315             String   filename) 
316         throws JMException  , IOException  ;
317 }
318 
319 
320
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags