VirtualDatabaseMBean


1   /**
2    * Sequoia: Database clustering technology.
3    * Copyright (C) 2002-2004 French National Institute For Research In Computer
4    * Science And Control (INRIA).
5    * Contact: sequoia@continuent.org
6    * 
7    * Licensed under the Apache License, Version 2.0 (the "License");
8    * you may not use this file except in compliance with the License.
9    * You may obtain a copy of the License at
10   * 
11   * http://www.apache.org/licenses/LICENSE-2.0
12   * 
13   * Unless required by applicable law or agreed to in writing, software
14   * distributed under the License is distributed on an "AS IS" BASIS,
15   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16   * See the License for the specific language governing permissions and
17   * limitations under the License. 
18   *
19   * Initial developer(s): Emmanuel Cecchet.
20   * Contributor(s): Nicolas Modrzyk.
21   */
22  
23  package org.continuent.sequoia.common.jmx.mbeans;
24  
25  import java.util.ArrayList  ;
26  import java.util.List  ;
27  import java.util.Map  ;
28  
29  import org.continuent.sequoia.common.exceptions.VirtualDatabaseException;
30  import org.continuent.sequoia.common.jmx.management.DumpInfo;
31  import org.continuent.sequoia.common.jmx.monitoring.backend.BackendStatistics;
32  
33  /**
34   * JMX Interface to remotely manage a Virtual Databases.
35   * 
36   * @author <a HREF="mailto:Emmanuel.Cecchet@inria.fr">Emmanuel Cecchet </a>
37   * @author <A HREF="mailto:Nicolas.Modrzyk@inrialpes.fr">Nicolas Modrzyk </a>
38   * @version 1.0
39   */
40  public interface VirtualDatabaseMBean
41  {
42    //
43    // Methods are organized as follows:
44    // 1. Database backends management
45    // 2. Checkpoint management
46    // 3. Backup management
47    // 4. Virtual database management
48    //  
49  
50    /**
51     * Initializes a virtual database from specified Backend. This has to be
52     * performed prior to any use of the vdb backends, i.e. there are no active
53     * backends in the vdb, and none has a last known checkpoint. This should be
54     * immediately followed by a backup operation on the specified backend. This
55     * resets the recovery log - if any - to an empty state, i.e. drops logtable,
56     * drops checkpoint table, and clears checkpoint names in the dump table.
57     * Finally, sets the last known checkpoint of specified backend to
58     * Initial_empty_recovery_log.
59     * 
60     * @param databaseBackendName the name of the backend to use for
61     *          initialization.
62     * @param force if true, do not perform sanity checks, unconditionally perform
63     *          the initialization   
64     * @throws VirtualDatabaseException if there is an active backend or a backend
65     *           which has a last known checkpoint, or if there is no recovery log
66     *           for this vdb.
67     */
68    void initializeFromBackend(String   databaseBackendName, boolean force)
69        throws VirtualDatabaseException;
70  
71    /**
72     * Performs initializeFromBackend(databaseBackendName, force=false).
73     * This is a convenience method for backward compatibility.
74     * 
75     * @param databaseBackendName the name of the backend to use for
76     *          initialization.
77     * @throws VirtualDatabaseException if there is an active backend or a backend
78     *           which has a last known checkpoint, or if there is no recovery log
79     *           for this vdb.
80     * @deprecated use method with explicit force option.
81     */
82    void initializeFromBackend(String   databaseBackendName)
83        throws VirtualDatabaseException;
84    
85    //
86    // Database backends management
87    //
88  
89    /**
90     * Enables a backend that has been previously added to this virtual database
91     * and that is in the disabled state. The backend is enabled without further
92     * check.
93     * 
94     * @param databaseBackendName The database backend logical name to enable
95     * @exception VirtualDatabaseException in case of communication-related error
96     */
97    void forceEnableBackend(String   databaseBackendName)
98        throws VirtualDatabaseException;
99  
100   /**
101    * Enable the given backend from its last known checkpoint
102    * 
103    * @param backendName the name of the backend to enable
104    * @throws VirtualDatabaseException if enable failed, or if there is no last
105    *           known checkpoint
106    */
107   void enableBackendFromCheckpoint(String   backendName)
108       throws VirtualDatabaseException;
109 
110   /**
111    * Disables a backend that is currently enabled on this virtual database
112    * (without further check).
113    * 
114    * @param databaseBackendName The database backend logical name to enable
115    * @exception VirtualDatabaseException in case of communication-related error
116    */
117   void forceDisableBackend(String   databaseBackendName)
118       throws VirtualDatabaseException;
119 
120   /**
121    * Disables a backend once all the pending write queries are executed. A
122    * checkpoint is inserted in the recovery log. The backend must belong to this
123    * virtual database. <em>Disabling a disabled backend is a no-operation.</em>
124    * 
125    * @param databaseBackendName The database backend logical name to disable
126    * @exception VirtualDatabaseException in case of communication-related error
127    */
128   void disableBackendWithCheckpoint(String   databaseBackendName)
129       throws VirtualDatabaseException;
130 
131   /**
132    * Get a list of all DatabaseBackend names.
133    * 
134    * @return List <code>ArrayList</code> of <code>String</code> representing
135    *         database backend names
136    * @throws VirtualDatabaseException if an error occurs
137    */
138   List   getAllBackendNames() throws VirtualDatabaseException;
139 
140   /**
141    * Add an additionnal backend to the virtual database with connection managers
142    * identical to the backend replicated.
143    * 
144    * @param backendName the backend to replicate and to use parameters from.
145    * @param newBackendName the new backend name.
146    * @param parameters parameters to override or modify when replicating to the
147    *          new backend
148    * @throws VirtualDatabaseException if cannot replicate backend
149    */
150   void replicateBackend(String   backendName, String   newBackendName,
151       Map   parameters) throws VirtualDatabaseException;
152 
153   /**
154    * Transfer the backend to the destinated controller. Note that this does
155    * nothing in a non-distributed environment
156    * 
157    * @param backend the backend to transfer
158    * @param controllerDestination the controller to copy the backend to
159    * @throws VirtualDatabaseException if transfer failed
160    */
161   void transferBackend(String   backend, String   controllerDestination)
162       throws VirtualDatabaseException;
163 
164   //
165   // Checkpoints management
166   //
167 
168   /**
169    * Copies a chunk of the local virtual database recovery log onto a remote
170    * controller's peer virtual database log. The copy is performed from the
171    * checkpoint associated to the specified dump uptil 'now' (a new global
172    * checkpoint). The copy is sent to the specified remote node.
173    * 
174    * @param dumpName the name of the dump (which gives associated checkpoint)
175    *          from which to perform the copy.
176    * @param controllerName the remote controller to send the copy to
177    * @throws VirtualDatabaseException if there is no recovery log, or the
178    *           virtual database is not distributed, or in case of error.
179    */
180   void copyLogFromCheckpoint(String   dumpName, String   controllerName)
181       throws VirtualDatabaseException;
182 
183   /**
184    * Deletes the recovery log (if any) from the begining upto the specified
185    * checkpoint.
186    * 
187    * @param checkpointName the name of the checkpoint upto which to delete the
188    *          recovery log.
189    * @throws VirtualDatabaseException if there is no recovery log, or in case of
190    *           error.
191    */
192   void deleteLogUpToCheckpoint(String   checkpointName)
193       throws VirtualDatabaseException;
194 
195   /**
196    * Sets the last known checkpoint of a backend. This will also update the
197    * value in the recovery log
198    * 
199    * @param backendName backend
200    * @param checkpoint checkpoint
201    * @throws VirtualDatabaseException if fails
202    */
203   void setBackendLastKnownCheckpoint(String   backendName, String   checkpoint)
204       throws VirtualDatabaseException;
205 
206   // 
207   // Backup management
208   //
209 
210   /**
211    * Get the names of the <code>Backupers</code> available from this
212    * <code>BackupManager</code>.
213    * 
214    * @return an (possibly 0-sized) array of <code>String</code> representing
215    *         the name of the <code>Backupers</code>
216    */
217   String  [] getBackuperNames();
218 
219   /**
220    * Get the dump format associated to a given <code>Backuper</code>
221    * 
222    * @param backuperName name associated to a <code>Backuper</code>
223    * @return the dump format associated to a given <code>Backuper</code>
224    */
225   String   getDumpFormatForBackuper(String   backuperName);
226 
227   /**
228    * Create a backup of a specific backend. Note the backend will be disabled if
229    * needed during backup, and will be put back to its previous state after
230    * backup. If there is only one backend left in the system, this operation
231    * will fail when using 'false' as force parameter.
232    * 
233    * @param backendName the target backend to backup
234    * @param login the login to use to connect to the database for the backup
235    *          operation
236    * @param password the password to use to connect to the database for the
237    *          backup operation
238    * @param dumpName the name of the dump to create
239    * @param backuperName the logical name of the backuper to use
240    * @param path the path where to store the dump
241    * @param force use true to force the backup even if there is only one backend
242    *          left in the system.
243    * @param tables the list of tables to backup, null means all tables
244    * @throws VirtualDatabaseException if the backup fails
245    */
246   void backupBackend(String   backendName, String   login, String   password,
247       String   dumpName, String   backuperName, String   path, boolean force,
248       ArrayList   tables) throws VirtualDatabaseException;
249 
250   /**
251    * This is backupBackend(force=true).
252    * 
253    * @see #backupBackend(String backendName, String login, String password,
254    *      String dumpName, String backuperName, String path, boolean force,
255    *      ArrayList tables).
256    * @deprecated use method with explicit option force.
257    */
258   void backupBackend(String   backendName, String   login, String   password,
259       String   dumpName, String   backuperName, String   path, ArrayList   tables)
260       throws VirtualDatabaseException;
261 
262   /**
263    * Get all available dump info for this virtual database
264    * 
265    * @return an array of <code>DumpInfo</code> containing the available dump
266    *         info for this virtual database. Cannot be null but can be empty.
267    * @exception VirtualDatabaseException if we can't retrieve dumps
268    */
269   DumpInfo[] getAvailableDumps() throws VirtualDatabaseException;
270 
271   /**
272    * Update the path of the dump for a given dumpName.
273    * 
274    * @param dumpName name of the dump
275    * @param newPath new path for the dump
276    * @throws VirtualDatabaseException if cannot update the path
277    */
278   void updateDumpPath(String   dumpName, String   newPath)
279       throws VirtualDatabaseException;
280 
281   /**
282    * Delete the dump entry associated to the <code>dumpName</code>.<br />
283    * If <code>keepsFile</code> is false, the dump file is also removed from
284    * the file system.
285    * 
286    * @param dumpName name of the dump entry to remove
287    * @param keepsFile <code>true</code> if the dump should be also removed
288    *          from the file system, <code>false</code> else
289    * @throws VirtualDatabaseException if an exception occured while removing the
290    *           dump entry or the dump file
291    */
292   void deleteDump(String   dumpName, boolean keepsFile)
293       throws VirtualDatabaseException;
294 
295   /**
296    * Rename an existing dump.
297    * 
298    * @param oldDumpName old name of the dump
299    * @param newDumpName new name of the dump
300    * @throws VirtualDatabaseException if the old dump does not exist or the new
301    *           dump name already exists
302    */
303   void renameDump(String   oldDumpName, String   newDumpName)
304       throws VirtualDatabaseException;
305 
306   /**
307    * Restore a dump on a specific backend. The proper Backuper is retrieved
308    * automatically according to the dump format stored in the recovery log dump
309    * table.
310    * <p>
311    * This method disables the backend and leave it disabled after recovery
312    * process. The user has to call the <code>enableBackendFromCheckpoint</code>
313    * after this.
314    * 
315    * @param databaseBackendName the name of the backend to restore
316    * @param login the login to use to connect to the database for the restore
317    *          operation
318    * @param password the password to use to connect to the database for the
319    *          restore operation
320    * @param dumpName the name of the dump to restore
321    * @param tables the list of tables to restore, null means all tables
322    * @throws VirtualDatabaseException if the restore operation failed
323    */
324   void restoreDumpOnBackend(String   databaseBackendName, String   login,
325       String   password, String   dumpName, ArrayList   tables)
326       throws VirtualDatabaseException;
327 
328   /**
329    * Transfer specified dump over to specified vdb's controller, making it
330    * available for restore operation. The local dump is not deleted and still
331    * available for local restore operations. This operation wants a recovery log
332    * to be enabled for the vdb (stores dump info, and meaning less otherwize as
333    * no restore is possible without a recovery log). It is pointless (and an
334    * error) to use this on a 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    * @param noCopy specifies whether or not to actually copy the dump. Default:
340    *          false. No-copy is a useful option in case of NFS/shared dumps.
341    * @throws VirtualDatabaseException in case of error
342    */
343   void transferDump(String   dumpName, String   remoteControllerName, boolean noCopy)
344       throws VirtualDatabaseException;
345 
346   //
347   // Administration/Monitoring functions
348   //
349 
350   /**
351    * Return information about the specified backend.
352    * 
353    * @param backendName the backend logical name
354    * @return String the backend information
355    * @throws VirtualDatabaseException if an error occurs
356    */
357   String   getBackendInformation(String   backendName)
358       throws VirtualDatabaseException;
359 
360   // TODO: Should return a BackendInfo
361 
362   /**
363    * Retrieves this <code>VirtualDatabase</code> object in xml format
364    * 
365    * @return xml formatted string that conforms to sequoia.dtd
366    */
367   String   getXml();
368 
369   //
370   // Virtual database management
371   //
372 
373   // FIXME this method is useless: if a jmx client can connect
374   // to the vdb mbean it won't call this method and can still
375   // manage the vdb because the other mbean's method do not
376   // check that their caller has been authenticated or not...
377   /**
378    * Authenticate a user for a given virtual database
379    * 
380    * @param adminLogin username
381    * @param adminPassword password
382    * @return true if authentication is a success, false otherwise
383    * @throws VirtualDatabaseException if database does not exists
384    */
385   boolean checkAdminAuthentication(String   adminLogin, String   adminPassword)
386       throws VirtualDatabaseException;
387 
388   // TODO rename it to getName()
389   /**
390    * Gets the virtual database name to be used by the client (Sequoia driver)
391    * 
392    * @return the virtual database name
393    */
394   String   getVirtualDatabaseName();
395 
396   // TODO rename it to isRecoveryLogDefined() so that it is considered as an
397   // attribute
398   // rather than an operation
399   /**
400    * Indicate if there is a recovery log defined for this virtual database
401    * 
402    * @return <code>true</code> if the recovery log is defined and can be
403    *         accessed, <code>false</code> otherwise
404    */
405   boolean hasRecoveryLog();
406 
407   // TODO rename it to isResultCacheDefined() so that it is considered as an
408   // attribute
409   // rather than an operation
410   /**
411    * Indicate if there is a result cache defined for this virtual database
412    * 
413    * @return <code>true</code> if a request cache is defined and can be
414    *         accessed, <code>false</code> otherwise
415    */
416   boolean hasResultCache();
417 
418   /**
419    * Tells whether this database is distributed or not
420    * 
421    * @return <code>true</code> if the database is distributed among multiple
422    *         controllers <code>false</code> if it exists on a single
423    *         controller only
424    */
425   boolean isDistributed();
426 
427   /**
428    * Shutdown this virtual database. Finish all threads and stop connection to
429    * backends
430    * 
431    * @param level Constants.SHUTDOWN_WAIT, Constants.SHUTDOWN_SAFE or
432    *          Constants.SHUTDOWN_FORCE
433    * @throws VirtualDatabaseException if an error occurs
434    */
435   void shutdown(int level) throws VirtualDatabaseException;
436 
437   // TODO rename it to getOwningController() so that it is considered as an
438   // attribute
439   // rather than an operation
440   /**
441    * Name of the controller owning this virtual database
442    * 
443    * @return url of the controller
444    */
445   String   viewOwningController();
446 
447   /**
448    * Retrieves an array of statistics of the given backend for this virtual
449    * database
450    * 
451    * @param backendName name of the backend
452    * @return <code>BackendStatistics[]</code> of formatted data for all
453    *         backends or <code>null</code> if the backend does not exist
454    * @throws Exception if fails
455    */
456   BackendStatistics getBackendStatistics(String   backendName) throws Exception  ;
457 
458   // TODO: Should monitoring be in a separate interface?
459 
460   // TODO rename it to getControllers() so that it is considered as an attribute
461   // rather than an operation
462   /**
463    * Return the list of controllers defining this virtual database. If the
464    * database is not distributed this returns the same as
465    * <code>viewOwningController</code> otherwise returns an array of
466    * controller configuring this <code>DistributedVirtualDatabase</code>
467    * 
468    * @return <code>String[]</code> of controller names.
469    */
470   String  [] viewControllerList();
471 
472   // TODO rename to getWorkerThreadsSize()
473   /**
474    * Returns the currentNbOfThreads.
475    * 
476    * @return int
477    */
478   int getCurrentNbOfThreads();
479 
480   // TODO add a isActiveMonitoring() to know the current state of monitoring
481   // activation
482 
483   // TODO rename it to setActiveMonitoring() so that it is considered as an
484   // attribute
485   // rather than an operation
486   /**
487    * If a monitoring section exists, we can set the monitoring on or off by
488    * calling this method. If monitoring is not defined we throw an exception.
489    * 
490    * @param active should set the monitor to on or off
491    * @throws VirtualDatabaseException if there is no monitor.
492    */
493   void setMonitoringToActive(boolean active) throws VirtualDatabaseException;
494 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags