org.objectweb.cjdbc.common.jmx.mbeans
Interface VirtualDatabaseMBean

All Known Implementing Classes:

VirtualDatabase

public interface VirtualDatabaseMBean

JMX Interface to remotely manage a Virtual Databases.

Version:

1.0

Author:

Emmanuel Cecchet , Nicolas Modrzyk

Method Summary

void	backupBackend(java.lang.String backendName, java.lang.String login, java.lang.String password, java.lang.String dumpName, java.lang.String backuperName, java.lang.String path, java.util.ArrayList tables) Create a backup of a specific backend.
boolean	checkAdminAuthentication(java.lang.String adminLogin, java.lang.String adminPassword) Authenticate a user for a given virtual database
void	cleanMonitoringData() Clean data collected by the current monitoring system, to avoid memory problems.
void	copyDump(java.lang.String dumpName, java.lang.String remoteControllerName) Copy a local dump over to a remote member of this distributed vdb, making it available for restore operation.
void	copyLogFromCheckpoint(java.lang.String dumpName, java.lang.String controllerName) Copies a chunk of the local virtual database recovery log onto a remote controller's peer virtual database log.
void	deleteLogUpToCheckpoint(java.lang.String checkpointName) Deletes the recovery log (if any) from the begining upto the specified checkpoint.
void	disableAllBackends() Disable all backends for this virtual database
void	disableAllBackendsWithCheckpoint(java.lang.String checkpoint) Disable all backends and store a checkpoint
void	disableBackendWithCheckpoint(java.lang.String databaseBackendName) Disables a backend once all the pending write queries are executed.
void	enableAllBackends() Enable all the backends without any check.
void	enableAllBackendsFromCheckpoint() Enable all backends from their last known states that has been recorded in the recovery log, and enable only the backends which where properly disabled.
void	enableBackendFromCheckpoint(java.lang.String backendName) Enable the given backend from its last known checkpoint
void	forceDisableBackend(java.lang.String databaseBackendName) Disables a backend that is currently enabled on this virtual database (without further check).
void	forceEnableBackend(java.lang.String databaseBackendName) Enables a backend that has been previously added to this virtual database and that is in the disabled state.
java.util.ArrayList	getAllBackendNames() Get a list of all DatabaseBackend names.
DumpInfo[]	getAvailableDumps() Get all available dump info for this virtual database
java.lang.String	getBackendInformation(java.lang.String backendName) Return information about the specified backend.
java.lang.String	getBackendSchema(java.lang.String backendName) The getXml() method does not return the schema if it is not static anymore, to avoid confusion between static and dynamic schema.
java.lang.String	getBackendState(java.lang.String backendName) Return the state of a given database backend
BackendStatistics	getBackendStatistics(java.lang.String backendName) Retrieves an array of statistics of the given backend for this virtual database
java.lang.String[]	getBackuperNames() Get the names of the Backupers available from this BackupManager.
int	getCurrentNbOfThreads() Returns the currentNbOfThreads.
java.lang.String	getDumpFormatForBackuper(java.lang.String backuperName) Get the dump format associated to a given Backuper
java.lang.String	getVirtualDatabaseName() Gets the virtual database name to be used by the client (C-JDBC driver)
java.lang.String	getXml() Retrieves this VirtualDatabase object in xml format
boolean	hasRecoveryLog() Indicate if there is a recovery log defined for this virtual database
boolean	hasResultCache() Indicate if there is a result cache defined for this virtual database
boolean	isDistributed() Tells whether this database is distributed or not
void	removeBackend(java.lang.String backend) Remove a backend from the virtual database list.
void	removeCheckpoint(java.lang.String checkpoint) Disable all backends and store a checkpoint
boolean	removeDump(java.lang.String dumpName) Remove a dump from the controller repository
void	replicateBackend(java.lang.String backendName, java.lang.String newBackendName, java.util.Map parameters) Add an additionnal backend to the virtual database with connection managers identical to the backend replicated.
void	restoreDumpOnBackend(java.lang.String databaseBackendName, java.lang.String login, java.lang.String password, java.lang.String dumpName, java.util.ArrayList tables) Restore a dump on a specific backend.
java.lang.String[][]	retrieveBackendsData() Retrieves an array of data on the backends for this virtual database
void	setBackendLastKnownCheckpoint(java.lang.String backendName, java.lang.String checkpoint) Sets the last known checkpoint of a backend.
void	setMonitoringToActive(boolean active) If a monitoring section exists, we can set the monitoring on or off by calling this method.
void	shutdown(int level) Shutdown this virtual database.
void	transferBackend(java.lang.String backend, java.lang.String controllerDestination) Transfer the backend to the destinated controller.
void	transferDump(java.lang.String dumpName, java.lang.String remoteControllerName, boolean noCopy) Transfer specified dump over to specified vdb's controller, making it available for restore operation.
void	updateDumpPath(java.lang.String dumpName, java.lang.String newPath) Update the path of the dump for a given dumpName.
java.lang.String[]	viewBackendInformation(java.lang.String backendName) Returns an array of information on this backend The method above is not used at the moment ...
java.util.ArrayList	viewCheckpointNames() Returns an array of names of all the checkpoint available in the recovery log of this virtual dabase.
java.lang.String[]	viewControllerList() Return the list of controllers defining this virtual database.
java.util.Hashtable	viewGroupBackends() Returns a mapping of controller jmx names with their backends.
java.lang.String	viewOwningController() Name of the controller owning this virtual database

Method Detail

forceEnableBackend

public void forceEnableBackend(java.lang.String databaseBackendName)
                        throws VirtualDatabaseException

Enables a backend that has been previously added to this virtual database and that is in the disabled state. The backend is enabled without further check.

Parameters:

databaseBackendName - The database backend logical name to enable

Throws:

VirtualDatabaseException - in case of communication-related error

enableBackendFromCheckpoint

public void enableBackendFromCheckpoint(java.lang.String backendName)
                                 throws VirtualDatabaseException

Enable the given backend from its last known checkpoint

Parameters:

backendName - the name of the backend to enable

Throws:

VirtualDatabaseException - if enable failed, or if there is no last known checkpoint

enableAllBackends

public void enableAllBackends()
                       throws VirtualDatabaseException

Enable all the backends without any check.

Throws:

VirtualDatabaseException - if fails

enableAllBackendsFromCheckpoint

public void enableAllBackendsFromCheckpoint()
                                     throws VirtualDatabaseException

Enable all backends from their last known states that has been recorded in the recovery log, and enable only the backends which where properly disabled.

Throws:

VirtualDatabaseException - if fails

forceDisableBackend

public void forceDisableBackend(java.lang.String databaseBackendName)
                         throws VirtualDatabaseException

Disables a backend that is currently enabled on this virtual database (without further check).

Parameters:

databaseBackendName - The database backend logical name to enable

Throws:

VirtualDatabaseException - in case of communication-related error

disableBackendWithCheckpoint

public void disableBackendWithCheckpoint(java.lang.String databaseBackendName)
                                  throws VirtualDatabaseException

Disables a backend once all the pending write queries are executed. A checkpoint is inserted in the recovery log. The backend must belong to this virtual database and be in the enabled state.

Parameters:

databaseBackendName - The database backend logical name to disable

Throws:

VirtualDatabaseException - in case of communication-related error

disableAllBackends

public void disableAllBackends()
                        throws VirtualDatabaseException

Disable all backends for this virtual database

Throws:

VirtualDatabaseException - if fails

disableAllBackendsWithCheckpoint

public void disableAllBackendsWithCheckpoint(java.lang.String checkpoint)
                                      throws VirtualDatabaseException

Disable all backends and store a checkpoint

Parameters:

checkpoint - the name of the checkpoitn

Throws:

VirtualDatabaseException - if fails

getAllBackendNames

public java.util.ArrayList getAllBackendNames()
                                       throws VirtualDatabaseException

Get a list of all DatabaseBackend names.

Returns:

ArrayList ArrayList of String representing database backend names

Throws:

VirtualDatabaseException - if an error occurs

replicateBackend

public void replicateBackend(java.lang.String backendName,
                             java.lang.String newBackendName,
                             java.util.Map parameters)
                      throws VirtualDatabaseException

Add an additionnal backend to the virtual database with connection managers identical to the backend replicated.

Parameters:

backendName - the backend to replicate and to use parameters from.

newBackendName - the new backend name.

parameters - parameters to override or modify when replicating to the new backend

Throws:

VirtualDatabaseException - if cannot replicate backend

removeBackend

public void removeBackend(java.lang.String backend)
                   throws VirtualDatabaseException

Remove a backend from the virtual database list. Do not check whether it is enabled or not, and do not perform backup operation

Parameters:

backend - the name of the backend to remove

Throws:

VirtualDatabaseException - if the backend does not exist

transferBackend

public void transferBackend(java.lang.String backend,
                            java.lang.String controllerDestination)
                     throws VirtualDatabaseException

Transfer the backend to the destinated controller. Note that this does nothing in a non-distributed environment

Parameters:

backend - the backend to transfer

controllerDestination - the controller to copy the backend to

Throws:

VirtualDatabaseException - if transfer failed

copyLogFromCheckpoint

public void copyLogFromCheckpoint(java.lang.String dumpName,
                                  java.lang.String controllerName)
                           throws VirtualDatabaseException

Copies a chunk of the local virtual database recovery log onto a remote controller's peer virtual database log. The copy is performed from the checkpoint associated to the specified dump uptil 'now' (a new global checkpoint). The copy is sent to the specified remote node.

Parameters:

dumpName - the name of the dump (which gives associated checkpoint) from which to perform the copy.

controllerName - the remote controller to send the copy to

Throws:

VirtualDatabaseException - if there is no recovery log, or the virtual database is not distributed, or in case of error.

deleteLogUpToCheckpoint

public void deleteLogUpToCheckpoint(java.lang.String checkpointName)
                             throws VirtualDatabaseException

Deletes the recovery log (if any) from the begining upto the specified checkpoint.

Parameters:

checkpointName - the name of the checkpoint upto which to delete the recovery log.

Throws:

VirtualDatabaseException - if there is no recovery log, or in case of error.

removeCheckpoint

public void removeCheckpoint(java.lang.String checkpoint)
                      throws VirtualDatabaseException

Disable all backends and store a checkpoint

Parameters:

checkpoint - the name of the checkpoitn

Throws:

VirtualDatabaseException - if fails

setBackendLastKnownCheckpoint

public void setBackendLastKnownCheckpoint(java.lang.String backendName,
                                          java.lang.String checkpoint)
                                   throws VirtualDatabaseException

Sets the last known checkpoint of a backend. This will also update the value in the recovery log

Parameters:

backendName - backend

checkpoint - checkpoint

Throws:

VirtualDatabaseException - if fails

viewCheckpointNames

public java.util.ArrayList viewCheckpointNames()

Returns an array of names of all the checkpoint available in the recovery log of this virtual dabase.

Returns:

ArrayList of checkpoint names. Can be empty

getBackuperNames

public java.lang.String[] getBackuperNames()

Get the names of the Backupers available from this BackupManager.

Returns:

an (possibly 0-sized) array of String representing the name of the Backupers

getDumpFormatForBackuper

public java.lang.String getDumpFormatForBackuper(java.lang.String backuperName)

Get the dump format associated to a given Backuper

Parameters:

backuperName - name associated to a Backuper

Returns:

the dump format associated to a given Backuper

backupBackend

public void backupBackend(java.lang.String backendName,
                          java.lang.String login,
                          java.lang.String password,
                          java.lang.String dumpName,
                          java.lang.String backuperName,
                          java.lang.String path,
                          java.util.ArrayList tables)
                   throws VirtualDatabaseException

Create a backup of a specific backend. Note the backend will be disabled if needed during backup, and will be put back to its previous state after backup.

Parameters:

backendName - the target backend to backup

login - the login to use to connect to the database for the backup operation

password - the password to use to connect to the database for the backup operation

dumpName - the name of the dump to create

backuperName - the logical name of the backuper to use

