KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > derby > iapi > store > raw > RawStoreFactory


1 /*
2
3    Derby - Class org.apache.derby.iapi.store.raw.RawStoreFactory
4
5    Licensed to the Apache Software Foundation (ASF) under one or more
6    contributor license agreements. See the NOTICE file distributed with
7    this work for additional information regarding copyright ownership.
8    The ASF licenses this file to you under the Apache License, Version 2.0
9    (the "License"); you may not use this file except in compliance with
10    the License. You may obtain a copy of the License at
11
12       http://www.apache.org/licenses/LICENSE-2.0
13
14    Unless required by applicable law or agreed to in writing, software
15    distributed under the License is distributed on an "AS IS" BASIS,
16    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17    See the License for the specific language governing permissions and
18    limitations under the License.
19
20  */

21
22 package org.apache.derby.iapi.store.raw;
23
24 import org.apache.derby.iapi.services.daemon.DaemonService;
25 import org.apache.derby.iapi.services.context.ContextManager;
26 import org.apache.derby.iapi.services.locks.LockFactory;
27
28 import org.apache.derby.iapi.services.property.PersistentSet;
29
30 import org.apache.derby.iapi.store.access.TransactionInfo;
31 import org.apache.derby.iapi.store.raw.xact.TransactionFactory;
32 import org.apache.derby.iapi.store.raw.log.LogInstant;
33 import org.apache.derby.iapi.error.StandardException;
34
35 import org.apache.derby.catalog.UUID;
36 import org.apache.derby.iapi.store.access.DatabaseInstant;
37 import org.apache.derby.iapi.error.ExceptionSeverity;
38 import java.util.Properties JavaDoc;
39 import java.io.Serializable JavaDoc;
40 import java.io.File JavaDoc;
41
42 /**
43     RawStoreFactory implements a single unit of transactional
44     storage. A RawStoreFactory contains Segments and Segments
45     contain Containers.
46     <P>
47     Segments are identified
48     by integer identifiers that are unique within a RawStoreFactory.
49     <P>
50     Containers are also identified by unique integer identifiers
51     within a RawStoreFactory, but will overlap with segment identifiers.
52     <P><B>LIMITS</B><BR>
53     This is a list of (hopefully) all limits within the raw store. Where a size
54     has more than one limit all are documented (rather than just the most
55     restrictive) so that the correct limit can be found if the most restictive
56     is every removed.
57     <UL>
58     <LI>Field -
59         <UL>
60         <LI>Max length 2^31 - 1 (2147483647) -
61         </UL>
62     <LI>Record -
63         <UL>
64         <LI>Max number of fields 2^31 - 1 (2147483647) - from use of Object[]
65         array to represent row, which can "only" have int sized number of array
66         members.
67         </UL>
68     <LI>Page -
69     <LI>Container -
70     <LI>Segment -
71     <LI>Raw Store -
72     </UL>
73
74     <P>
75     Access and RawStore work together to provide the ACID properties of
76     transactions. On a high level, RawStore deals with anything that directly
77     impacts persistency. On a more detailed level, RawStore provides
78     logging, rollback and recovery, data management on page, page allocation
79     and deallocation, container allocation and deallocation.
80
81
82     <P>
83     RawStore is organized as 3 branches, transaction, data, and
84     logging. These branches each have its own "factory", the transaction
85     factory hands out transactions, the data factory hands out containers,
86     and the log factory hands out logger (or log buffers) for transactions to
87     write on. For a more detailed description on these factories, please see
88     their corresponding javadocs.
89
90
91     MT - Thread Safe
92
93     @see ContainerHandle */

