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  ;
39  import java.io.Serializable  ;
40  import java.io.File  ;
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   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   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   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   PAGE_RESERVED_SPACE_PARAMETER = 
174         "derby.storage.pageReservedSpace";
175 
176     public static final String   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   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   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   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   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   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   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   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   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   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   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   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   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   PATCH_INITPAGE_RECOVER_ERROR = 
349         "derby.storage.patchInitPageRecoverError";
350 
351 
352     /** module name */
353     public static final String   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   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   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           compatibilitySpace,
612     ContextManager contextMgr,
613     String           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           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   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    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   getTransactionFactoryModule();
793 
794     /*
795      * return the data factory module 
796      */
797     public String   getDataFactoryModule();
798 
799     /*
800      * return the Log factory module 
801      */
802     public String   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   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   changeBootPassword(Properties   properties, Serializable   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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags