KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > objectweb > cjdbc > common > jmx > mbeans > 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 JavaDoc;
28 import java.util.Hashtable JavaDoc;
29 import java.util.Map JavaDoc;
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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc backendName, String JavaDoc newBackendName,
158       Map JavaDoc 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 JavaDoc 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 JavaDoc backend, String JavaDoc 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 JavaDoc dumpName, String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc backendName, String JavaDoc 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 JavaDoc 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 JavaDoc[] 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 JavaDoc getDumpFormatForBackuper(String JavaDoc 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 JavaDoc backendName, String JavaDoc login, String JavaDoc password,
276       String JavaDoc dumpName, String JavaDoc backuperName, String JavaDoc path, ArrayList JavaDoc 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 JavaDoc dumpName, String JavaDoc 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 JavaDoc 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 JavaDoc databaseBackendName, String JavaDoc login,
326       String JavaDoc password, String JavaDoc dumpName, ArrayList JavaDoc 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 JavaDoc dumpName, String JavaDoc 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 JavaDoc dumpName, String JavaDoc 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 JavaDoc getBackendInformation(String JavaDoc 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 JavaDoc getBackendSchema(String JavaDoc 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 JavaDoc getBackendState(String JavaDoc 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 JavaDoc 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 JavaDoc adminLogin, String JavaDoc 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 JavaDoc 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 JavaDoc[] viewBackendInformation(String JavaDoc 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 JavaDoc viewGroupBackends() throws VirtualDatabaseException;
487
488   /**
489    * Name of the controller owning this virtual database
490    *
491    * @return url of the controller
492    */

493   String JavaDoc 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 JavaDoc[][] retrieveBackendsData() throws Exception JavaDoc;
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 JavaDoc backendName) throws Exception JavaDoc;
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 JavaDoc[] 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 }
Popular Tags