94
95
96 public interface RawStoreFactory extends Corruptable {
97
98     /** Store engine version numbers indicating the database must be upgraded to
99      * or created at the current engine level
100      */

101
102     /** Derby Store Minor Version (1) **/
103     public static final int DERBY_STORE_MINOR_VERSION_1 = 1;
104
105     /** Derby Store Minor Version (2) **/
106     public static final int DERBY_STORE_MINOR_VERSION_2 = 2;
107
108     /** Derby 10 Store Major version */
109     public static final int DERBY_STORE_MAJOR_VERSION_10 = 10;
110
111     /**
112         Default value for PAGE_SIZE_PARAMETER (4096).
113     */

114     public static final int PAGE_SIZE_DEFAULT = 4096;
115
116     /**
117         Minimum page size we will accept (1024).
118     */

119     public static final int PAGE_SIZE_MINIMUM = 1024;
120
121
122     public static final String JavaDoc PAGE_SIZE_STRING = "2048";
123
124
125     /** Property name for the page cache size to be used in the storage area.
126     Equal to 'derby.storage.pageCacheSize'
127     */

128     public static final String JavaDoc PAGE_CACHE_SIZE_PARAMETER =
129         "derby.storage.pageCacheSize";
130
131     /**
132         Default value for PAGE_CACHE_SIZE_PARAMETER (1000).
133     */

134     public static final int PAGE_CACHE_SIZE_DEFAULT = 1000;
135
136     /**
137         Minimum page cache size we will accept (40).
138     */

139     public static final int PAGE_CACHE_SIZE_MINIMUM = 40;
140
141     /**
142         Maximum page cache size we will accept (MAXINT).
143     */

144     public static final int PAGE_CACHE_SIZE_MAXIMUM = Integer.MAX_VALUE;
145
146     /**
147         Maximum number of initial pages when a container is created
148     */

149     public static final short MAX_CONTAINER_INITIAL_PAGES = 1000;
150
151     /** Property name for the default minimum record size to be used in the
152         storage area. Minimum record size is the minimum number of bytes that a
153         record will reserve on disk.
154     */

155     public static final String JavaDoc MINIMUM_RECORD_SIZE_PARAMETER =
156         "derby.storage.minimumRecordSize";
157     /**
158         Default value for MINIMUM_RECORD_SIZE_PARAMETER for heap tables that
159         allow overflow. By setting minimumRecordSize to 12 bytes, we
160         guarantee there is enough space to update the row even there is not
161         enough space on the page. The 12 bytes will guarantee there is room
162         for an overflow pointer (page + id).
163     */

164     public static final int MINIMUM_RECORD_SIZE_DEFAULT = 12;
165
166     /**
167         Minimum value for MINIMUM_RECORD_SIZE_PARAMETER (1).
168     */

169     public static final int MINIMUM_RECORD_SIZE_MINIMUM = 1;
170
171     /** Property name for percentage of space to leave free on page for updates.
172     */

173     public static final String JavaDoc PAGE_RESERVED_SPACE_PARAMETER =
174         "derby.storage.pageReservedSpace";
175
176     public static final String JavaDoc PAGE_RESERVED_ZERO_SPACE_STRING = "0";
177
178     /** Property name for the number of pages we try to pre-allocate in one
179     /** synchronous I/O
180     */

181     public static final String JavaDoc PRE_ALLOCATE_PAGE =
182         "derby.storage.pagePerAllocate";
183
184
185     /**
186         Property name for container which reuses recordId when a page is
187         reused. Defaults to false, which means recordId is never reused.
188
189         This property should NOT be set by the end user, only Access should set
190         it for special conglomerates which does not count on permanant unique
191         recordIds for all records.
192     */

193     public static final String JavaDoc PAGE_REUSABLE_RECORD_ID =
194         "derby.storage.reusableRecordId";
195
196     /**
197         Property name for buffer size to be used in the stream file container.
198         Equal to 'derby.storage.streamFileBufferSize'
199     */

200     public static final String JavaDoc STREAM_FILE_BUFFER_SIZE_PARAMETER =
201         "derby.storage.streamFileBufferSize";
202
203     /**
204         Default value for STREAM_FILE_BUFFER_SIZE_PARAMETER (16384).
205     */

206     public static final int STREAM_FILE_BUFFER_SIZE_DEFAULT = 16384;
207
208     /**
209         Minimum stream file buffer size we will accept (1024).
210     */

211     public static final int STREAM_FILE_BUFFER_SIZE_MINIMUM = 1024;
212
213     /**
214         Maximum stream file buffer size we will accept (MAXINT).
215     */

216     public static final int STREAM_FILE_BUFFER_SIZE_MAXIMUM =
217         Integer.MAX_VALUE;
218
219     /**
220
221         Property name for container which attempts to be created with an
222         initial size of this many pages. Defaults to 1 page.
223
224         <BR>All containers are guarenteed to be created with at least 1 page,
225         if this property is set, it will attempt to allocate
226         CONTAINER_INITIAL_PAGES, but with no guarentee.
227         CONTAIENR_INITIAL_PAGES legally ranges from 1 to
228         MAX_CONTAINER_INITIAL_PAGES. Values < 1 will
229         be set to 1 and values > MAX_CONTAINER_INITIAL_PAGES will be set to
230         MAX_CONTAINER_INITIAL_PAGES
231
232         This property should only be set in the PROPERTIES list in a CREATE
233         TABLE or CREATE INDEX statement. The global setting of this property
234         has no effect.
235     */

236     public static final String JavaDoc CONTAINER_INITIAL_PAGES =
237         "derby.storage.initialPages";
238
239     /**
240         encryption alignment requirement.
241      */

242     public static final int ENCRYPTION_ALIGNMENT = 8;
243
244     /**
245         default encryption block size
246         In old existing databases (ie 5.1.x), the default
247         encryption block size used is 8. Do not change this value unless you
248         account for downgrade issues
249      */

250     public static final int DEFAULT_ENCRYPTION_BLOCKSIZE = 8;
251
252     /**
253         encryption block size used during creation of encrypted database
254         This property is not set by the user; it is set by the engine when
255         RawStore boots up during creation of an encrypted database
256     */

257     public static final String JavaDoc ENCRYPTION_BLOCKSIZE = "derby.encryptionBlockSize";
258
259     /**
260
261         This variable is used to store the encryption scheme to allow
262         for any future changes in encryption schemes of data
263         This property has been introduced in version 10
264         Value starts at 1
265      */

266     public static final String JavaDoc DATA_ENCRYPT_ALGORITHM_VERSION="data_encrypt_algorithm_version";
267
268     /**
269                 Store the encryption scheme used for logging
270         This will allow for any future changes in encryption schemes of logs
271         This variable has been introduced in version 10 and value starts at 1.
272      */

273     public static final String JavaDoc LOG_ENCRYPT_ALGORITHM_VERSION="log_encrypt_algorithm_version";
274
275     /**
276         If dataEncryption is true, store the encrypted key in
277         services.properties file. It is really the encrypted
278         key, but the property key is called the encryptedBootPassword.
279
280      */

281     public static final String JavaDoc ENCRYPTED_KEY =
282         "encryptedBootPassword";
283
284
285     /**
286      * When the datbase is getting re-encrypted old encrypted key is
287      * stored in the service.properties until re-encyrption
288      * successfully completes or rolled back. It is really the old
289      * encryptedkey, but the property key is called the
290      * OldEncryptedBootPassword.
291      */

292     public static final String JavaDoc OLD_ENCRYPTED_KEY =
293         "OldEncryptedBootPassword";
294
295
296     /*
297      * Following property is used to track the status of the (re)encryption,
298      * required to bring the database back to state it was before the
299      * (re) encryption started, id (re) encryption of the database
300      * is aborted.
301      */

302     public static final String JavaDoc DB_ENCRYPTION_STATUS =
303         "derby.storage.databaseEncryptionStatus";
304
305     /* (re)encryption is in progress, if a crash
306      * occurs after this flag is set,
307      * (re)encryption needs to be undone.
308      */

309     public static final int DB_ENCRYPTION_IN_PROGRESS = 1;
310
311     /* this flag is used to track crash during undo
312        of (re) encryption during recovery .
313     */

314     public static final int DB_ENCRYPTION_IN_UNDO = 2;
315
316     /*
317      * Cleanup any (re) encryption related resources.
318      */

319     public static final int DB_ENCRYPTION_IN_CLEANUP = 3;
320
321     
322     /**
323        A File used to save the old copy of the verify key
324        (Attribute.CRYPTO_EXTERNAL_KEY_VERIFY_FILE) file during
325        re-encryption of the database.
326      */

327     String JavaDoc CRYPTO_OLD_EXTERNAL_KEY_VERIFY_FILE = "verifyOldKey.dat";
328
329
330
331     /**
332      * for debugging, keep all transaction logs intact.
333      */

334     public static final String JavaDoc KEEP_TRANSACTION_LOG =
335         "derby.storage.keepTransactionLog";
336
337     /**
338       * The following is a to enable patch for databases with recovery
339       * errors during redo of InitPage. If this property is set and
340       * the page on the disk is corrupted and is getting exceptions like
341       * invalid page format ids, we cook up the page during the recovery time.
342       * We have seen this kind of problem with 1.5.1 databases from
343       * customer Tridium ( Bug no: 3813).
344       * This patch needs to be kept unless we find the problem is during
345       * recovery process. If we discover this problem is actaully happening
346       * at the recovery then this patch should be backed out.
347       **/

348     public static final String JavaDoc PATCH_INITPAGE_RECOVER_ERROR =
349         "derby.storage.patchInitPageRecoverError";
350
351
352     /** module name */
353     public static final String JavaDoc MODULE =
354         "org.apache.derby.iapi.store.raw.RawStoreFactory";
355
356     /**
357         Is the store read-only.
358     */

359     public boolean isReadOnly();
360
361     /**
362         Get the LockFactory to use with this store.
363     */

364     public LockFactory getLockFactory();
365
366
367     /**
368         Create a user transaction, almost all work within the raw store is
369         performed in the context of a transaction.
370         <P>
371         Starting a transaction always performs the following steps.
372         <OL>
373         <LI>Create an raw store transaction context
374         <LI>Create a new idle transaction and then link it to the context.
375         </UL>
376         Only one user transaction and one nested user transaction can be active
377         in a context at any one time.
378         After a commit the transaction may be re-used.
379         <P>
380         <B>Raw Store Transaction Context Behaviour</B>
381         <BR>
382         The cleanupOnError() method of this context behaves as follows:
383         <UL>
384         <LI>
385         If error is an instance of StandardException that
386         has a severity less than ExceptionSeverity.TRANSACTION_SEVERITY then
387         no action is taken.
388         <LI>
389         If error is an instance of StandardException that
390         has a severity equal to ExceptionSeverity.TRANSACTION_SEVERITY then
391         the context's transaction is aborted, and the transaction returned to
392         the idle state.
393         <LI>
394         If error is an instance of StandardException that
395         has a severity greater than ExceptionSeverity.TRANSACTION_SEVERITY
396         then the context's transaction is aborted, the transaction closed, and
397         the context is popped off the stack.
398         <LI>
399         If error is not an instance of StandardException then the context's
400         transaction is aborted, the transaction closed, and the
401         context is popped off the stack.
402         </UL>
403
404         @param contextMgr is the context manager to use. An exception will be
405         thrown if context is not the current context.
406         @param transName is the name of the transaction. Thsi name will be displayed
407         by the transactiontable VTI.
408
409         @exception StandardException Standard Cloudscape error policy
410
411         @see Transaction
412         @see org.apache.derby.iapi.services.context.Context
413         @see StandardException
414     */

415
416     public Transaction startTransaction(
417     ContextManager contextMgr,
418     String JavaDoc transName)
419         throws StandardException;
420
421     /**
422         Create a global user transaction, almost all work within the raw store
423         is performed in the context of a transaction.
424         <P>
425         The (format_id, global_id, branch_id) triplet is meant to come exactly
426         from a javax.transaction.xa.Xid. We don't use Xid so that the system
427         can be delivered on a non-1.2 vm system and not require the javax
428         classes in the path.
429         <P>
430         Starting a transaction always performs the following steps.
431         <OL>
432         <LI>Create an raw store transaction context
433         <LI>Create a new idle transaction and then link it to the context.
434         </UL>
435         Only one user transaction can be active in a context at any one time.
436         After a commit the transaction may be re-used.
437         <P>
438         <B>Raw Store Transaction Context Behaviour</B>
439         <BR>
440         The cleanupOnError() method of this context behaves as follows:
441         <UL>
442         <LI>
443         If error is an instance of StandardException that
444         has a severity less than ExceptionSeverity.TRANSACTION_SEVERITY then
445         no action is taken.
446         <LI>
447         If error is an instance of StandardException that
448         has a severity equal to ExceptionSeverity.TRANSACTION_SEVERITY then
449         the context's transaction is aborted, and the transaction returned to
450         the idle state.
451         <LI>
452         If error is an instance of StandardException that
453         has a severity greater than ExceptionSeverity.TRANSACTION_SEVERITY
454         then the context's transaction is aborted, the transaction closed, and
455         the context is popped off the stack.
456         <LI>
457         If error is not an instance of StandardException then the context's
458         transaction is aborted, the transaction closed, and the
459         context is popped off the stack.
460         </UL>
461
462         @param contextMgr is the context manager to use. An exception will be
463                           thrown if context is not the current context.
464         @param format_id the format id part of the Xid - ie. Xid.getFormatId().
465         @param global_id the global transaction identifier part of XID - ie.
466                           Xid.getGlobalTransactionId().
467         @param local_id The branch qualifier of the Xid - ie.
468                           Xid.getBranchQaulifier()
469
470         @exception StandardException Standard Cloudscape error policy
471
472         @see Transaction
473         @see org.apache.derby.iapi.services.context.Context
474         @see StandardException
475     */

476     public Transaction startGlobalTransaction(
477     ContextManager contextMgr,
478     int format_id,
479     byte[] global_id,
480     byte[] local_id)
481         throws StandardException;
482
483
484     /**
485         Find a user transaction in the context manager, which must be the
486         current context manager. If a user transaction does not already exist,
487         then create one @see #startTransaction
488
489         @param contextMgr the context manager to use. An exception will be
490                           thrown if context is not the current context.
491         @param transName If a new transaction is started, it will be given
492                           this name.
493         The name is displayed in the transactiontable VTI.
494
495         @exception StandardException Standard Cloudscape error policy
496
497         @see #startTransaction
498     */

499     public Transaction findUserTransaction(
500         ContextManager contextMgr,
501         String JavaDoc transName) throws StandardException;
502
503
504     /**
505         Create an internal transaction.
506         <P>
507         Starting an internal transaction always performs the following steps.
508         <OL>
509         <LI>Create an raw store internal transaction context
510         <LI>Create a new idle internal transaction and then link it to the
511             context.
512         </UL>
513         <P>
514         AN internal transaction is identical to a user transaction with the
515         exception that
516         <UL>
517         <LI> Logical operations are not supported
518         <LI> Savepoints are not supported
519         <LI> Containers are not closed when commit() is called.
520         <LI> Pages are not unlatched (since containers are not closed) when
521              commit() is called.
522         <LI> During recovery time internal transactions are rolled back before
523              user transactions.
524         </UL>
525         Only one internal transaction can be active in a context at any one time.
526         After a commit the transaction may be re-used.
527         <P>
528         <B>Raw Store Internal Transaction Context Behaviour</B>
529         <BR>
530         The cleanupOnError() method of this context behaves as follows:
531         <UL>
532         <LI>
533         If error is an instance of StandardException that
534         has a severity less than ExceptionSeverity.TRANSACTION_SEVERITY then
535         the internal transaction is aborted, the internal transaction is closed, the context is popped off the stack, and an exception of severity
536         Transaction exception is re-thrown.
537         <LI>
538         If error is an instance of StandardException that has a severity
539         greater than or equal to ExceptionSeverity.TRANSACTION_SEVERITY then
540         the context's internal transaction is aborted, the internal
541         transaction is closed and the context is popped off the stack.
542         <LI>
543         If error is not an instance of StandardException then the context's
544         internal transaction is aborted, the internal transaction is closed
545         and the context is popped off the stack.
546         </UL>
547
548         @exception StandardException Standard Cloudscape error policy
549
550         @see Transaction
551         @see org.apache.derby.iapi.services.context.Context
552         @see StandardException
553     */

554     public Transaction startInternalTransaction(ContextManager contextMgr) throws StandardException;
555
556     /**
557         Create a nested user transaction, almost all work within the raw store
558         is performed in the context of a transaction.
559         <P>
560         A nested user transaction is exactly the same as a user transaction,
561         except that one can specify a compatibility space to associate with
562         the transaction.
563         Starting a transaction always performs the following steps.
564         <OL>
565         <LI>Create an raw store transaction context
566         <LI>Create a new idle transaction and then link it to the context.
567         </UL>
568         Only one user transaction and one nested user transaction can be active
569         in a context at any one time.
570         After a commit the transaction may be re-used.
571         <P>
572         <B>Raw Store Transaction Context Behaviour</B>
573         <BR>
574         The cleanupOnError() method of this context behaves as follows:
575         <UL>
576         <LI>
577         If error is an instance of StandardException that
578         has a severity less than ExceptionSeverity.TRANSACTION_SEVERITY then
579         no action is taken.
580         <LI>
581         If error is an instance of StandardException that
582         has a severity equal to ExceptionSeverity.TRANSACTION_SEVERITY then
583         the context's transaction is aborted, and the transaction returned to
584         the idle state. If a user transaction exists on the context stack
585         then that transaction is aborted also.
586         <LI>
587         If error is an instance of StandardException that
588         has a severity greater than ExceptionSeverity.TRANSACTION_SEVERITY
589         then the context's transaction is aborted, the transaction closed, and
590         the context is popped off the stack.
591         <LI>
592         If error is not an instance of StandardException then the context's
593         transaction is aborted, the transaction closed, and the
594         context is popped off the stack.
595         </UL>
596
597         @param compatibilitySpace compatibility space to use for locks.
598         @param contextMgr is the context manager to use. An exception will be
599         thrown if context is not the current context.
600         @param transName is the name of the transaction. This name will be
601         displayed by the transactiontable VTI.
602
603         @exception StandardException Standard Cloudscape error policy
604
605         @see Transaction
606         @see org.apache.derby.iapi.services.context.Context
607         @see StandardException
608     */

609
610     public Transaction startNestedReadOnlyUserTransaction(
611     Object JavaDoc compatibilitySpace,
612     ContextManager contextMgr,
613     String JavaDoc transName)
614         throws StandardException;
615
616     /**
617         Create a nested user transaction, almost all work within the raw store
618         is performed in the context of a transaction.
619         <P>
620         A nested user transaction is exactly the same as a user transaction,
621         except that one can specify a compatibility space to associate with
622         the transaction.
623         Starting a transaction always performs the following steps.
624         <OL>
625         <LI>Create an raw store transaction context
626         <LI>Create a new idle transaction and then link it to the context.
627         </UL>
628         Only one user transaction and one nested user transaction can be active
629         in a context at any one time.
630         After a commit the transaction may be re-used.
631         <P>
632         <B>Raw Store Transaction Context Behaviour</B>
633         <BR>
634         The cleanupOnError() method of this context behaves as follows:
635         <UL>
636         <LI>
637         If error is an instance of StandardException that
638         has a severity less than ExceptionSeverity.TRANSACTION_SEVERITY then
639         no action is taken.
640         <LI>
641         If error is an instance of StandardException that
642         has a severity equal to ExceptionSeverity.TRANSACTION_SEVERITY then
643         the context's transaction is aborted, and the transaction returned to
644         the idle state. If a user transaction exists on the context stack
645         then that transaction is aborted also.
646         <LI>
647         If error is an instance of StandardException that
648         has a severity greater than ExceptionSeverity.TRANSACTION_SEVERITY
649         then the context's transaction is aborted, the transaction closed, and
650         the context is popped off the stack.
651         <LI>
652         If error is not an instance of StandardException then the context's
653         transaction is aborted, the transaction closed, and the
654         context is popped off the stack.
655         </UL>
656
657         @param contextMgr is the context manager to use. An exception will be
658         thrown if context is not the current context.
659         @param transName is the name of the transaction. This name will be
660         displayed by the transactiontable VTI.
661
662         @exception StandardException Standard Cloudscape error policy
663
664         @see Transaction
665         @see org.apache.derby.iapi.services.context.Context
666         @see StandardException
667     */

668
669     public Transaction startNestedUpdateUserTransaction(
670     ContextManager contextMgr,
671     String JavaDoc transName)
672         throws StandardException;
673
674
675     /**
676       @see org.apache.derby.iapi.store.access.AccessFactory#getTransactionInfo
677      */

678     public TransactionInfo[] getTransactionInfo();
679
680     /**
681       * Freeze the database temporarily so a backup can be taken.
682       * <P>Please see cloudscape on line documentation on backup and restore.
683       *
684       * @exception StandardException Thrown on error
685       */

686     public void freeze() throws StandardException;
687
688     /**
689       * Unfreeze the database after a backup has been taken.
690       * <P>Please see cloudscape on line documentation on backup and restore.
691       *
692       * @exception StandardException Thrown on error
693       */

694     public void unfreeze() throws StandardException;
695
696     /**
697       * Backup the database to backupDir.
698       * <P>Please see cloudscape on line documentation on backup and restore.
699       *
700       * @param backupDir the name of the directory where the backup should be
701       * stored.
702       * @param wait if <tt>true</tt>, waits for all the backup blocking
703       * operations in progress to finish.
704       *
705       * @exception StandardException Thrown on error
706       */

707     public void backup(
708     String JavaDoc backupDir,
709     boolean wait) throws StandardException;
710
711         
712     /**
713      * Backup the database to a backup directory and enable the log archive
714      * mode that will keep the archived log files required for roll-forward
715      * from this version backup.
716      *
717      * @param backupDir the directory name where the
718      * database backup should go. This
719      * directory will be created if not it
720      * does not exist.
721      *
722      * @param deleteOnlineArchivedLogFiles If true deletes online archived log
723      * files that exist before this backup,
724      * delete will occur only after backup
725      * is complete.
726      *
727      * @param wait if <tt>true</tt>, waits for all the backup blocking
728      * operations in progress to finish.
729      *
730      * @exception StandardException Thrown on error
731      */

732     public void backupAndEnableLogArchiveMode(
733     String JavaDoc backupDir,
734     boolean deleteOnlineArchivedLogFiles,
735     boolean wait)
736         throws StandardException;
737         
738     /**
739      * disables the log archival process, i.e No old log files
740      * will be kept around for a roll-forward recovery.
741      *
742      * @param deleteOnlineArchivedLogFiles If true deletes all online archived
743      * log files that exist before this
744      * call immediately; Only restore that
745      * can be performed after disabling
746      * log archive mode is version
747      * recovery.
748      *
749      * @exception StandardException Thrown on error
750      */

751     public void disableLogArchiveMode(boolean deleteOnlineArchivedLogFiles)
752         throws StandardException;
753
754
755     /**
756         Try to checkpoint the database to minimize recovery time.
757         The raw store does not guarentee that a checkpoint will indeed have
758         happened by the time this routine returns.
759
760         @exception StandardException Standard Cloudscape error policy
761     */

762     public void checkpoint() throws StandardException;
763
764
765     /**
766         Idle the raw store as much as possible.
767         @exception StandardException Standard Cloudscape error policy
768
769     */

770     public void idle() throws StandardException;
771
772     /**
773         Get a flushed scan.
774         @param start The instant for the beginning of the scan.
775         @param groupsIWant log record groups the caller wants to scan.
776         @exception StandardException StandardCloudscape error policy
777         */

778     ScanHandle openFlushedScan(DatabaseInstant start, int groupsIWant)
779          throws StandardException;
780
781     
782     /**
783         If this raw store has a daemon that services its need, return the
784         daemon. If not, return null
785     */

786     public DaemonService getDaemon();
787
788
789     /*
790      * return the transaction factory module
791      */

792     public String JavaDoc getTransactionFactoryModule();
793
794     /*
795      * return the data factory module
796      */

797     public String JavaDoc getDataFactoryModule();
798
799     /*
800      * return the Log factory module
801      */

802     public String JavaDoc getLogFactoryModule();
803
804     /*
805      * Return the module providing XAresource interface to the transaction
806      * table.
807      *
808      * @exception StandardException Standard cloudscape exception policy.
809      */

810     public /* XAResourceManager */ Object JavaDoc getXAResourceManager()
811         throws StandardException;
812
813     /*
814      * the database creation phase is finished
815      * @exception StandardException Standard cloudscape exception policy.
816      */

817     public void createFinished() throws StandardException;
818
819     /**
820      * Get JBMS properties relavent to raw store
821      *
822      * @exception StandardException Standard cloudscape exception policy.
823      */

824     public void getRawStoreProperties(PersistentSet tc)
825          throws StandardException;
826
827     /**
828      * Backup / restore support
829      */

830
831     /**
832      * Freeze the database from altering any persistent storage.
833      *
834      * @exception StandardException Standard cloudscape exception policy.
835      */

836     public void freezePersistentStore() throws StandardException;
837
838     /**
839      * Unfreeze the database, persistent storage can now be altered.
840      *
841      * @exception StandardException Standard cloudscape exception policy.
842      */

843     public void unfreezePersistentStore() throws StandardException;
844
845     /**
846         Encrypt cleartext into ciphertext.
847
848         @see org.apache.derby.iapi.services.crypto.CipherProvider#encrypt
849         @exception StandardException Standard Cloudscape Error Policy
850      */

851     public int encrypt(byte[] cleartext, int offset, int length,
852                        byte[] ciphertext, int outputOffset,
853                        boolean newEngine)
854          throws StandardException ;
855
856     /**
857         Decrypt cleartext from ciphertext.
858
859         @see org.apache.derby.iapi.services.crypto.CipherProvider#decrypt
860         @exception StandardException Standard Cloudscape Error Policy
861      */

862     public int decrypt(byte[] ciphertext, int offset, int length,
863                        byte[] cleartext, int outputOffset)
864          throws StandardException ;
865
866     /**
867         Returns the encryption block size used during creation of the encrypted database
868      */

869     public int getEncryptionBlockSize();
870
871     /**
872         Returns a secure random number for this raw store - if database is not
873         encrypted, returns 0.
874      */

875     public int random();
876
877     /**
878         Change the boot password. Return the encrypted form of the secret key.
879         The new value must be a String of the form: oldBootPassword, newBootPassword
880
881         @exception StandardException Standard Cloudscape Error Policy
882      */

883     public Serializable JavaDoc changeBootPassword(Properties JavaDoc properties, Serializable JavaDoc changePassword)
884          throws StandardException ;
885
886     /**
887      * Return an id which can be used to create a container.
888      * <p>
889      * Return an id number with is greater than any existing container
890      * in the current database. Caller will use this to allocate future
891      * container numbers - most likely caching the value and then incrementing
892      * it as it is used.
893      * <p>
894      *
895      * @return The an id which can be used to create a container.
896      *
897      * @exception StandardException Standard exception policy.
898      **/

899     long getMaxContainerId()
900         throws StandardException;
901
902
903     /**
904         Get the Transaction Factory to use with this store.
905     */

906     public TransactionFactory getXactFactory();
907 }
908
Popular Tags