001: /*
002:
003: Derby - Class org.apache.derby.iapi.store.raw.RawStoreFactory
004:
005: Licensed to the Apache Software Foundation (ASF) under one or more
006: contributor license agreements. See the NOTICE file distributed with
007: this work for additional information regarding copyright ownership.
008: The ASF licenses this file to you under the Apache License, Version 2.0
009: (the "License"); you may not use this file except in compliance with
010: the License. You may obtain a copy of the License at
011:
012: http://www.apache.org/licenses/LICENSE-2.0
013:
014: Unless required by applicable law or agreed to in writing, software
015: distributed under the License is distributed on an "AS IS" BASIS,
016: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: See the License for the specific language governing permissions and
018: limitations under the License.
019:
020: */
021:
022: package org.apache.derby.iapi.store.raw;
023:
024: import org.apache.derby.iapi.services.daemon.DaemonService;
025: import org.apache.derby.iapi.services.context.ContextManager;
026: import org.apache.derby.iapi.services.locks.LockFactory;
027:
028: import org.apache.derby.iapi.services.property.PersistentSet;
029:
030: import org.apache.derby.iapi.store.access.TransactionInfo;
031: import org.apache.derby.iapi.store.raw.xact.TransactionFactory;
032: import org.apache.derby.iapi.store.raw.log.LogInstant;
033: import org.apache.derby.iapi.error.StandardException;
034:
035: import org.apache.derby.catalog.UUID;
036: import org.apache.derby.iapi.store.access.DatabaseInstant;
037: import org.apache.derby.iapi.error.ExceptionSeverity;
038: import java.util.Properties;
039: import java.io.Serializable;
040: import java.io.File;
041:
042: /**
043: RawStoreFactory implements a single unit of transactional
044: storage. A RawStoreFactory contains Segments and Segments
045: contain Containers.
046: <P>
047: Segments are identified
048: by integer identifiers that are unique within a RawStoreFactory.
049: <P>
050: Containers are also identified by unique integer identifiers
051: within a RawStoreFactory, but will overlap with segment identifiers.
052: <P><B>LIMITS</B><BR>
053: This is a list of (hopefully) all limits within the raw store. Where a size
054: has more than one limit all are documented (rather than just the most
055: restrictive) so that the correct limit can be found if the most restictive
056: is every removed.
057: <UL>
058: <LI>Field -
059: <UL>
060: <LI>Max length 2^31 - 1 (2147483647) -
061: </UL>
062: <LI>Record -
063: <UL>
064: <LI>Max number of fields 2^31 - 1 (2147483647) - from use of Object[]
065: array to represent row, which can "only" have int sized number of array
066: members.
067: </UL>
068: <LI>Page -
069: <LI>Container -
070: <LI>Segment -
071: <LI>Raw Store -
072: </UL>
073:
074: <P>
075: Access and RawStore work together to provide the ACID properties of
076: transactions. On a high level, RawStore deals with anything that directly
077: impacts persistency. On a more detailed level, RawStore provides
078: logging, rollback and recovery, data management on page, page allocation
079: and deallocation, container allocation and deallocation.
080:
081:
082: <P>
083: RawStore is organized as 3 branches, transaction, data, and
084: logging. These branches each have its own "factory", the transaction
085: factory hands out transactions, the data factory hands out containers,
086: and the log factory hands out logger (or log buffers) for transactions to
087: write on. For a more detailed description on these factories, please see
088: their corresponding javadocs.
089:
090:
091: MT - Thread Safe
092:
093: @see ContainerHandle */
094:
095: public interface RawStoreFactory extends Corruptable {
096:
097: /** Store engine version numbers indicating the database must be upgraded to
098: * or created at the current engine level
099: */
100:
101: /** Derby Store Minor Version (1) **/
102: public static final int DERBY_STORE_MINOR_VERSION_1 = 1;
103:
104: /** Derby Store Minor Version (2) **/
105: public static final int DERBY_STORE_MINOR_VERSION_2 = 2;
106:
107: /** Derby 10 Store Major version */
108: public static final int DERBY_STORE_MAJOR_VERSION_10 = 10;
109:
110: /**
111: Default value for PAGE_SIZE_PARAMETER (4096).
112: */
113: public static final int PAGE_SIZE_DEFAULT = 4096;
114:
115: /**
116: Minimum page size we will accept (1024).
117: */
118: public static final int PAGE_SIZE_MINIMUM = 1024;
119:
120: public static final String PAGE_SIZE_STRING = "2048";
121:
122: /** Property name for the page cache size to be used in the storage area.
123: Equal to 'derby.storage.pageCacheSize'
124: */
125: public static final String PAGE_CACHE_SIZE_PARAMETER = "derby.storage.pageCacheSize";
126:
127: /**
128: Default value for PAGE_CACHE_SIZE_PARAMETER (1000).
129: */
130: public static final int PAGE_CACHE_SIZE_DEFAULT = 1000;
131:
132: /**
133: Minimum page cache size we will accept (40).
134: */
135: public static final int PAGE_CACHE_SIZE_MINIMUM = 40;
136:
137: /**
138: Maximum page cache size we will accept (MAXINT).
139: */
140: public static final int PAGE_CACHE_SIZE_MAXIMUM = Integer.MAX_VALUE;
141:
142: /**
143: Maximum number of initial pages when a container is created
144: */
145: public static final short MAX_CONTAINER_INITIAL_PAGES = 1000;
146:
147: /** Property name for the default minimum record size to be used in the
148: storage area. Minimum record size is the minimum number of bytes that a
149: record will reserve on disk.
150: */
151: public static final String MINIMUM_RECORD_SIZE_PARAMETER = "derby.storage.minimumRecordSize";
152: /**
153: Default value for MINIMUM_RECORD_SIZE_PARAMETER for heap tables that
154: allow overflow. By setting minimumRecordSize to 12 bytes, we
155: guarantee there is enough space to update the row even there is not
156: enough space on the page. The 12 bytes will guarantee there is room
157: for an overflow pointer (page + id).
158: */
159: public static final int MINIMUM_RECORD_SIZE_DEFAULT = 12;
160:
161: /**
162: Minimum value for MINIMUM_RECORD_SIZE_PARAMETER (1).
163: */
164: public static final int MINIMUM_RECORD_SIZE_MINIMUM = 1;
165:
166: /** Property name for percentage of space to leave free on page for updates.
167: */
168: public static final String PAGE_RESERVED_SPACE_PARAMETER = "derby.storage.pageReservedSpace";
169:
170: public static final String PAGE_RESERVED_ZERO_SPACE_STRING = "0";
171:
172: /** Property name for the number of pages we try to pre-allocate in one
173: /** synchronous I/O
174: */
175: public static final String PRE_ALLOCATE_PAGE = "derby.storage.pagePerAllocate";
176:
177: /**
178: Property name for container which reuses recordId when a page is
179: reused. Defaults to false, which means recordId is never reused.
180:
181: This property should NOT be set by the end user, only Access should set
182: it for special conglomerates which does not count on permanant unique
183: recordIds for all records.
184: */
185: public static final String PAGE_REUSABLE_RECORD_ID = "derby.storage.reusableRecordId";
186:
187: /**
188: Property name for buffer size to be used in the stream file container.
189: Equal to 'derby.storage.streamFileBufferSize'
190: */
191: public static final String STREAM_FILE_BUFFER_SIZE_PARAMETER = "derby.storage.streamFileBufferSize";
192:
193: /**
194: Default value for STREAM_FILE_BUFFER_SIZE_PARAMETER (16384).
195: */
196: public static final int STREAM_FILE_BUFFER_SIZE_DEFAULT = 16384;
197:
198: /**
199: Minimum stream file buffer size we will accept (1024).
200: */
201: public static final int STREAM_FILE_BUFFER_SIZE_MINIMUM = 1024;
202:
203: /**
204: Maximum stream file buffer size we will accept (MAXINT).
205: */
206: public static final int STREAM_FILE_BUFFER_SIZE_MAXIMUM = Integer.MAX_VALUE;
207:
208: /**
209:
210: Property name for container which attempts to be created with an
211: initial size of this many pages. Defaults to 1 page.
212:
213: <BR>All containers are guarenteed to be created with at least 1 page,
214: if this property is set, it will attempt to allocate
215: CONTAINER_INITIAL_PAGES, but with no guarentee.
216: CONTAIENR_INITIAL_PAGES legally ranges from 1 to
217: MAX_CONTAINER_INITIAL_PAGES. Values < 1 will
218: be set to 1 and values > MAX_CONTAINER_INITIAL_PAGES will be set to
219: MAX_CONTAINER_INITIAL_PAGES
220:
221: This property should only be set in the PROPERTIES list in a CREATE
222: TABLE or CREATE INDEX statement. The global setting of this property
223: has no effect.
224: */
225: public static final String CONTAINER_INITIAL_PAGES = "derby.storage.initialPages";
226:
227: /**
228: encryption alignment requirement.
229: */
230: public static final int ENCRYPTION_ALIGNMENT = 8;
231:
232: /**
233: default encryption block size
234: In old existing databases (ie 5.1.x), the default
235: encryption block size used is 8. Do not change this value unless you
236: account for downgrade issues
237: */
238: public static final int DEFAULT_ENCRYPTION_BLOCKSIZE = 8;
239:
240: /**
241: encryption block size used during creation of encrypted database
242: This property is not set by the user; it is set by the engine when
243: RawStore boots up during creation of an encrypted database
244: */
245: public static final String ENCRYPTION_BLOCKSIZE = "derby.encryptionBlockSize";
246:
247: /**
248:
249: This variable is used to store the encryption scheme to allow
250: for any future changes in encryption schemes of data
251: This property has been introduced in version 10
252: Value starts at 1
253: */
254: public static final String DATA_ENCRYPT_ALGORITHM_VERSION = "data_encrypt_algorithm_version";
255:
256: /**
257: Store the encryption scheme used for logging
258: This will allow for any future changes in encryption schemes of logs
259: This variable has been introduced in version 10 and value starts at 1.
260: */
261: public static final String LOG_ENCRYPT_ALGORITHM_VERSION = "log_encrypt_algorithm_version";
262:
263: /**
264: If dataEncryption is true, store the encrypted key in
265: services.properties file. It is really the encrypted
266: key, but the property key is called the encryptedBootPassword.
267:
268: */
269: public static final String ENCRYPTED_KEY = "encryptedBootPassword";
270:
271: /**
272: * When the datbase is getting re-encrypted old encrypted key is
273: * stored in the service.properties until re-encyrption
274: * successfully completes or rolled back. It is really the old
275: * encryptedkey, but the property key is called the
276: * OldEncryptedBootPassword.
277: */
278: public static final String OLD_ENCRYPTED_KEY = "OldEncryptedBootPassword";
279:
280: /*
281: * Following property is used to track the status of the (re)encryption,
282: * required to bring the database back to state it was before the
283: * (re) encryption started, id (re) encryption of the database
284: * is aborted.
285: */
286: public static final String DB_ENCRYPTION_STATUS = "derby.storage.databaseEncryptionStatus";
287:
288: /* (re)encryption is in progress, if a crash
289: * occurs after this flag is set,
290: * (re)encryption needs to be undone.
291: */
292: public static final int DB_ENCRYPTION_IN_PROGRESS = 1;
293:
294: /* this flag is used to track crash during undo
295: of (re) encryption during recovery .
296: */
297: public static final int DB_ENCRYPTION_IN_UNDO = 2;
298:
299: /*
300: * Cleanup any (re) encryption related resources.
301: */
302: public static final int DB_ENCRYPTION_IN_CLEANUP = 3;
303:
304: /**
305: A File used to save the old copy of the verify key
306: (Attribute.CRYPTO_EXTERNAL_KEY_VERIFY_FILE) file during
307: re-encryption of the database.
308: */
309: String CRYPTO_OLD_EXTERNAL_KEY_VERIFY_FILE = "verifyOldKey.dat";
310:
311: /**
312: * for debugging, keep all transaction logs intact.
313: */
314: public static final String KEEP_TRANSACTION_LOG = "derby.storage.keepTransactionLog";
315:
316: /**
317: * The following is a to enable patch for databases with recovery
318: * errors during redo of InitPage. If this property is set and
319: * the page on the disk is corrupted and is getting exceptions like
320: * invalid page format ids, we cook up the page during the recovery time.
321: * We have seen this kind of problem with 1.5.1 databases from
322: * customer Tridium ( Bug no: 3813).
323: * This patch needs to be kept unless we find the problem is during
324: * recovery process. If we discover this problem is actaully happening
325: * at the recovery then this patch should be backed out.
326: **/
327: public static final String PATCH_INITPAGE_RECOVER_ERROR = "derby.storage.patchInitPageRecoverError";
328:
329: /** module name */
330: public static final String MODULE = "org.apache.derby.iapi.store.raw.RawStoreFactory";
331:
332: /**
333: Is the store read-only.
334: */
335: public boolean isReadOnly();
336:
337: /**
338: Get the LockFactory to use with this store.
339: */
340: public LockFactory getLockFactory();
341:
342: /**
343: Create a user transaction, almost all work within the raw store is
344: performed in the context of a transaction.
345: <P>
346: Starting a transaction always performs the following steps.
347: <OL>
348: <LI>Create an raw store transaction context
349: <LI>Create a new idle transaction and then link it to the context.
350: </UL>
351: Only one user transaction and one nested user transaction can be active
352: in a context at any one time.
353: After a commit the transaction may be re-used.
354: <P>
355: <B>Raw Store Transaction Context Behaviour</B>
356: <BR>
357: The cleanupOnError() method of this context behaves as follows:
358: <UL>
359: <LI>
360: If error is an instance of StandardException that
361: has a severity less than ExceptionSeverity.TRANSACTION_SEVERITY then
362: no action is taken.
363: <LI>
364: If error is an instance of StandardException that
365: has a severity equal to ExceptionSeverity.TRANSACTION_SEVERITY then
366: the context's transaction is aborted, and the transaction returned to
367: the idle state.
368: <LI>
369: If error is an instance of StandardException that
370: has a severity greater than ExceptionSeverity.TRANSACTION_SEVERITY
371: then the context's transaction is aborted, the transaction closed, and
372: the context is popped off the stack.
373: <LI>
374: If error is not an instance of StandardException then the context's
375: transaction is aborted, the transaction closed, and the
376: context is popped off the stack.
377: </UL>
378:
379: @param contextMgr is the context manager to use. An exception will be
380: thrown if context is not the current context.
381: @param transName is the name of the transaction. Thsi name will be displayed
382: by the transactiontable VTI.
383:
384: @exception StandardException Standard Cloudscape error policy
385:
386: @see Transaction
387: @see org.apache.derby.iapi.services.context.Context
388: @see StandardException
389: */
390:
391: public Transaction startTransaction(ContextManager contextMgr,
392: String transName) throws StandardException;
393:
394: /**
395: Create a global user transaction, almost all work within the raw store
396: is performed in the context of a transaction.
397: <P>
398: The (format_id, global_id, branch_id) triplet is meant to come exactly
399: from a javax.transaction.xa.Xid. We don't use Xid so that the system
400: can be delivered on a non-1.2 vm system and not require the javax
401: classes in the path.
402: <P>
403: Starting a transaction always performs the following steps.
404: <OL>
405: <LI>Create an raw store transaction context
406: <LI>Create a new idle transaction and then link it to the context.
407: </UL>
408: Only one user transaction can be active in a context at any one time.
409: After a commit the transaction may be re-used.
410: <P>
411: <B>Raw Store Transaction Context Behaviour</B>
412: <BR>
413: The cleanupOnError() method of this context behaves as follows:
414: <UL>
415: <LI>
416: If error is an instance of StandardException that
417: has a severity less than ExceptionSeverity.TRANSACTION_SEVERITY then
418: no action is taken.
419: <LI>
420: If error is an instance of StandardException that
421: has a severity equal to ExceptionSeverity.TRANSACTION_SEVERITY then
422: the context's transaction is aborted, and the transaction returned to
423: the idle state.
424: <LI>
425: If error is an instance of StandardException that
426: has a severity greater than ExceptionSeverity.TRANSACTION_SEVERITY
427: then the context's transaction is aborted, the transaction closed, and
428: the context is popped off the stack.
429: <LI>
430: If error is not an instance of StandardException then the context's
431: transaction is aborted, the transaction closed, and the
432: context is popped off the stack.
433: </UL>
434:
435: @param contextMgr is the context manager to use. An exception will be
436: thrown if context is not the current context.
437: @param format_id the format id part of the Xid - ie. Xid.getFormatId().
438: @param global_id the global transaction identifier part of XID - ie.
439: Xid.getGlobalTransactionId().
440: @param local_id The branch qualifier of the Xid - ie.
441: Xid.getBranchQaulifier()
442:
443: @exception StandardException Standard Cloudscape error policy
444:
445: @see Transaction
446: @see org.apache.derby.iapi.services.context.Context
447: @see StandardException
448: */
449: public Transaction startGlobalTransaction(
450: ContextManager contextMgr, int format_id, byte[] global_id,
451: byte[] local_id) throws StandardException;
452:
453: /**
454: Find a user transaction in the context manager, which must be the
455: current context manager. If a user transaction does not already exist,
456: then create one @see #startTransaction
457:
458: @param contextMgr the context manager to use. An exception will be
459: thrown if context is not the current context.
460: @param transName If a new transaction is started, it will be given
461: this name.
462: The name is displayed in the transactiontable VTI.
463:
464: @exception StandardException Standard Cloudscape error policy
465:
466: @see #startTransaction
467: */
468: public Transaction findUserTransaction(ContextManager contextMgr,
469: String transName) throws StandardException;
470:
471: /**
472: Create an internal transaction.
473: <P>
474: Starting an internal transaction always performs the following steps.
475: <OL>
476: <LI>Create an raw store internal transaction context
477: <LI>Create a new idle internal transaction and then link it to the
478: context.
479: </UL>
480: <P>
481: AN internal transaction is identical to a user transaction with the
482: exception that
483: <UL>
484: <LI> Logical operations are not supported
485: <LI> Savepoints are not supported
486: <LI> Containers are not closed when commit() is called.
487: <LI> Pages are not unlatched (since containers are not closed) when
488: commit() is called.
489: <LI> During recovery time internal transactions are rolled back before
490: user transactions.
491: </UL>
492: Only one internal transaction can be active in a context at any one time.
493: After a commit the transaction may be re-used.
494: <P>
495: <B>Raw Store Internal Transaction Context Behaviour</B>
496: <BR>
497: The cleanupOnError() method of this context behaves as follows:
498: <UL>
499: <LI>
500: If error is an instance of StandardException that
501: has a severity less than ExceptionSeverity.TRANSACTION_SEVERITY then
502: the internal transaction is aborted, the internal transaction is closed, the context is popped off the stack, and an exception of severity
503: Transaction exception is re-thrown.
504: <LI>
505: If error is an instance of StandardException that has a severity
506: greater than or equal to ExceptionSeverity.TRANSACTION_SEVERITY then
507: the context's internal transaction is aborted, the internal
508: transaction is closed and the context is popped off the stack.
509: <LI>
510: If error is not an instance of StandardException then the context's
511: internal transaction is aborted, the internal transaction is closed
512: and the context is popped off the stack.
513: </UL>
514:
515: @exception StandardException Standard Cloudscape error policy
516:
517: @see Transaction
518: @see org.apache.derby.iapi.services.context.Context
519: @see StandardException
520: */
521: public Transaction startInternalTransaction(
522: ContextManager contextMgr) throws StandardException;
523:
524: /**
525: Create a nested user transaction, almost all work within the raw store
526: is performed in the context of a transaction.
527: <P>
528: A nested user transaction is exactly the same as a user transaction,
529: except that one can specify a compatibility space to associate with
530: the transaction.
531: Starting a transaction always performs the following steps.
532: <OL>
533: <LI>Create an raw store transaction context
534: <LI>Create a new idle transaction and then link it to the context.
535: </UL>
536: Only one user transaction and one nested user transaction can be active
537: in a context at any one time.
538: After a commit the transaction may be re-used.
539: <P>
540: <B>Raw Store Transaction Context Behaviour</B>
541: <BR>
542: The cleanupOnError() method of this context behaves as follows:
543: <UL>
544: <LI>
545: If error is an instance of StandardException that
546: has a severity less than ExceptionSeverity.TRANSACTION_SEVERITY then
547: no action is taken.
548: <LI>
549: If error is an instance of StandardException that
550: has a severity equal to ExceptionSeverity.TRANSACTION_SEVERITY then
551: the context's transaction is aborted, and the transaction returned to
552: the idle state. If a user transaction exists on the context stack
553: then that transaction is aborted also.
554: <LI>
555: If error is an instance of StandardException that
556: has a severity greater than ExceptionSeverity.TRANSACTION_SEVERITY
557: then the context's transaction is aborted, the transaction closed, and
558: the context is popped off the stack.
559: <LI>
560: If error is not an instance of StandardException then the context's
561: transaction is aborted, the transaction closed, and the
562: context is popped off the stack.
563: </UL>
564:
565: @param compatibilitySpace compatibility space to use for locks.
566: @param contextMgr is the context manager to use. An exception will be
567: thrown if context is not the current context.
568: @param transName is the name of the transaction. This name will be
569: displayed by the transactiontable VTI.
570:
571: @exception StandardException Standard Cloudscape error policy
572:
573: @see Transaction
574: @see org.apache.derby.iapi.services.context.Context
575: @see StandardException
576: */
577:
578: public Transaction startNestedReadOnlyUserTransaction(
579: Object compatibilitySpace, ContextManager contextMgr,
580: String transName) throws StandardException;
581:
582: /**
583: Create a nested user transaction, almost all work within the raw store
584: is performed in the context of a transaction.
585: <P>
586: A nested user transaction is exactly the same as a user transaction,
587: except that one can specify a compatibility space to associate with
588: the transaction.
589: Starting a transaction always performs the following steps.
590: <OL>
591: <LI>Create an raw store transaction context
592: <LI>Create a new idle transaction and then link it to the context.
593: </UL>
594: Only one user transaction and one nested user transaction can be active
595: in a context at any one time.
596: After a commit the transaction may be re-used.
597: <P>
598: <B>Raw Store Transaction Context Behaviour</B>
599: <BR>
600: The cleanupOnError() method of this context behaves as follows:
601: <UL>
602: <LI>
603: If error is an instance of StandardException that
604: has a severity less than ExceptionSeverity.TRANSACTION_SEVERITY then
605: no action is taken.
606: <LI>
607: If error is an instance of StandardException that
608: has a severity equal to ExceptionSeverity.TRANSACTION_SEVERITY then
609: the context's transaction is aborted, and the transaction returned to
610: the idle state. If a user transaction exists on the context stack
611: then that transaction is aborted also.
612: <LI>
613: If error is an instance of StandardException that
614: has a severity greater than ExceptionSeverity.TRANSACTION_SEVERITY
615: then the context's transaction is aborted, the transaction closed, and
616: the context is popped off the stack.
617: <LI>
618: If error is not an instance of StandardException then the context's
619: transaction is aborted, the transaction closed, and the
620: context is popped off the stack.
621: </UL>
622:
623: @param contextMgr is the context manager to use. An exception will be
624: thrown if context is not the current context.
625: @param transName is the name of the transaction. This name will be
626: displayed by the transactiontable VTI.
627:
628: @exception StandardException Standard Cloudscape error policy
629:
630: @see Transaction
631: @see org.apache.derby.iapi.services.context.Context
632: @see StandardException
633: */
634:
635: public Transaction startNestedUpdateUserTransaction(
636: ContextManager contextMgr, String transName)
637: throws StandardException;
638:
639: /**
640: @see org.apache.derby.iapi.store.access.AccessFactory#getTransactionInfo
641: */
642: public TransactionInfo[] getTransactionInfo();
643:
644: /**
645: * Freeze the database temporarily so a backup can be taken.
646: * <P>Please see cloudscape on line documentation on backup and restore.
647: *
648: * @exception StandardException Thrown on error
649: */
650: public void freeze() throws StandardException;
651:
652: /**
653: * Unfreeze the database after a backup has been taken.
654: * <P>Please see cloudscape on line documentation on backup and restore.
655: *
656: * @exception StandardException Thrown on error
657: */
658: public void unfreeze() throws StandardException;
659:
660: /**
661: * Backup the database to backupDir.
662: * <P>Please see cloudscape on line documentation on backup and restore.
663: *
664: * @param backupDir the name of the directory where the backup should be
665: * stored.
666: * @param wait if <tt>true</tt>, waits for all the backup blocking
667: * operations in progress to finish.
668: *
669: * @exception StandardException Thrown on error
670: */
671: public void backup(String backupDir, boolean wait)
672: throws StandardException;
673:
674: /**
675: * Backup the database to a backup directory and enable the log archive
676: * mode that will keep the archived log files required for roll-forward
677: * from this version backup.
678: *
679: * @param backupDir the directory name where the
680: * database backup should go. This
681: * directory will be created if not it
682: * does not exist.
683: *
684: * @param deleteOnlineArchivedLogFiles If true deletes online archived log
685: * files that exist before this backup,
686: * delete will occur only after backup
687: * is complete.
688: *
689: * @param wait if <tt>true</tt>, waits for all the backup blocking
690: * operations in progress to finish.
691: *
692: * @exception StandardException Thrown on error
693: */
694: public void backupAndEnableLogArchiveMode(String backupDir,
695: boolean deleteOnlineArchivedLogFiles, boolean wait)
696: throws StandardException;
697:
698: /**
699: * disables the log archival process, i.e No old log files
700: * will be kept around for a roll-forward recovery.
701: *
702: * @param deleteOnlineArchivedLogFiles If true deletes all online archived
703: * log files that exist before this
704: * call immediately; Only restore that
705: * can be performed after disabling
706: * log archive mode is version
707: * recovery.
708: *
709: * @exception StandardException Thrown on error
710: */
711: public void disableLogArchiveMode(
712: boolean deleteOnlineArchivedLogFiles)
713: throws StandardException;
714:
715: /**
716: Try to checkpoint the database to minimize recovery time.
717: The raw store does not guarentee that a checkpoint will indeed have
718: happened by the time this routine returns.
719:
720: @exception StandardException Standard Cloudscape error policy
721: */
722: public void checkpoint() throws StandardException;
723:
724: /**
725: Idle the raw store as much as possible.
726: @exception StandardException Standard Cloudscape error policy
727:
728: */
729: public void idle() throws StandardException;
730:
731: /**
732: Get a flushed scan.
733: @param start The instant for the beginning of the scan.
734: @param groupsIWant log record groups the caller wants to scan.
735: @exception StandardException StandardCloudscape error policy
736: */
737: ScanHandle openFlushedScan(DatabaseInstant start, int groupsIWant)
738: throws StandardException;
739:
740: /**
741: If this raw store has a daemon that services its need, return the
742: daemon. If not, return null
743: */
744: public DaemonService getDaemon();
745:
746: /*
747: * return the transaction factory module
748: */
749: public String getTransactionFactoryModule();
750:
751: /*
752: * return the data factory module
753: */
754: public String getDataFactoryModule();
755:
756: /*
757: * return the Log factory module
758: */
759: public String getLogFactoryModule();
760:
761: /*
762: * Return the module providing XAresource interface to the transaction
763: * table.
764: *
765: * @exception StandardException Standard cloudscape exception policy.
766: */
767: public/* XAResourceManager */Object getXAResourceManager()
768: throws StandardException;
769:
770: /*
771: * the database creation phase is finished
772: * @exception StandardException Standard cloudscape exception policy.
773: */
774: public void createFinished() throws StandardException;
775:
776: /**
777: * Get JBMS properties relavent to raw store
778: *
779: * @exception StandardException Standard cloudscape exception policy.
780: */
781: public void getRawStoreProperties(PersistentSet tc)
782: throws StandardException;
783:
784: /**
785: * Backup / restore support
786: */
787:
788: /**
789: * Freeze the database from altering any persistent storage.
790: *
791: * @exception StandardException Standard cloudscape exception policy.
792: */
793: public void freezePersistentStore() throws StandardException;
794:
795: /**
796: * Unfreeze the database, persistent storage can now be altered.
797: *
798: * @exception StandardException Standard cloudscape exception policy.
799: */
800: public void unfreezePersistentStore() throws StandardException;
801:
802: /**
803: Encrypt cleartext into ciphertext.
804:
805: @see org.apache.derby.iapi.services.crypto.CipherProvider#encrypt
806: @exception StandardException Standard Cloudscape Error Policy
807: */
808: public int encrypt(byte[] cleartext, int offset, int length,
809: byte[] ciphertext, int outputOffset, boolean newEngine)
810: throws StandardException;
811:
812: /**
813: Decrypt cleartext from ciphertext.
814:
815: @see org.apache.derby.iapi.services.crypto.CipherProvider#decrypt
816: @exception StandardException Standard Cloudscape Error Policy
817: */
818: public int decrypt(byte[] ciphertext, int offset, int length,
819: byte[] cleartext, int outputOffset)
820: throws StandardException;
821:
822: /**
823: Returns the encryption block size used during creation of the encrypted database
824: */
825: public int getEncryptionBlockSize();
826:
827: /**
828: Returns a secure random number for this raw store - if database is not
829: encrypted, returns 0.
830: */
831: public int random();
832:
833: /**
834: Change the boot password. Return the encrypted form of the secret key.
835: The new value must be a String of the form: oldBootPassword, newBootPassword
836:
837: @exception StandardException Standard Cloudscape Error Policy
838: */
839: public Serializable changeBootPassword(Properties properties,
840: Serializable changePassword) throws StandardException;
841:
842: /**
843: * Return an id which can be used to create a container.
844: * <p>
845: * Return an id number with is greater than any existing container
846: * in the current database. Caller will use this to allocate future
847: * container numbers - most likely caching the value and then incrementing
848: * it as it is used.
849: * <p>
850: *
851: * @return The an id which can be used to create a container.
852: *
853: * @exception StandardException Standard exception policy.
854: **/
855: long getMaxContainerId() throws StandardException;
856:
857: /**
858: Get the Transaction Factory to use with this store.
859: */
860: public TransactionFactory getXactFactory();
861: }
|