VirtualDatabaseMBean


1   /**
2    * C-JDBC: Clustered JDBC.
3    * Copyright (C) 2002-2004 French National Institute For Research In Computer
4    * Science And Control (INRIA).
5    * Contact: c-jdbc@objectweb.org
6    * 
7    * This library is free software; you can redistribute it and/or modify it
8    * under the terms of the GNU Lesser General Public License as published by the
9    * Free Software Foundation; either version 2.1 of the License, or any later
10   * version.
11   * 
12   * This library is distributed in the hope that it will be useful, but WITHOUT
13   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
14   * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
15   * for more details.
16   * 
17   * You should have received a copy of the GNU Lesser General Public License
18   * along with this library; if not, write to the Free Software Foundation,
19   * Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
20   *
21   * Initial developer(s): Emmanuel Cecchet.
22   * Contributor(s): Nicolas Modrzyk.
23   */
24  
25  package org.objectweb.cjdbc.common.jmx.mbeans;
26  
27  import java.util.ArrayList  ;
28  import java.util.Hashtable  ;
29  import java.util.Map  ;
30  
31  import org.objectweb.cjdbc.common.exceptions.VirtualDatabaseException;
32  import org.objectweb.cjdbc.common.monitor.backend.BackendStatistics;
33  import org.objectweb.cjdbc.common.shared.DumpInfo;
34  
35  /**
36   * JMX Interface to remotely manage a Virtual Databases.
37   * 
38   * @author <a HREF="mailto:Emmanuel.Cecchet@inria.fr">Emmanuel Cecchet </a>
39   * @author <A HREF="mailto:Nicolas.Modrzyk@inrialpes.fr">Nicolas Modrzyk </a>
40   * @version 1.0
41   */
42  public interface VirtualDatabaseMBean
43  {
44    //
45    // Methods are organized as follows:
46    // 1. Database backends management
47    // 2. Checkpoint management
48    // 3. Backup management
49    // 4. Virtual database management
50    //  
51  
52    //
53    // Database backends management
54    //
55  
56    /**
57     * Enables a backend that has been previously added to this virtual database
58     * and that is in the disabled state. The backend is enabled without further
59     * check.
60     * 
61     * @param databaseBackendName The database backend logical name to enable
62     * @exception VirtualDatabaseException in case of communication-related error
63     */
64    void forceEnableBackend(String   databaseBackendName)
65        throws VirtualDatabaseException;
66  
67    /**
68     * Enable the given backend from its last known checkpoint
69     * 
70     * @param backendName the name of the backend to enable
71     * @throws VirtualDatabaseException if enable failed, or if there is no last
72     *           known checkpoint
73     */
74    void enableBackendFromCheckpoint(String   backendName)
75        throws VirtualDatabaseException;
76  
77    /**
78     * Enable all the backends without any check.
79     * 
80     * @throws VirtualDatabaseException if fails
81     */
82    void enableAllBackends() throws VirtualDatabaseException;
83  
84    // TODO: Move implem to console
85  
86    /**
87     * Enable all backends from their last known states that has been recorded in
88     * the recovery log, and enable only the backends which where properly
89     * disabled.
90     * 
91     * @throws VirtualDatabaseException if fails
92     */
93    void enableAllBackendsFromCheckpoint() throws VirtualDatabaseException;
94  
95    // TODO: Move implem to console
96  
97    /**
98     * Disables a backend that is currently enabled on this virtual database
99     * (without further check).
100    * 
101    * @param databaseBackendName The database backend logical name to enable
102    * @exception VirtualDatabaseException in case of communication-related error
103    */
104   void forceDisableBackend(String   databaseBackendName)
105       throws VirtualDatabaseException;
106 
107   /**
108    * Disables a backend once all the pending write queries are executed. A
109    * checkpoint is inserted in the recovery log. The backend must belong to this
110    * virtual database and be in the enabled state.
111    * 
112    * @param databaseBackendName The database backend logical name to disable
113    * @exception VirtualDatabaseException in case of communication-related error
114    */
115   void disableBackendWithCheckpoint(String   databaseBackendName)
116       throws VirtualDatabaseException;
117 
118   /**
119    * Disable all backends for this virtual database
120    * 
121    * @throws VirtualDatabaseException if fails
122    */
123   void disableAllBackends() throws VirtualDatabaseException;
124 
125   // TODO: Move implem to console
126 
127   /**
128    * Disable all backends and store a checkpoint
129    * 
130    * @param checkpoint the name of the checkpoitn
131    * @throws VirtualDatabaseException if fails
132    */
133   void disableAllBackendsWithCheckpoint(String   checkpoint)
134       throws VirtualDatabaseException;
135 
136   // TODO: Move implem to console
137 
138   /**
139    * Get a list of all DatabaseBackend names.
140    * 
141    * @return ArrayList <code>ArrayList</code> of <code>String</code>
142    *         representing database backend names
143    * @throws VirtualDatabaseException if an error occurs
144    */
145   ArrayList   getAllBackendNames() throws VirtualDatabaseException;
146 
147   /**
148    * Add an additionnal backend to the virtual database with connection managers
149    * identical to the backend replicated.
150    * 
151    * @param backendName the backend to replicate and to use parameters from.
152    * @param newBackendName the new backend name.
153    * @param parameters parameters to override or modify when replicating to the
154    *          new backend
155    * @throws VirtualDatabaseException if cannot replicate backend
156    */
157   void replicateBackend(String   backendName, String   newBackendName,
158       Map   parameters) throws VirtualDatabaseException;
159 
160   /**
161    * Remove a backend from the virtual database list. Do not check whether it is
162    * enabled or not, and do not perform backup operation
163    * 
164    * @param backend the name of the backend to remove
165    * @throws VirtualDatabaseException if the backend does not exist
166    */
167   void removeBackend(String   backend) throws VirtualDatabaseException;
168 
169   /**
170    * Transfer the backend to the destinated controller. Note that this does
171    * nothing in a non-distributed environment
172    * 
173    * @param backend the backend to transfer
174    * @param controllerDestination the controller to copy the backend to
175    * @throws VirtualDatabaseException if transfer failed
176    */
177   void transferBackend(String   backend, String   controllerDestination)
178       throws VirtualDatabaseException;
179 
180   //
181   // Checkpoints management
182   //
183 
184   /**
185    * Copies a chunk of the local virtual database recovery log onto a remote
186    * controller's peer virtual database log. The copy is performed from the
187    * checkpoint associated to the specified dump uptil 'now' (a new global
188    * checkpoint). The copy is sent to the specified remote node.
189    * 
190    * @param dumpName the name of the dump (which gives associated checkpoint)
191    *          from which to perform the copy.
192    * @param controllerName the remote controller to send the copy to
193    * @throws VirtualDatabaseException if there is no recovery log, or the
194    *           virtual database is not distributed, or in case of error.
195    */
196   void copyLogFromCheckpoint(String   dumpName, String   controllerName)
197       throws VirtualDatabaseException;
198 
199   /**
200    * Deletes the recovery log (if any) from the begining upto the specified
201    * checkpoint.
202    * 
203    * @param checkpointName the name of the checkpoint upto which to delete the
204    *          recovery log.
205    * @throws VirtualDatabaseException if there is no recovery log, or in case of
206    *           error.
207    */
208   void deleteLogUpToCheckpoint(String   checkpointName)
209       throws VirtualDatabaseException;
210 
211   /**
212    * Disable all backends and store a checkpoint
213    * 
214    * @param checkpoint the name of the checkpoitn
215    * @throws VirtualDatabaseException if fails
216    */
217   void removeCheckpoint(String   checkpoint) throws VirtualDatabaseException;
218 
219   /**
220    * Sets the last known checkpoint of a backend. This will also update the
221    * value in the recovery log
222    * 
223    * @param backendName backend
224    * @param checkpoint checkpoint
225    * @throws VirtualDatabaseException if fails
226    */
227   void setBackendLastKnownCheckpoint(String   backendName, String   checkpoint)
228       throws VirtualDatabaseException;
229 
230   /**
231    * Returns an array of names of all the checkpoint available in the recovery
232    * log of this virtual dabase.
233    * 
234    * @return <code>ArrayList</code> of checkpoint names. Can be empty
235    */
236   ArrayList   viewCheckpointNames();
237 
238   // 
239   // Backup management
240   //
241 
242   /**
243    * Get the names of the <code>Backupers</code> available from this
244    * <code>BackupManager</code>.
245    * 
246    * @return an (possibly 0-sized) array of <code>String</code> representing
247    *         the name of the <code>Backupers</code>
248    */
249   String  [] getBackuperNames();
250 
251   /**
252    * Get the dump format associated to a given <code>Backuper</code>
253    * 
254    * @param backuperName name associated to a <code>Backuper</code>
255    * @return the dump format associated to a given <code>Backuper</code>
256    */
257   String   getDumpFormatForBackuper(String   backuperName);
258 
259   /**
260    * Create a backup of a specific backend. Note the backend will be disabled if
261    * needed during backup, and will be put back to its previous state after
262    * backup.
263    * 
264    * @param backendName the target backend to backup
265    * @param login the login to use to connect to the database for the backup
266    *          operation
267    * @param password the password to use to connect to the database for the
268    *          backup operation
269    * @param dumpName the name of the dump to create
270    * @param backuperName the logical name of the backuper to use
271    * @param path the path where to store the dump
272    * @param tables the list of tables to backup, null means all tables
273    * @throws VirtualDatabaseException if the backup fails
274    */
275   void backupBackend(String   backendName, String   login, String   password,
276       String   dumpName, String   backuperName, String   path, ArrayList   tables)
277       throws VirtualDatabaseException;
278 
279   /**
280    * Get all available dump info for this virtual database
281    * 
282    * @return an array of <code>DumpInfo</code> containing the available dump
283    *         info for this virtual database. Cannot be null but can be empty.
284    * @throws VirtualDatabaseException if cannot retrieve dump informations
285    */
286   DumpInfo[] getAvailableDumps() throws VirtualDatabaseException;
287 
288   /**
289    * Update the path of the dump for a given dumpName.
290    * 
291    * @param dumpName name of the dump
292    * @param newPath new path for the dump
293    * @throws VirtualDatabaseException if cannot update the path
294    */
295   void updateDumpPath(String   dumpName, String   newPath)
296       throws VirtualDatabaseException;
297 
298   /**
299    * Remove a dump from the controller repository
300    * 
301    * @param dumpName name of the dump to remove
302    * @return <code>true</code> if the dump was removed, <code>false</code>
303    *         otherwise
304    */
305   boolean removeDump(String   dumpName);
306 
307   /**
308    * Restore a dump on a specific backend. The proper Backuper is retrieved
309    * automatically according to the dump format stored in the recovery log dump
310    * table.
311    * <p>
312    * This method disables the backend and leave it disabled after recovery
313    * process. The user has to call the <code>enableBackendFromCheckpoint</code>
314    * after this.
315    * 
316    * @param databaseBackendName the name of the backend to restore
317    * @param login the login to use to connect to the database for the restore
318    *          operation
319    * @param password the password to use to connect to the database for the
320    *          restore operation
321    * @param dumpName the name of the dump to restore
322    * @param tables the list of tables to restore, null means all tables
323    * @throws VirtualDatabaseException if the restore operation failed
324    */
325   void restoreDumpOnBackend(String   databaseBackendName, String   login,
326       String   password, String   dumpName, ArrayList   tables)
327       throws VirtualDatabaseException;
328 
329   /**
330    * Copy a local dump over to a remote member of this distributed vdb, making
331    * it available for restore operation. Wants a recovery log to be enabled
332    * (stores dump info, and meaning less otherwize as no restore is possible
333    * without a recovery log). It is pointless (and an error) to use this on a
334    * non-distributed virtual db.
335    * 
336    * @param dumpName the name of the dump to copy. Should exist locally, and not
337    *          remotely.
338    * @param remoteControllerName the remote controller to talk to.
339    * @throws VirtualDatabaseException in case of error.
340    */
341   void copyDump(String   dumpName, String   remoteControllerName)
342       throws VirtualDatabaseException;
343 
344   /**
345    * Transfer specified dump over to specified vdb's controller, making it
346    * available for restore operation. The local dump is not deleted and still
347    * available for local restore operations. This operation wants a recovery log
348    * to be enabled for the vdb (stores dump info, and meaning less otherwize as
349    * no restore is possible without a recovery log). It is pointless (and an
350    * error) to use this on a non-distributed virtual db.
351    * 
352    * @param dumpName the name of the dump to copy. Should exist locally, and not
353    *          remotely.
354    * @param remoteControllerName the remote controller to talk to.
355    * @param noCopy specifies whether or not to actually copy the dump. Default:
356    *          false. No-copy is a useful option in case of NFS/shared dumps.
357    * @throws VirtualDatabaseException in case of error
358    */
359   void transferDump(String   dumpName, String   remoteControllerName, boolean noCopy)
360       throws VirtualDatabaseException;
361 
362   //
363   // Administration/Monitoring functions
364   //
365 
366   /**
367    * Return information about the specified backend.
368    * 
369    * @param backendName the backend logical name
370    * @return String the backend information
371    * @throws VirtualDatabaseException if an error occurs
372    */
373   String   getBackendInformation(String   backendName)
374       throws VirtualDatabaseException;
375 
376   // TODO: Should return a BackendInfo
377 
378   /**
379    * The getXml() method does not return the schema if it is not static anymore,
380    * to avoid confusion between static and dynamic schema. This method returns a
381    * static view of the schema, whatever the dynamic precision is.
382    * 
383    * @param backendName the name of the backend to get the schema from
384    * @return an xml formatted string
385    * @throws VirtualDatabaseException if an error occurs while accessing the
386    *           backend, or if the backend does not exist.
387    */
388   String   getBackendSchema(String   backendName) throws VirtualDatabaseException;
389 
390   /**
391    * Return the state of a given database backend
392    * 
393    * @param backendName the name of the backend
394    * @return <code>String</code> description of the database backend
395    * @throws VirtualDatabaseException if fails
396    */
397   String   getBackendState(String   backendName) throws VirtualDatabaseException;
398 
399   // TODO: Dup with getBackendInformation?
400 
401   /**
402    * Retrieves this <code>VirtualDatabase</code> object in xml format
403    * 
404    * @return xml formatted string that conforms to c-jdbc.dtd
405    */
406   String   getXml();
407 
408   //
409   // Virtual database management
410   //
411 
412   /**
413    * Authenticate a user for a given virtual database
414    * 
415    * @param adminLogin username
416    * @param adminPassword password
417    * @return true if authentication is a success, false otherwise
418    * @throws VirtualDatabaseException if database does not exists
419    */
420   boolean checkAdminAuthentication(String   adminLogin, String   adminPassword)
421       throws VirtualDatabaseException;
422 
423   /**
424    * Gets the virtual database name to be used by the client (C-JDBC driver)
425    * 
426    * @return the virtual database name
427    */
428   String   getVirtualDatabaseName();
429 
430   /**
431    * Indicate if there is a recovery log defined for this virtual database
432    * 
433    * @return <code>true</code> if the recovery log is defined and can be
434    *         accessed, <code>false</code> otherwise
435    */
436   boolean hasRecoveryLog();
437 
438   /**
439    * Indicate if there is a result cache defined for this virtual database
440    * 
441    * @return <code>true</code> if a request cache is defined and can be
442    *         accessed, <code>false</code> otherwise
443    */
444   boolean hasResultCache();
445 
446   /**
447    * Tells whether this database is distributed or not
448    * 
449    * @return <code>true</code> if the database is distributed among multiple
450    *         controllers <code>false</code> if it exists on a single
451    *         controller only
452    */
453   boolean isDistributed();
454 
455   /**
456    * Shutdown this virtual database. Finish all threads and stop connection to
457    * backends
458    * 
459    * @param level Constants.SHUTDOWN_WAIT, Constants.SHUTDOWN_SAFE or
460    *          Constants.SHUTDOWN_FORCE
461    * @throws VirtualDatabaseException if an error occurs
462    */
463   void shutdown(int level) throws VirtualDatabaseException;
464 
465   /**
466    * Returns an array of information on this backend The method above is not
467    * used at the moment ... This one is by the GUI.
468    * 
469    * @param backendName the name of the backend
470    * @return <code>String[]</code>
471    * @throws VirtualDatabaseException if an error occurs
472    */
473   String  [] viewBackendInformation(String   backendName)
474       throws VirtualDatabaseException;
475 
476   // TODO: Ugly, probably dup, to refactor
477 
478   /**
479    * Returns a mapping of controller jmx names with their backends. Note the
480    * method is only useful in distributed environment
481    * 
482    * @return <code>Hashtable</code> of controllerName -->
483    *         ArrayList[BackendInfo]
484    * @throws VirtualDatabaseException if cannot return the result
485    */
486   Hashtable   viewGroupBackends() throws VirtualDatabaseException;
487 
488   /**
489    * Name of the controller owning this virtual database
490    * 
491    * @return url of the controller
492    */
493   String   viewOwningController();
494 
495   /**
496    * Retrieves an array of data on the backends for this virtual database
497    * 
498    * @return <code>String[][]</code> of formatted data for all backends
499    * @throws Exception if fails
500    */
501   String  [][] retrieveBackendsData() throws Exception  ;
502 
503   // TODO: Ugly, to refactor
504 
505   /**
506    * Retrieves an array of statistics of the given backend for this virtual
507    * database
508    * 
509    * @param backendName name of the backend
510    * @return <code>BackendStatistics[]</code> of formatted data for all
511    *         backends or <code>null</code> if the backend does not exist
512    * @throws Exception if fails
513    */
514   BackendStatistics getBackendStatistics(String   backendName) throws Exception  ;
515 
516   // TODO: Should monitoring be in a separate interface?
517 
518   /**
519    * Return the list of controllers defining this virtual database. If the
520    * database is not distributed this returns the same as
521    * <code>viewOwningController</code> otherwise returns an array of
522    * controller configuring this <code>DistributedVirtualDatabase</code>
523    * 
524    * @return <code>String[]</code> of controller names.
525    */
526   String  [] viewControllerList();
527 
528   /**
529    * Returns the currentNbOfThreads.
530    * 
531    * @return int
532    */
533   int getCurrentNbOfThreads();
534 
535   // TODO: Should monitoring be in a separate interface?
536 
537   /**
538    * Clean data collected by the current monitoring system, to avoid memory
539    * problems. Monitor does not have to be active.
540    * 
541    * @throws VirtualDatabaseException if there is no monitor.
542    */
543   void cleanMonitoringData() throws VirtualDatabaseException;
544 
545   // TODO: Should monitoring be in a separate interface? Ugly, usefulness?
546 
547   /**
548    * If a monitoring section exists, we can set the monitoring on or off by
549    * calling this method. If monitoring is not defined we throw an exception.
550    * 
551    * @param active should set the monitor to on or off
552    * @throws VirtualDatabaseException if there is no monitor.
553    */
554   void setMonitoringToActive(boolean active) throws VirtualDatabaseException;
555   // TODO: Should monitoring be in a separate interface?
556 
557 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags