00001 /** 00002 * C-JDBC: Clustered JDBC. 00003 * Copyright (C) 2002-2004 French National Institute For Research In Computer 00004 * Science And Control (INRIA). 00005 * Contact: c-jdbc@objectweb.org 00006 * 00007 * This library is free software; you can redistribute it and/or modify it 00008 * under the terms of the GNU Lesser General Public License as published by the 00009 * Free Software Foundation; either version 2.1 of the License, or any later 00010 * version. 00011 * 00012 * This library is distributed in the hope that it will be useful, but WITHOUT 00013 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 00014 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License 00015 * for more details. 00016 * 00017 * You should have received a copy of the GNU Lesser General Public License 00018 * along with this library; if not, write to the Free Software Foundation, 00019 * Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. 00020 * 00021 * Initial developer(s): Emmanuel Cecchet. 00022 * Contributor(s): Nicolas Modrzyk. 00023 */ 00024 00025 package org.objectweb.cjdbc.common.jmx.mbeans; 00026 00027 import java.io.File; 00028 import java.util.ArrayList; 00029 import java.util.Hashtable; 00030 import java.util.Map; 00031 00032 import org.objectweb.cjdbc.common.exceptions.BackupException; 00033 import org.objectweb.cjdbc.common.exceptions.OctopusException; 00034 import org.objectweb.cjdbc.common.exceptions.VirtualDatabaseException; 00035 00036 /** 00037 * JMX Interface to remotely manage a Virtual Databases. 00038 * 00039 * @author <a href="mailto:Emmanuel.Cecchet@inria.fr">Emmanuel Cecchet </a> 00040 * @author <A href="mailto:Nicolas.Modrzyk@inrialpes.fr">Nicolas Modrzyk </a> 00041 * @version 1.0 00042 */ 00043 public interface VirtualDatabaseMBean 00044 { 00045 // 00046 // Methods are organized as follows: 00047 // 1. Database backends management 00048 // 2. Checkpoint management 00049 // 3. Backup management 00050 // 4. Virtual database management 00051 // 00052 00053 // 00054 // Database backends management 00055 // 00056 00057 /** 00058 * Enables a backend that has been previously added to this virtual database 00059 * and that is in the disabled state. The backend is enabled without further 00060 * check. 00061 * 00062 * @param databaseBackendName The database backend logical name to enable 00063 * @exception VirtualDatabaseException in case of communication-related error 00064 */ 00065 void enableBackend(String databaseBackendName) 00066 throws VirtualDatabaseException; 00067 00068 /** 00069 * Enable the given backend from its last known checkpoint 00070 * 00071 * @param backendName the name of the backend to enable 00072 * @throws VirtualDatabaseException if enable failed, or if there is no last 00073 * known checkpoint 00074 */ 00075 void enableBackendFromCheckpoint(String backendName) 00076 throws VirtualDatabaseException; 00077 00078 /** 00079 * Enable all the backends without any check. 00080 * 00081 * @throws VirtualDatabaseException if fails 00082 */ 00083 void enableAllBackends() throws VirtualDatabaseException; 00084 00085 /** 00086 * Enable all backends from their last known states that has been recorded in 00087 * the recovery log, and enable only the backends which where properly 00088 * disabled. 00089 * 00090 * @throws VirtualDatabaseException if fails 00091 */ 00092 void enableAllBackendsFromCheckpoint() throws VirtualDatabaseException; 00093 00094 /** 00095 * Disables a backend that is currently enabled on this virtual database 00096 * (without further check). 00097 * 00098 * @param databaseBackendName The database backend logical name to enable 00099 * @exception VirtualDatabaseException in case of communication-related error 00100 */ 00101 void disableBackend(String databaseBackendName) 00102 throws VirtualDatabaseException; 00103 00104 /** 00105 * Disables a backend once all the pending write queries are executed. A 00106 * checkpoint is inserted in the recovery log. The backend must belong to this 00107 * virtual database and be in the enabled state. 00108 * 00109 * @param databaseBackendName The database backend logical name to disable 00110 * @param checkpointName the checkpoint name to store 00111 * @exception VirtualDatabaseException in case of communication-related error 00112 */ 00113 void disableBackendWithCheckpoint(String databaseBackendName, 00114 String checkpointName) throws VirtualDatabaseException; 00115 00116 /** 00117 * Disable all backends for this virtual database 00118 * 00119 * @throws VirtualDatabaseException if fails 00120 */ 00121 void disableAllBackends() throws VirtualDatabaseException; 00122 00123 /** 00124 * Disable all backends and store a checkpoint 00125 * 00126 * @param checkpoint the name of the checkpoitn 00127 * @throws VirtualDatabaseException if fails 00128 */ 00129 void disableAllBackendsWithCheckpoint(String checkpoint) 00130 throws VirtualDatabaseException; 00131 00132 /** 00133 * Get a list of all DatabaseBackend names. 00134 * 00135 * @return ArrayList <code>ArrayList</code> of <code>String</code> 00136 * representing database backend names 00137 * @throws VirtualDatabaseException if an error occurs 00138 */ 00139 ArrayList getAllBackendNames() throws VirtualDatabaseException; 00140 00141 /** 00142 * Add an additionnal backend to the virtual database with connection managers 00143 * identical to the backend replicated. 00144 * 00145 * @param backendName the backend to replicate and to use parameters from. 00146 * @param newBackendName the new backend name. 00147 * @param parameters parameters to override or modify when replicating to the 00148 * new backend 00149 * @throws VirtualDatabaseException if cannot replicate backend 00150 */ 00151 void replicateBackend(String backendName, String newBackendName, 00152 Map parameters) throws VirtualDatabaseException; 00153 00154 /** 00155 * Remove a backend from the virtual database list. Do not check whether it is 00156 * enabled or not, and do not perform backup operation 00157 * 00158 * @param backend the name of the backend to remove 00159 * @throws VirtualDatabaseException if the backend does not exist 00160 */ 00161 void removeBackend(String backend) throws VirtualDatabaseException; 00162 00163 /** 00164 * Transfer the backend to the destinated controller. Note that this does 00165 * nothing in a non-distributed environment 00166 * 00167 * @param backend the backend to transfer 00168 * @param controllerDestination the controller to copy the backend to 00169 * @throws VirtualDatabaseException if transfer failed 00170 */ 00171 void transferBackend(String backend, String controllerDestination) 00172 throws VirtualDatabaseException; 00173 00174 // 00175 // Checkpoints management 00176 // 00177 00178 /** 00179 * Disable all backends and store a checkpoint 00180 * 00181 * @param checkpoint the name of the checkpoitn 00182 * @throws VirtualDatabaseException if fails 00183 */ 00184 void removeCheckpoint(String checkpoint) throws VirtualDatabaseException; 00185 00186 /** 00187 * Sets the last known checkpoint of a backend. This will also update the 00188 * value in the recovery log 00189 * 00190 * @param backendName backend 00191 * @param checkpoint checkpoint 00192 * @throws VirtualDatabaseException if fails 00193 */ 00194 void setBackendLastKnownCheckpoint(String backendName, String checkpoint) 00195 throws VirtualDatabaseException; 00196 00197 /** 00198 * Returns an array of names of all the checkpoint available in the recovery 00199 * log of this virtual dabase. 00200 * 00201 * @return <code>ArrayList</code> of checkpoint names. Can be empty 00202 */ 00203 ArrayList viewCheckpointNames(); 00204 00205 // 00206 // Backup management 00207 // 00208 00209 /** 00210 * Create a backup of a specific backend. Note the backend will be disabled 00211 * during backup, and will be put back to its previous state after backup. 00212 * 00213 * @param backendName to backup 00214 * @param checkpointName to associate this backup with 00215 * @param tables to copy or null if copy all 00216 * @throws VirtualDatabaseException if fails 00217 */ 00218 void backupBackendWithCheckpoint(String backendName, String checkpointName, 00219 ArrayList tables) throws VirtualDatabaseException; 00220 00221 /** 00222 * Get all available dump files for this virtual database 00223 * 00224 * @return an array of <code>File</code> containing the available files. 00225 * Cannot be null but can be empty. 00226 */ 00227 File[] getAvailableDumpFiles(); 00228 00229 /** 00230 * Delete a dump file from the controller repository 00231 * 00232 * @param dumpFile the file reference of the dumpFile 00233 * @return true deletion was completed, false otherwise 00234 */ 00235 boolean removeDumpFile(File dumpFile); 00236 00237 /** 00238 * Recopy all the data of a previous dump recorded by octopus into the named 00239 * backend. This disables the backend and leave it disabled after recovery 00240 * process. The user has to call the <code>enableBackendFromCheckpoint</code> 00241 * after this. 00242 * 00243 * @param databaseBackendName the name of the backend to restore 00244 * @param checkpointName the name of the checkpoint that has a dump 00245 * @throws VirtualDatabaseException if cannot access the backend from its name 00246 * @throws OctopusException if backup failed while in octopus mode 00247 * @throws BackupException if backup failed for other reasons 00248 */ 00249 void restoreDumpOnBackend(String databaseBackendName, String checkpointName) 00250 throws VirtualDatabaseException, BackupException, OctopusException; 00251 00252 // 00253 // Administration/Monitoring functions 00254 // 00255 00256 /** 00257 * Return information about the specified backend. 00258 * 00259 * @param backendName the backend logical name 00260 * @return String the backend information 00261 * @throws VirtualDatabaseException if an error occurs 00262 */ 00263 String getBackendInformation(String backendName) 00264 throws VirtualDatabaseException; 00265 00266 /** 00267 * The getXml() method does not return the schema if it is not static anymore, 00268 * to avoid confusion between static and dynamic schema. This method returns a 00269 * static view of the schema, whatever the dynamic precision is. 00270 * 00271 * @param backendName the name of the backend to get the schema from 00272 * @return an xml formatted string 00273 * @throws VirtualDatabaseException if an error occurs while accessing the 00274 * backend, or if the backend does not exist. 00275 */ 00276 String getBackendSchema(String backendName) throws VirtualDatabaseException; 00277 00278 /** 00279 * Return the state of a given database backend 00280 * 00281 * @param backendName the name of the backend 00282 * @return <code>String</code> description of the database backend 00283 * @throws VirtualDatabaseException if fails 00284 */ 00285 String getBackendState(String backendName) throws VirtualDatabaseException; 00286 00287 /** 00288 * Retrieves this <code>VirtualDatabase</code> object in xml format 00289 * 00290 * @return xml formatted string that conforms to c-jdbc.dtd 00291 */ 00292 String getXml(); 00293 00294 // 00295 // Virtual database management 00296 // 00297 00298 /** 00299 * Authenticate a user for a given virtual database 00300 * 00301 * @param adminLogin username 00302 * @param adminPassword password 00303 * @return true if authentication is a success, false otherwise 00304 * @throws VirtualDatabaseException if database does not exists 00305 */ 00306 boolean checkAdminAuthentication(String adminLogin, String adminPassword) 00307 throws VirtualDatabaseException; 00308 00309 /** 00310 * Gets the virtual database name to be used by the client (C-JDBC driver) 00311 * 00312 * @return the virtual database name 00313 */ 00314 String getVirtualDatabaseName(); 00315 00316 /** 00317 * Indicate if there is a recovery log defined for this virtual database 00318 * 00319 * @return <code>true</code> if the recovery log is defined and can be 00320 * accessed, <code>false</code> otherwise 00321 */ 00322 boolean hasRecoveryLog(); 00323 00324 /** 00325 * Indicate if there is a result cache defined for this virtual database 00326 * 00327 * @return <code>true</code> if a request cache is defined and can be 00328 * accessed, <code>false</code> otherwise 00329 */ 00330 boolean hasResultCache(); 00331 00332 /** 00333 * Tells whether this database is distributed or not 00334 * 00335 * @return <code>true</code> if the database is distributed among multiple 00336 * controllers <code>false</code> if it exists on a single 00337 * controller only 00338 */ 00339 boolean isDistributed(); 00340 00341 /** 00342 * Shutdown this virtual database. Finish all threads and stop connection to 00343 * backends 00344 * 00345 * @param level Constants.SHUTDOWN_WAIT, Constants.SHUTDOWN_SAFE or 00346 * Constants.SHUTDOWN_FORCE 00347 * @throws VirtualDatabaseException if an error occurs 00348 */ 00349 void shutdown(int level) throws VirtualDatabaseException; 00350 00351 /** 00352 * Returns an array of information on this backend The method above is not 00353 * used at the moment ... This one is by the GUI. 00354 * 00355 * @param backendName the name of the backend 00356 * @return <code>String[]</code> 00357 * @throws VirtualDatabaseException if an error occurs 00358 */ 00359 String[] viewBackendInformation(String backendName) 00360 throws VirtualDatabaseException; 00361 00362 /** 00363 * Returns a mapping of controller jmx names with their backends Note the 00364 * method is only useful in distributed environment 00365 * 00366 * @return <code>Hashtable</code> of controllerName --> ArrayList of backend 00367 * names 00368 * @throws VirtualDatabaseException if cannot return the result 00369 */ 00370 Hashtable viewGroupBackends() throws VirtualDatabaseException; 00371 00372 /** 00373 * Name of the controller owning this virtual database 00374 * 00375 * @return url of the controller 00376 */ 00377 String viewOwningController(); 00378 00379 /** 00380 * Retrieves an array of data on the backends for this virtual database 00381 * 00382 * @return <code>String[][]</code> of formatted data for all backends 00383 * @throws Exception if fails 00384 */ 00385 String[][] retrieveBackendsData() throws Exception; 00386 00387 /** 00388 * Return the list of controllers defining this virtual database. If the 00389 * database is not distributed this returns the same as 00390 * <code>viewOwningController</code> otherwise returns an array of 00391 * controller configuring this <code>DistributedVirtualDatabase</code> 00392 * 00393 * @return <code>String[]</code> of controller names. 00394 */ 00395 String[] viewControllerList(); 00396 00397 /** 00398 * Returns the currentNbOfThreads. 00399 * 00400 * @return int 00401 */ 00402 int getCurrentNbOfThreads(); 00403 00404 /** 00405 * Clean data collected by the current monitoring system, to avoid memory 00406 * problems. Monitor does not have to be active. 00407 * 00408 * @throws VirtualDatabaseException if there is no monitor. 00409 */ 00410 void cleanMonitoringData() throws VirtualDatabaseException; 00411 00412 /** 00413 * If a monitoring section exists, we can set the monitoring on or off by 00414 * calling this method. If monitoring is not defined we throw an exception. 00415 * 00416 * @param active should set the monitor to on or off 00417 * @throws VirtualDatabaseException if there is no monitor. 00418 */ 00419 void setMonitoringToActive(boolean active) throws VirtualDatabaseException; 00420 00421 }