path - the path where to store the dump

tables - the list of tables to backup, null means all tables

Throws:

VirtualDatabaseException - if the backup fails

getAvailableDumps

public DumpInfo[] getAvailableDumps()
                             throws VirtualDatabaseException

Get all available dump info for this virtual database

Returns:

an array of DumpInfo containing the available dump info for this virtual database. Cannot be null but can be empty.

Throws:

VirtualDatabaseException - if cannot retrieve dump informations

updateDumpPath

public void updateDumpPath(java.lang.String dumpName,
                           java.lang.String newPath)
                    throws VirtualDatabaseException

Update the path of the dump for a given dumpName.

Parameters:

dumpName - name of the dump

newPath - new path for the dump

Throws:

VirtualDatabaseException - if cannot update the path

removeDump

public boolean removeDump(java.lang.String dumpName)

Remove a dump from the controller repository

Parameters:

dumpName - name of the dump to remove

Returns:

true if the dump was removed, false otherwise

restoreDumpOnBackend

public void restoreDumpOnBackend(java.lang.String databaseBackendName,
                                 java.lang.String login,
                                 java.lang.String password,
                                 java.lang.String dumpName,
                                 java.util.ArrayList tables)
                          throws VirtualDatabaseException

Restore a dump on a specific backend. The proper Backuper is retrieved automatically according to the dump format stored in the recovery log dump table.

This method disables the backend and leave it disabled after recovery process. The user has to call the enableBackendFromCheckpoint after this.

Parameters:

databaseBackendName - the name of the backend to restore

login - the login to use to connect to the database for the restore operation

password - the password to use to connect to the database for the restore operation

dumpName - the name of the dump to restore

tables - the list of tables to restore, null means all tables

Throws:

VirtualDatabaseException - if the restore operation failed

copyDump

public void copyDump(java.lang.String dumpName,
                     java.lang.String remoteControllerName)
              throws VirtualDatabaseException

Copy a local dump over to a remote member of this distributed vdb, making it available for restore operation. Wants a recovery log to be enabled (stores dump info, and meaning less otherwize as no restore is possible without a recovery log). It is pointless (and an error) to use this on a non-distributed virtual db.

Parameters:

dumpName - the name of the dump to copy. Should exist locally, and not remotely.

remoteControllerName - the remote controller to talk to.

Throws:

VirtualDatabaseException - in case of error.

transferDump

public void transferDump(java.lang.String dumpName,
                         java.lang.String remoteControllerName,
                         boolean noCopy)
                  throws VirtualDatabaseException

Transfer specified dump over to specified vdb's controller, making it available for restore operation. The local dump is not deleted and still available for local restore operations. This operation wants a recovery log to be enabled for the vdb (stores dump info, and meaning less otherwize as no restore is possible without a recovery log). It is pointless (and an error) to use this on a non-distributed virtual db.

Parameters:

dumpName - the name of the dump to copy. Should exist locally, and not remotely.

remoteControllerName - the remote controller to talk to.

noCopy - specifies whether or not to actually copy the dump. Default: false. No-copy is a useful option in case of NFS/shared dumps.

Throws:

VirtualDatabaseException - in case of error

getBackendInformation

public java.lang.String getBackendInformation(java.lang.String backendName)
                                       throws VirtualDatabaseException

Return information about the specified backend.

Parameters:

backendName - the backend logical name

Returns:

String the backend information

Throws:

VirtualDatabaseException - if an error occurs

getBackendSchema

public java.lang.String getBackendSchema(java.lang.String backendName)
                                  throws VirtualDatabaseException

The getXml() method does not return the schema if it is not static anymore, to avoid confusion between static and dynamic schema. This method returns a static view of the schema, whatever the dynamic precision is.

Parameters:

backendName - the name of the backend to get the schema from

Returns:

an xml formatted string

Throws:

VirtualDatabaseException - if an error occurs while accessing the backend, or if the backend does not exist.

getBackendState

public java.lang.String getBackendState(java.lang.String backendName)
                                 throws VirtualDatabaseException

Return the state of a given database backend

