001: /**
002: * Sequoia: Database clustering technology.
003: * Copyright (C) 2002-2004 French National Institute For Research In Computer
004: * Science And Control (INRIA).
005: * Contact: sequoia@continuent.org
006: *
007: * Licensed under the Apache License, Version 2.0 (the "License");
008: * you may not use this file except in compliance with the License.
009: * You may obtain a copy of the License at
010: *
011: * http://www.apache.org/licenses/LICENSE-2.0
012: *
013: * Unless required by applicable law or agreed to in writing, software
014: * distributed under the License is distributed on an "AS IS" BASIS,
015: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
016: * See the License for the specific language governing permissions and
017: * limitations under the License.
018: *
019: * Initial developer(s): Emmanuel Cecchet.
020: * Contributor(s): Nicolas Modrzyk.
021: */package org.continuent.sequoia.common.jmx.mbeans;
022:
023: import java.sql.SQLException;
024: import java.util.ArrayList;
025: import java.util.List;
026: import java.util.Map;
027:
028: import javax.management.openmbean.TabularData;
029:
030: import org.continuent.sequoia.common.exceptions.VirtualDatabaseException;
031: import org.continuent.sequoia.common.jmx.management.DumpInfo;
032: import org.continuent.sequoia.common.jmx.monitoring.backend.BackendStatistics;
033:
034: /**
035: * JMX Interface to remotely manage a Virtual Databases.
036: *
037: * @author <a href="mailto:Emmanuel.Cecchet@inria.fr">Emmanuel Cecchet </a>
038: * @author <A href="mailto:Nicolas.Modrzyk@inrialpes.fr">Nicolas Modrzyk </a>
039: * @version 1.0
040: */
041: public interface VirtualDatabaseMBean {
042: //
043: // Methods are organized as follows:
044: // 1. Database backends management
045: // 2. Checkpoint management
046: // 3. Backup management
047: // 4. Virtual database management
048: //
049:
050: /**
051: * Initializes a virtual database from specified Backend. This has to be
052: * performed prior to any use of the vdb backends, i.e. there are no active
053: * backends in the vdb, and none has a last known checkpoint. This should be
054: * immediately followed by a backup operation on the specified backend. This
055: * resets the recovery log - if any - to an empty state, i.e. drops logtable,
056: * drops checkpoint table, and clears checkpoint names in the dump table.
057: * Finally, sets the last known checkpoint of specified backend to
058: * Initial_empty_recovery_log.
059: *
060: * @param databaseBackendName the name of the backend to use for
061: * initialization.
062: * @param force if true, do not perform sanity checks, unconditionally perform
063: * the initialization
064: * @throws VirtualDatabaseException if there is an active backend or a backend
065: * which has a last known checkpoint, or if there is no recovery log
066: * for this vdb.
067: */
068: void initializeFromBackend(String databaseBackendName, boolean force)
069: throws VirtualDatabaseException;
070:
071: /**
072: * Performs initializeFromBackend(databaseBackendName, force=false). This is a
073: * convenience method for backward compatibility.
074: *
075: * @param databaseBackendName the name of the backend to use for
076: * initialization.
077: * @throws VirtualDatabaseException if there is an active backend or a backend
078: * which has a last known checkpoint, or if there is no recovery log
079: * for this vdb.
080: * @deprecated use method with explicit force option.
081: */
082: void initializeFromBackend(String databaseBackendName)
083: throws VirtualDatabaseException;
084:
085: //
086: // Database backends management
087: //
088:
089: /**
090: * Enables a backend that has been previously added to this virtual database
091: * and that is in the disabled state. The backend is enabled without further
092: * check.
093: *
094: * @param databaseBackendName The database backend logical name to enable
095: * @exception VirtualDatabaseException in case of communication-related error
096: */
097: void forceEnableBackend(String databaseBackendName)
098: throws VirtualDatabaseException;
099:
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,
204: String checkpoint) 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,
247: String password, String dumpName, String backuperName,
248: String path, boolean force, ArrayList tables)
249: throws VirtualDatabaseException;
250:
251: /**
252: * This is backupBackend(force=true).
253: *
254: * @see backupBackend(String backendName, String login, String password,
255: * String dumpName, String backuperName, String path, boolean force,
256: * ArrayList tables).
257: * @deprecated use method with explicit option force.
258: */
259: void backupBackend(String backendName, String login,
260: String password, String dumpName, String backuperName,
261: String path, ArrayList tables)
262: throws VirtualDatabaseException;
263:
264: /**
265: * Get all available dump info for this virtual database
266: *
267: * @return an array of <code>DumpInfo</code> containing the available dump
268: * info for this virtual database. Cannot be null but can be empty.
269: * @exception VirtualDatabaseException if we can't retrieve dumps
270: */
271: DumpInfo[] getAvailableDumps() throws VirtualDatabaseException;
272:
273: /**
274: * Get all available dump info for this virtual database
275: *
276: * @return an open-type represenation of the array of <code>DumpInfo</code>
277: * that would be returned by #getAvailableDumps() above.
278: * @exception VirtualDatabaseException if we can't retrieve dumps
279: */
280: TabularData getDumps() throws Exception;
281:
282: /**
283: * Update the path of the dump for a given dumpName.
284: *
285: * @param dumpName name of the dump
286: * @param newPath new path for the dump
287: * @throws VirtualDatabaseException if cannot update the path
288: */
289: void updateDumpPath(String dumpName, String newPath)
290: throws VirtualDatabaseException;
291:
292: /**
293: * Delete the dump entry associated to the <code>dumpName</code>.<br />
294: * If <code>keepsFile</code> is false, the dump file is also removed from
295: * the file system.
296: *
297: * @param dumpName name of the dump entry to remove
298: * @param keepsFile <code>true</code> if the dump should be also removed
299: * from the file system, <code>false</code> else
300: * @throws VirtualDatabaseException if an exception occured while removing the
301: * dump entry or the dump file
302: */
303: void deleteDump(String dumpName, boolean keepsFile)
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,
344: boolean noCopy) 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: * The getXml() method does not return the schema if it is not static anymore,
364: * to avoid confusion between static and dynamic schema. This method returns a
365: * static view of the schema, whatever the dynamic precision is.
366: *
367: * @param backendName the name of the backend to get the schema from
368: * @return an xml formatted string
369: * @throws VirtualDatabaseException if an error occurs while accessing the
370: * backend, or if the backend does not exist.
371: */
372: String getBackendSchema(String backendName)
373: throws VirtualDatabaseException;
374:
375: /**
376: * Retrieves this <code>VirtualDatabase</code> object in xml format
377: *
378: * @return xml formatted string that conforms to sequoia.dtd
379: */
380: String getXml();
381:
382: //
383: // Virtual database management
384: //
385:
386: // FIXME this method is useless: if a jmx client can connect
387: // to the vdb mbean it won't call this method and can still
388: // manage the vdb because the other mbean's method do not
389: // check that their caller has been authenticated or not...
390: /**
391: * Authenticate a user for a given virtual database
392: *
393: * @param adminLogin username
394: * @param adminPassword password
395: * @return true if authentication is a success, false otherwise
396: * @throws VirtualDatabaseException if database does not exists
397: */
398: boolean checkAdminAuthentication(String adminLogin,
399: String adminPassword) throws VirtualDatabaseException;
400:
401: // TODO rename it to getName()
402: /**
403: * Gets the virtual database name to be used by the client (Sequoia driver)
404: *
405: * @return the virtual database name
406: */
407: String getVirtualDatabaseName();
408:
409: // TODO rename it to isRecoveryLogDefined() so that it is considered as an
410: // attribute
411: // rather than an operation
412: /**
413: * Indicate if there is a recovery log defined for this virtual database
414: *
415: * @return <code>true</code> if the recovery log is defined and can be
416: * accessed, <code>false</code> otherwise
417: */
418: boolean hasRecoveryLog();
419:
420: // TODO rename it to isResultCacheDefined() so that it is considered as an
421: // attribute
422: // rather than an operation
423: /**
424: * Indicate if there is a result cache defined for this virtual database
425: *
426: * @return <code>true</code> if a request cache is defined and can be
427: * accessed, <code>false</code> otherwise
428: */
429: boolean hasResultCache();
430:
431: /**
432: * Tells whether this database is distributed or not
433: *
434: * @return <code>true</code> if the database is distributed among multiple
435: * controllers <code>false</code> if it exists on a single
436: * controller only
437: */
438: boolean isDistributed();
439:
440: /**
441: * Shutdown this virtual database. Finish all threads and stop connection to
442: * backends
443: *
444: * @param level Constants.SHUTDOWN_WAIT, Constants.SHUTDOWN_SAFE or
445: * Constants.SHUTDOWN_FORCE
446: * @throws VirtualDatabaseException if an error occurs
447: */
448: void shutdown(int level) throws VirtualDatabaseException;
449:
450: /**
451: * Name of the controller owning this virtual database
452: *
453: * @return url of the controller
454: */
455: String getOwningController();
456:
457: /**
458: * Retrieves an array of statistics of the given backend for this virtual
459: * database
460: *
461: * @param backendName name of the backend
462: * @return <code>BackendStatistics[]</code> of formatted data for all
463: * backends or <code>null</code> if the backend does not exist
464: * @throws Exception if fails
465: */
466: BackendStatistics getBackendStatistics(String backendName)
467: throws Exception;
468:
469: /**
470: * Return the list of controllers defining this virtual database. If the
471: * database is not distributed this returns the same as
472: * <code>getOwningController</code> otherwise returns an array of
473: * controller configuring this <code>DistributedVirtualDatabase</code>
474: *
475: * @return <code>String[]</code> of controller names.
476: */
477: String[] getControllers();
478:
479: // TODO rename to getWorkerThreadsSize()
480: /**
481: * Returns the currentNbOfThreads.
482: *
483: * @return int
484: */
485: int getCurrentNbOfThreads();
486:
487: // TODO add a isActiveMonitoring() to know the current state of monitoring
488: // activation
489:
490: // TODO rename it to setActiveMonitoring() so that it is considered as an
491: // attribute
492: // rather than an operation
493: /**
494: * If a monitoring section exists, we can set the monitoring on or off by
495: * calling this method. If monitoring is not defined we throw an exception.
496: *
497: * @param active should set the monitor to on or off
498: * @throws VirtualDatabaseException if there is no monitor.
499: */
500: void setMonitoringToActive(boolean active)
501: throws VirtualDatabaseException;
502:
503: /**
504: * Abort a transaction that has been started but in which no query was
505: * executed. As we use lazy transaction begin, there is no need to rollback
506: * such transaction but just to cleanup the metadata associated with this not
507: * effectively started transaction.
508: *
509: * @param transactionId id of the transaction to abort
510: * @param logAbort true if the abort (in fact rollback) should be logged in
511: * the recovery log
512: * @param forceAbort true if the abort will be forced. Actually, abort will do
513: * nothing when a transaction has savepoints (we do not abort the
514: * whole transaction, so that the user can rollback to a previous
515: * savepoint), except when the connection is closed. In this last
516: * case, if the transaction is not aborted, it prevents future
517: * maintenance operations such as shutdowns, enable/disable from
518: * completing, so we have to force this abort operation. It also
519: * applies to the DeadlockDetectionThread and the cleanup of the
520: * VirtualDatabaseWorkerThread.
521: * @throws SQLException if an error occurs
522: */
523: void abort(long transactionId, boolean logAbort, boolean forceAbort)
524: throws SQLException;
525:
526: /**
527: * Close the given persistent connection.
528: *
529: * @param login login to use to retrieve the right connection pool
530: * @param persistentConnectionId id of the persistent connection to close
531: */
532: void closePersistentConnection(String login,
533: long persistentConnectionId);
534: }
|