Parameters:

backendName - the name of the backend

Returns:

String description of the database backend

Throws:

VirtualDatabaseException - if fails

getXml

public java.lang.String getXml()

Retrieves this VirtualDatabase object in xml format

Returns:

xml formatted string that conforms to c-jdbc.dtd

checkAdminAuthentication

public boolean checkAdminAuthentication(java.lang.String adminLogin,
                                        java.lang.String adminPassword)
                                 throws VirtualDatabaseException

Authenticate a user for a given virtual database

Parameters:

adminLogin - username

adminPassword - password

Returns:

true if authentication is a success, false otherwise

Throws:

VirtualDatabaseException - if database does not exists

getVirtualDatabaseName

public java.lang.String getVirtualDatabaseName()

Gets the virtual database name to be used by the client (C-JDBC driver)

Returns:

the virtual database name

hasRecoveryLog

public boolean hasRecoveryLog()

Indicate if there is a recovery log defined for this virtual database

Returns:

true if the recovery log is defined and can be accessed, false otherwise

hasResultCache

public boolean hasResultCache()

Indicate if there is a result cache defined for this virtual database

Returns:

true if a request cache is defined and can be accessed, false otherwise

isDistributed

public boolean isDistributed()

Tells whether this database is distributed or not

Returns:

true if the database is distributed among multiple controllers false if it exists on a single controller only

shutdown

public void shutdown(int level)
              throws VirtualDatabaseException

Shutdown this virtual database. Finish all threads and stop connection to backends

Parameters:

level - Constants.SHUTDOWN_WAIT, Constants.SHUTDOWN_SAFE or Constants.SHUTDOWN_FORCE

Throws:

VirtualDatabaseException - if an error occurs

viewBackendInformation

public java.lang.String[] viewBackendInformation(java.lang.String backendName)
                                          throws VirtualDatabaseException

Returns an array of information on this backend The method above is not used at the moment ... This one is by the GUI.

Parameters:

backendName - the name of the backend

Returns:

String[]

Throws:

VirtualDatabaseException - if an error occurs

viewGroupBackends

public java.util.Hashtable viewGroupBackends()
                                      throws VirtualDatabaseException

Returns a mapping of controller jmx names with their backends. Note the method is only useful in distributed environment

Returns:

Hashtable of controllerName --> ArrayList[BackendInfo]

Throws:

VirtualDatabaseException - if cannot return the result

viewOwningController

public java.lang.String viewOwningController()

Name of the controller owning this virtual database

Returns:

url of the controller

retrieveBackendsData

public java.lang.String[][] retrieveBackendsData()
                                          throws java.lang.Exception

Retrieves an array of data on the backends for this virtual database

Returns:

String[][] of formatted data for all backends

Throws:

java.lang.Exception - if fails

getBackendStatistics

public BackendStatistics getBackendStatistics(java.lang.String backendName)
                                       throws java.lang.Exception

Retrieves an array of statistics of the given backend for this virtual database

Parameters:

backendName - name of the backend

Returns:

BackendStatistics[] of formatted data for all backends or null if the backend does not exist

Throws:

java.lang.Exception - if fails

viewControllerList

public java.lang.String[] viewControllerList()

Return the list of controllers defining this virtual database. If the database is not distributed this returns the same as viewOwningController otherwise returns an array of controller configuring this DistributedVirtualDatabase

Returns:

String[] of controller names.

getCurrentNbOfThreads

public int getCurrentNbOfThreads()

Returns the currentNbOfThreads.

Returns:

int

cleanMonitoringData

public void cleanMonitoringData()
                         throws VirtualDatabaseException

Clean data collected by the current monitoring system, to avoid memory problems. Monitor does not have to be active.

Throws:

VirtualDatabaseException - if there is no monitor.

setMonitoringToActive

public void setMonitoringToActive(boolean active)
                           throws VirtualDatabaseException

If a monitoring section exists, we can set the monitoring on or off by calling this method. If monitoring is not defined we throw an exception.

Parameters:

active - should set the monitor to on or off

Throws:

VirtualDatabaseException - if there is no monitor.