--- /dev/null
+/*\r
+\r
+ Derby - Class org.apache.derby.iapi.store.raw.RawStoreFactory\r
+\r
+ Licensed to the Apache Software Foundation (ASF) under one or more\r
+ contributor license agreements. See the NOTICE file distributed with\r
+ this work for additional information regarding copyright ownership.\r
+ The ASF licenses this file to you under the Apache License, Version 2.0\r
+ (the "License"); you may not use this file except in compliance with\r
+ the License. You may obtain a copy of the License at\r
+\r
+ http://www.apache.org/licenses/LICENSE-2.0\r
+\r
+ Unless required by applicable law or agreed to in writing, software\r
+ distributed under the License is distributed on an "AS IS" BASIS,\r
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
+ See the License for the specific language governing permissions and\r
+ limitations under the License.\r
+\r
+ */\r
+\r
+package org.apache.derby.iapi.store.raw;\r
+\r
+import org.apache.derby.iapi.services.daemon.DaemonService;\r
+import org.apache.derby.iapi.services.context.ContextManager;\r
+import org.apache.derby.iapi.services.locks.CompatibilitySpace;\r
+import org.apache.derby.iapi.services.locks.LockFactory;\r
+\r
+import org.apache.derby.iapi.services.property.PersistentSet;\r
+\r
+import org.apache.derby.iapi.store.access.TransactionInfo;\r
+import org.apache.derby.iapi.store.raw.xact.TransactionFactory;\r
+import org.apache.derby.iapi.store.raw.log.LogInstant;\r
+import org.apache.derby.iapi.error.StandardException;\r
+\r
+import org.apache.derby.catalog.UUID;\r
+import org.apache.derby.iapi.store.access.DatabaseInstant;\r
+import org.apache.derby.iapi.error.ExceptionSeverity;\r
+import java.util.Properties;\r
+import java.io.Serializable;\r
+import java.io.File;\r
+\r
+/**\r
+ RawStoreFactory implements a single unit of transactional\r
+ storage. A RawStoreFactory contains Segments and Segments\r
+ contain Containers.\r
+ <P>\r
+ Segments are identified\r
+ by integer identifiers that are unique within a RawStoreFactory.\r
+ <P>\r
+ Containers are also identified by unique integer identifiers\r
+ within a RawStoreFactory, but will overlap with segment identifiers.\r
+ <P><B>LIMITS</B><BR>\r
+ This is a list of (hopefully) all limits within the raw store. Where a size \r
+ has more than one limit all are documented (rather than just the most \r
+ restrictive) so that the correct limit can be found if the most restictive \r
+ is every removed.\r
+ <UL>\r
+ <LI>Field - \r
+ <UL>\r
+ <LI>Max length 2^31 - 1 (2147483647) - \r
+ </UL>\r
+ <LI>Record - \r
+ <UL>\r
+ <LI>Max number of fields 2^31 - 1 (2147483647) - from use of Object[] \r
+ array to represent row, which can "only" have int sized number of array\r
+ members.\r
+ </UL>\r
+ <LI>Page -\r
+ <LI>Container -\r
+ <LI>Segment -\r
+ <LI>Raw Store -\r
+ </UL>\r
+\r
+ <P>\r
+ Access and RawStore work together to provide the ACID properties of\r
+ transactions. On a high level, RawStore deals with anything that directly\r
+ impacts persistency. On a more detailed level, RawStore provides\r
+ logging, rollback and recovery, data management on page, page allocation\r
+ and deallocation, container allocation and deallocation. \r
+\r
+\r
+ <P>\r
+ RawStore is organized as 3 branches, transaction, data, and\r
+ logging. These branches each have its own "factory", the transaction\r
+ factory hands out transactions, the data factory hands out containers,\r
+ and the log factory hands out logger (or log buffers) for transactions to\r
+ write on. For a more detailed description on these factories, please see\r
+ their corresponding javadocs.\r
+\r
+\r
+ MT - Thread Safe\r
+\r
+ @see ContainerHandle */\r
+\r
+\r
+public interface RawStoreFactory extends Corruptable {\r
+\r
+ /** Store engine version numbers indicating the database must be upgraded to \r
+ * or created at the current engine level \r
+ */\r
+\r
+ /** Derby Store Minor Version (1) **/\r
+ public static final int DERBY_STORE_MINOR_VERSION_1 = 1;\r
+\r
+ /** Derby Store Minor Version (2) **/\r
+ public static final int DERBY_STORE_MINOR_VERSION_2 = 2;\r
+\r
+ /** Derby Store Minor Version (3) **/\r
+ public static final int DERBY_STORE_MINOR_VERSION_3 = 3;\r
+\r
+ /** Derby 10 Store Major version */\r
+ public static final int DERBY_STORE_MAJOR_VERSION_10 = 10;\r
+\r
+ /**\r
+ Default value for PAGE_SIZE_PARAMETER (4096).\r
+ */\r
+ public static final int PAGE_SIZE_DEFAULT = 4096;\r
+\r
+ /**\r
+ Minimum page size we will accept (1024).\r
+ */\r
+ public static final int PAGE_SIZE_MINIMUM = 1024;\r
+\r
+\r
+ public static final String PAGE_SIZE_STRING = "2048";\r
+\r
+\r
+ /** Property name for the page cache size to be used in the storage area.\r
+ Equal to 'derby.storage.pageCacheSize'\r
+ */\r
+ public static final String PAGE_CACHE_SIZE_PARAMETER = \r
+ "derby.storage.pageCacheSize";\r
+\r
+ /**\r
+ Default value for PAGE_CACHE_SIZE_PARAMETER (1000).\r
+ */\r
+ public static final int PAGE_CACHE_SIZE_DEFAULT = 1000;\r
+\r
+ /**\r
+ Minimum page cache size we will accept (40).\r
+ */\r
+ public static final int PAGE_CACHE_SIZE_MINIMUM = 40;\r
+\r
+ /**\r
+ Maximum page cache size we will accept (MAXINT).\r
+ */\r
+ public static final int PAGE_CACHE_SIZE_MAXIMUM = Integer.MAX_VALUE;\r
+\r
+ /**\r
+ Maximum number of initial pages when a container is created\r
+ */\r
+ public static final short MAX_CONTAINER_INITIAL_PAGES = 1000;\r
+\r
+ /** Property name for the default minimum record size to be used in the \r
+ storage area. Minimum record size is the minimum number of bytes that a \r
+ record will reserve on disk.\r
+ */\r
+ public static final String MINIMUM_RECORD_SIZE_PARAMETER = \r
+ "derby.storage.minimumRecordSize";\r
+ /**\r
+ Default value for MINIMUM_RECORD_SIZE_PARAMETER for heap tables that \r
+ allow overflow. By setting minimumRecordSize to 12 bytes, we \r
+ guarantee there is enough space to update the row even there is not\r
+ enough space on the page. The 12 bytes will guarantee there is room\r
+ for an overflow pointer (page + id).\r
+ */\r
+ public static final int MINIMUM_RECORD_SIZE_DEFAULT = 12;\r
+\r
+ /**\r
+ Minimum value for MINIMUM_RECORD_SIZE_PARAMETER (1).\r
+ */\r
+ public static final int MINIMUM_RECORD_SIZE_MINIMUM = 1;\r
+\r
+ /** Property name for percentage of space to leave free on page for updates.\r
+ */\r
+ public static final String PAGE_RESERVED_SPACE_PARAMETER = \r
+ "derby.storage.pageReservedSpace";\r
+\r
+ public static final String PAGE_RESERVED_ZERO_SPACE_STRING = "0";\r
+\r
+ /** Property name for the number of pages we try to pre-allocate in one\r
+ /** synchronous I/O\r
+ */\r
+ public static final String PRE_ALLOCATE_PAGE = \r
+ "derby.storage.pagePerAllocate";\r
+\r
+\r
+ /**\r
+ Property name for container which reuses recordId when a page is\r
+ reused. Defaults to false, which means recordId is never reused. \r
+\r
+ This property should NOT be set by the end user, only Access should set\r
+ it for special conglomerates which does not count on permanant unique\r
+ recordIds for all records.\r
+ */\r
+ public static final String PAGE_REUSABLE_RECORD_ID = \r
+ "derby.storage.reusableRecordId";\r
+\r
+ /**\r
+ Property name for buffer size to be used in the stream file container.\r
+ Equal to 'derby.storage.streamFileBufferSize'\r
+ */\r
+ public static final String STREAM_FILE_BUFFER_SIZE_PARAMETER = \r
+ "derby.storage.streamFileBufferSize";\r
+\r
+ /**\r
+ Default value for STREAM_FILE_BUFFER_SIZE_PARAMETER (16384).\r
+ */\r
+ public static final int STREAM_FILE_BUFFER_SIZE_DEFAULT = 16384;\r
+\r
+ /**\r
+ Minimum stream file buffer size we will accept (1024).\r
+ */\r
+ public static final int STREAM_FILE_BUFFER_SIZE_MINIMUM = 1024;\r
+\r
+ /**\r
+ Maximum stream file buffer size we will accept (MAXINT).\r
+ */\r
+ public static final int STREAM_FILE_BUFFER_SIZE_MAXIMUM = \r
+ Integer.MAX_VALUE;\r
+\r
+ /**\r
+\r
+ Property name for container which attempts to be created with an\r
+ initial size of this many pages. Defaults to 1 page. \r
+\r
+ <BR>All containers are guarenteed to be created with at least 1 page,\r
+ if this property is set, it will attempt to allocate\r
+ CONTAINER_INITIAL_PAGES, but with no guarentee.\r
+ CONTAIENR_INITIAL_PAGES legally ranges from 1 to\r
+ MAX_CONTAINER_INITIAL_PAGES. Values < 1 will\r
+ be set to 1 and values > MAX_CONTAINER_INITIAL_PAGES will be set to\r
+ MAX_CONTAINER_INITIAL_PAGES\r
+\r
+ This property should only be set in the PROPERTIES list in a CREATE\r
+ TABLE or CREATE INDEX statement. The global setting of this property\r
+ has no effect. \r
+ */\r
+ public static final String CONTAINER_INITIAL_PAGES = \r
+ "derby.storage.initialPages";\r
+\r
+ /**\r
+ encryption alignment requirement.\r
+ */\r
+ public static final int ENCRYPTION_ALIGNMENT = 8;\r
+\r
+ /**\r
+ default encryption block size\r
+ In old existing databases (ie 5.1.x), the default\r
+ encryption block size used is 8. Do not change this value unless you \r
+ account for downgrade issues\r
+ */\r
+ public static final int DEFAULT_ENCRYPTION_BLOCKSIZE = 8;\r
+\r
+ /**\r
+ encryption block size used during creation of encrypted database\r
+ This property is not set by the user; it is set by the engine when\r
+ RawStore boots up during creation of an encrypted database\r
+ */\r
+ public static final String ENCRYPTION_BLOCKSIZE = "derby.encryptionBlockSize";\r
+\r
+ /**\r
+\r
+ This variable is used to store the encryption scheme to allow\r
+ for any future changes in encryption schemes of data \r
+ This property has been introduced in version 10\r
+ Value starts at 1\r
+ */\r
+ public static final String DATA_ENCRYPT_ALGORITHM_VERSION="data_encrypt_algorithm_version";\r
+\r
+ /**\r
+ Store the encryption scheme used for logging\r
+ This will allow for any future changes in encryption schemes of logs\r
+ This variable has been introduced in version 10 and value starts at 1.\r
+ */\r
+ public static final String LOG_ENCRYPT_ALGORITHM_VERSION="log_encrypt_algorithm_version";\r
+\r
+ /**\r
+ If dataEncryption is true, store the encrypted key in\r
+ services.properties file. It is really the encrypted\r
+ key, but the property key is called the encryptedBootPassword.\r
+\r
+ */\r
+ public static final String ENCRYPTED_KEY = \r
+ "encryptedBootPassword";\r
+\r
+\r
+ /**\r
+ * When the datbase is getting re-encrypted old encrypted key is \r
+ * stored in the service.properties until re-encyrption\r
+ * successfully completes or rolled back. It is really the old \r
+ * encryptedkey, but the property key is called the \r
+ * OldEncryptedBootPassword.\r
+ */\r
+ public static final String OLD_ENCRYPTED_KEY = \r
+ "OldEncryptedBootPassword";\r
+\r
+\r
+ /*\r
+ * Following property is used to track the status of the (re)encryption,\r
+ * required to bring the database back to state it was before the \r
+ * (re) encryption started, id (re) encryption of the database \r
+ * is aborted.\r
+ */\r
+ public static final String DB_ENCRYPTION_STATUS =\r
+ "derby.storage.databaseEncryptionStatus";\r
+\r
+ /* (re)encryption is in progress, if a crash \r
+ * occurs after this flag is set, \r
+ * (re)encryption needs to be undone.\r
+ */\r
+ public static final int DB_ENCRYPTION_IN_PROGRESS = 1;\r
+\r
+ /* this flag is used to track crash during undo\r
+ of (re) encryption during recovery .\r
+ */\r
+ public static final int DB_ENCRYPTION_IN_UNDO = 2;\r
+\r
+ /*\r
+ * Cleanup any (re) encryption related resources. \r
+ */\r
+ public static final int DB_ENCRYPTION_IN_CLEANUP = 3;\r
+\r
+ \r
+ /**\r
+ A File used to save the old copy of the verify key \r
+ (Attribute.CRYPTO_EXTERNAL_KEY_VERIFY_FILE) file during \r
+ re-encryption of the database. \r
+ */\r
+ String CRYPTO_OLD_EXTERNAL_KEY_VERIFY_FILE = "verifyOldKey.dat";\r
+\r
+\r
+\r
+ /**\r
+ * for debugging, keep all transaction logs intact.\r
+ */\r
+ public static final String KEEP_TRANSACTION_LOG = \r
+ "derby.storage.keepTransactionLog";\r
+\r
+ /**\r
+ * The following is a to enable patch for databases with recovery\r
+ * errors during redo of InitPage. If this property is set and\r
+ * the page on the disk is corrupted and is getting exceptions like\r
+ * invalid page format ids, we cook up the page during the recovery time.\r
+ * We have seen this kind of problem with 1.5.1 databases from\r
+ * customer Tridium ( Bug no: 3813).\r
+ * This patch needs to be kept unless we find the problem is during\r
+ * recovery process. If we discover this problem is actaully happening\r
+ * at the recovery then this patch should be backed out.\r
+ **/\r
+ public static final String PATCH_INITPAGE_RECOVER_ERROR = \r
+ "derby.storage.patchInitPageRecoverError";\r
+\r
+\r
+ /** module name */\r
+ public static final String MODULE = \r
+ "org.apache.derby.iapi.store.raw.RawStoreFactory";\r
+\r
+ /**\r
+ Is the store read-only.\r
+ */\r
+ public boolean isReadOnly();\r
+\r
+ /**\r
+ Get the LockFactory to use with this store.\r
+ */\r
+ public LockFactory getLockFactory();\r
+\r
+\r
+ /**\r
+ Create a user transaction, almost all work within the raw store is\r
+ performed in the context of a transaction.\r
+ <P>\r
+ Starting a transaction always performs the following steps.\r
+ <OL>\r
+ <LI>Create an raw store transaction context\r
+ <LI>Create a new idle transaction and then link it to the context.\r
+ </UL>\r
+ Only one user transaction and one nested user transaction can be active\r
+ in a context at any one time.\r
+ After a commit the transaction may be re-used.\r
+ <P>\r
+ <B>Raw Store Transaction Context Behaviour</B>\r
+ <BR>\r
+ The cleanupOnError() method of this context behaves as follows:\r
+ <UL>\r
+ <LI>\r
+ If error is an instance of StandardException that\r
+ has a severity less than ExceptionSeverity.TRANSACTION_SEVERITY then\r
+ no action is taken.\r
+ <LI>\r
+ If error is an instance of StandardException that\r
+ has a severity equal to ExceptionSeverity.TRANSACTION_SEVERITY then\r
+ the context's transaction is aborted, and the transaction returned to\r
+ the idle state.\r
+ <LI>\r
+ If error is an instance of StandardException that\r
+ has a severity greater than ExceptionSeverity.TRANSACTION_SEVERITY\r
+ then the context's transaction is aborted, the transaction closed, and\r
+ the context is popped off the stack.\r
+ <LI>\r
+ If error is not an instance of StandardException then the context's\r
+ transaction is aborted, the transaction closed, and the\r
+ context is popped off the stack.\r
+ </UL>\r
+\r
+ @param contextMgr is the context manager to use. An exception will be\r
+ thrown if context is not the current context.\r
+ @param transName is the name of the transaction. Thsi name will be displayed\r
+ by the transactiontable VTI.\r
+\r
+ @exception StandardException Standard Derby error policy\r
+\r
+ @see Transaction\r
+ @see org.apache.derby.iapi.services.context.Context\r
+ @see StandardException\r
+ */\r
+\r
+ public Transaction startTransaction(\r
+ ContextManager contextMgr,\r
+ String transName)\r
+ throws StandardException;\r
+\r
+ /**\r
+ Create a global user transaction, almost all work within the raw store\r
+ is performed in the context of a transaction.\r
+ <P>\r
+ The (format_id, global_id, branch_id) triplet is meant to come exactly\r
+ from a javax.transaction.xa.Xid. We don't use Xid so that the system\r
+ can be delivered on a non-1.2 vm system and not require the javax \r
+ classes in the path. \r
+ <P>\r
+ Starting a transaction always performs the following steps.\r
+ <OL>\r
+ <LI>Create an raw store transaction context\r
+ <LI>Create a new idle transaction and then link it to the context.\r
+ </UL>\r
+ Only one user transaction can be active in a context at any one time.\r
+ After a commit the transaction may be re-used.\r
+ <P>\r
+ <B>Raw Store Transaction Context Behaviour</B>\r
+ <BR>\r
+ The cleanupOnError() method of this context behaves as follows:\r
+ <UL>\r
+ <LI>\r
+ If error is an instance of StandardException that\r
+ has a severity less than ExceptionSeverity.TRANSACTION_SEVERITY then \r
+ no action is taken.\r
+ <LI>\r
+ If error is an instance of StandardException that\r
+ has a severity equal to ExceptionSeverity.TRANSACTION_SEVERITY then\r
+ the context's transaction is aborted, and the transaction returned to \r
+ the idle state.\r
+ <LI>\r
+ If error is an instance of StandardException that\r
+ has a severity greater than ExceptionSeverity.TRANSACTION_SEVERITY \r
+ then the context's transaction is aborted, the transaction closed, and \r
+ the context is popped off the stack.\r
+ <LI>\r
+ If error is not an instance of StandardException then the context's\r
+ transaction is aborted, the transaction closed, and the\r
+ context is popped off the stack.\r
+ </UL>\r
+\r
+ @param contextMgr is the context manager to use. An exception will be\r
+ thrown if context is not the current context.\r
+ @param format_id the format id part of the Xid - ie. Xid.getFormatId().\r
+ @param global_id the global transaction identifier part of XID - ie.\r
+ Xid.getGlobalTransactionId().\r
+ @param local_id The branch qualifier of the Xid - ie. \r
+ Xid.getBranchQaulifier()\r
+\r
+ @exception StandardException Standard Derby error policy\r
+\r
+ @see Transaction\r
+ @see org.apache.derby.iapi.services.context.Context\r
+ @see StandardException\r
+ */\r
+ public Transaction startGlobalTransaction(\r
+ ContextManager contextMgr,\r
+ int format_id,\r
+ byte[] global_id,\r
+ byte[] local_id)\r
+ throws StandardException;\r
+\r
+\r
+ /**\r
+ Find a user transaction in the context manager, which must be the\r
+ current context manager. If a user transaction does not already exist,\r
+ then create one @see #startTransaction\r
+\r
+ @param contextMgr the context manager to use. An exception will be \r
+ thrown if context is not the current context.\r
+ @param transName If a new transaction is started, it will be given \r
+ this name.\r
+ The name is displayed in the transactiontable VTI.\r
+\r
+ @exception StandardException Standard Derby error policy\r
+\r
+ @see #startTransaction\r
+ */\r
+ public Transaction findUserTransaction(\r
+ ContextManager contextMgr,\r
+ String transName) throws StandardException;\r
+\r
+\r
+ /**\r
+ Create an internal transaction.\r
+ <P>\r
+ Starting an internal transaction always performs the following steps.\r
+ <OL>\r
+ <LI>Create an raw store internal transaction context\r
+ <LI>Create a new idle internal transaction and then link it to the \r
+ context.\r
+ </UL>\r
+ <P>\r
+ AN internal transaction is identical to a user transaction with the \r
+ exception that\r
+ <UL>\r
+ <LI> Logical operations are not supported\r
+ <LI> Savepoints are not supported\r
+ <LI> Containers are not closed when commit() is called.\r
+ <LI> Pages are not unlatched (since containers are not closed) when \r
+ commit() is called.\r
+ <LI> During recovery time internal transactions are rolled back before \r
+ user transactions.\r
+ </UL>\r
+ Only one internal transaction can be active in a context at any one time.\r
+ After a commit the transaction may be re-used.\r
+ <P>\r
+ <B>Raw Store Internal Transaction Context Behaviour</B>\r
+ <BR>\r
+ The cleanupOnError() method of this context behaves as follows:\r
+ <UL>\r
+ <LI>\r
+ If error is an instance of StandardException that\r
+ has a severity less than ExceptionSeverity.TRANSACTION_SEVERITY then\r
+ the internal transaction is aborted, the internal transaction is closed, the context is popped off the stack, and an exception of severity \r
+ Transaction exception is re-thrown.\r
+ <LI>\r
+ If error is an instance of StandardException that has a severity \r
+ greater than or equal to ExceptionSeverity.TRANSACTION_SEVERITY then\r
+ the context's internal transaction is aborted, the internal \r
+ transaction is closed and the context is popped off the stack.\r
+ <LI>\r
+ If error is not an instance of StandardException then the context's\r
+ internal transaction is aborted, the internal transaction is closed \r
+ and the context is popped off the stack.\r
+ </UL>\r
+\r
+ @exception StandardException Standard Derby error policy\r
+\r
+ @see Transaction\r
+ @see org.apache.derby.iapi.services.context.Context\r
+ @see StandardException\r
+ */\r
+ public Transaction startInternalTransaction(ContextManager contextMgr) throws StandardException;\r
+\r
+ /**\r
+ Create a nested user transaction, almost all work within the raw store \r
+ is performed in the context of a transaction.\r
+ <P>\r
+ A nested user transaction is exactly the same as a user transaction,\r
+ except that one can specify a compatibility space to associate with\r
+ the transaction.\r
+ Starting a transaction always performs the following steps.\r
+ <OL>\r
+ <LI>Create an raw store transaction context\r
+ <LI>Create a new idle transaction and then link it to the context.\r
+ </UL>\r
+ Only one user transaction and one nested user transaction can be active\r
+ in a context at any one time.\r
+ After a commit the transaction may be re-used.\r
+ <P>\r
+ <B>Raw Store Transaction Context Behaviour</B>\r
+ <BR>\r
+ The cleanupOnError() method of this context behaves as follows:\r
+ <UL>\r
+ <LI>\r
+ If error is an instance of StandardException that\r
+ has a severity less than ExceptionSeverity.TRANSACTION_SEVERITY then\r
+ no action is taken.\r
+ <LI>\r
+ If error is an instance of StandardException that\r
+ has a severity equal to ExceptionSeverity.TRANSACTION_SEVERITY then\r
+ the context's transaction is aborted, and the transaction returned to\r
+ the idle state. If a user transaction exists on the context stack\r
+ then that transaction is aborted also.\r
+ <LI>\r
+ If error is an instance of StandardException that\r
+ has a severity greater than ExceptionSeverity.TRANSACTION_SEVERITY\r
+ then the context's transaction is aborted, the transaction closed, and\r
+ the context is popped off the stack.\r
+ <LI>\r
+ If error is not an instance of StandardException then the context's\r
+ transaction is aborted, the transaction closed, and the\r
+ context is popped off the stack.\r
+ </UL>\r
+\r
+ @param compatibilitySpace compatibility space to use for locks.\r
+ @param contextMgr is the context manager to use. An exception will be\r
+ thrown if context is not the current context.\r
+ @param transName is the name of the transaction. This name will be \r
+ displayed by the transactiontable VTI.\r
+\r
+ @exception StandardException Standard Derby error policy\r
+\r
+ @see Transaction\r
+ @see org.apache.derby.iapi.services.context.Context\r
+ @see StandardException\r
+ */\r
+\r
+ public Transaction startNestedReadOnlyUserTransaction(\r
+ CompatibilitySpace compatibilitySpace,\r
+ ContextManager contextMgr,\r
+ String transName)\r
+ throws StandardException;\r
+\r
+ /**\r
+ Create a nested user transaction, almost all work within the raw store \r
+ is performed in the context of a transaction.\r
+ <P>\r
+ A nested user transaction is exactly the same as a user transaction,\r
+ except that one can specify a compatibility space to associate with\r
+ the transaction.\r
+ Starting a transaction always performs the following steps.\r
+ <OL>\r
+ <LI>Create an raw store transaction context\r
+ <LI>Create a new idle transaction and then link it to the context.\r
+ </UL>\r
+ Only one user transaction and one nested user transaction can be active\r
+ in a context at any one time.\r
+ After a commit the transaction may be re-used.\r
+ <P>\r
+ <B>Raw Store Transaction Context Behaviour</B>\r
+ <BR>\r
+ The cleanupOnError() method of this context behaves as follows:\r
+ <UL>\r
+ <LI>\r
+ If error is an instance of StandardException that\r
+ has a severity less than ExceptionSeverity.TRANSACTION_SEVERITY then\r
+ no action is taken.\r
+ <LI>\r
+ If error is an instance of StandardException that\r
+ has a severity equal to ExceptionSeverity.TRANSACTION_SEVERITY then\r
+ the context's transaction is aborted, and the transaction returned to\r
+ the idle state. If a user transaction exists on the context stack\r
+ then that transaction is aborted also.\r
+ <LI>\r
+ If error is an instance of StandardException that\r
+ has a severity greater than ExceptionSeverity.TRANSACTION_SEVERITY\r
+ then the context's transaction is aborted, the transaction closed, and\r
+ the context is popped off the stack.\r
+ <LI>\r
+ If error is not an instance of StandardException then the context's\r
+ transaction is aborted, the transaction closed, and the\r
+ context is popped off the stack.\r
+ </UL>\r
+\r
+ @param contextMgr is the context manager to use. An exception will be\r
+ thrown if context is not the current context.\r
+ @param transName is the name of the transaction. This name will be \r
+ displayed by the transactiontable VTI.\r
+\r
+ @exception StandardException Standard Derby error policy\r
+\r
+ @see Transaction\r
+ @see org.apache.derby.iapi.services.context.Context\r
+ @see StandardException\r
+ */\r
+\r
+ public Transaction startNestedUpdateUserTransaction(\r
+ ContextManager contextMgr,\r
+ String transName)\r
+ throws StandardException;\r
+\r
+\r
+ /**\r
+ @see org.apache.derby.iapi.store.access.AccessFactory#getTransactionInfo\r
+ */\r
+ public TransactionInfo[] getTransactionInfo();\r
+\r
+ /**\r
+ * Freeze the database temporarily so a backup can be taken.\r
+ * <P>Please see Derby on line documentation on backup and restore.\r
+ *\r
+ * @exception StandardException Thrown on error\r
+ */\r
+ public void freeze() throws StandardException;\r
+\r
+ /**\r
+ * Unfreeze the database after a backup has been taken.\r
+ * <P>Please see Derby on line documentation on backup and restore.\r
+ *\r
+ * @exception StandardException Thrown on error\r
+ */\r
+ public void unfreeze() throws StandardException;\r
+\r
+ /**\r
+ * Backup the database to backupDir. \r
+ * <P>Please see Derby on line documentation on backup and restore.\r
+ *\r
+ * @param backupDir the name of the directory where the backup should be\r
+ * stored.\r
+ * @param wait if <tt>true</tt>, waits for all the backup blocking \r
+ * operations in progress to finish.\r
+ * \r
+ * @exception StandardException Thrown on error\r
+ */\r
+ public void backup(\r
+ String backupDir, \r
+ boolean wait) throws StandardException;\r
+\r
+ \r
+ /**\r
+ * Backup the database to a backup directory and enable the log archive\r
+ * mode that will keep the archived log files required for roll-forward\r
+ * from this version backup.\r
+ *\r
+ * @param backupDir the directory name where the \r
+ * database backup should go. This \r
+ * directory will be created if not it\r
+ * does not exist.\r
+ *\r
+ * @param deleteOnlineArchivedLogFiles If true deletes online archived log\r
+ * files that exist before this backup,\r
+ * delete will occur only after backup\r
+ * is complete.\r
+ *\r
+ * @param wait if <tt>true</tt>, waits for all the backup blocking \r
+ * operations in progress to finish.\r
+ *\r
+ * @exception StandardException Thrown on error\r
+ */\r
+ public void backupAndEnableLogArchiveMode(\r
+ String backupDir, \r
+ boolean deleteOnlineArchivedLogFiles,\r
+ boolean wait) \r
+ throws StandardException;\r
+ \r
+ /**\r
+ * disables the log archival process, i.e No old log files\r
+ * will be kept around for a roll-forward recovery.\r
+ *\r
+ * @param deleteOnlineArchivedLogFiles If true deletes all online archived\r
+ * log files that exist before this \r
+ * call immediately; Only restore that\r
+ * can be performed after disabling \r
+ * log archive mode is version \r
+ * recovery.\r
+ *\r
+ * @exception StandardException Thrown on error\r
+ */\r
+ public void disableLogArchiveMode(boolean deleteOnlineArchivedLogFiles)\r
+ throws StandardException;\r
+\r
+\r
+ /**\r
+ Try to checkpoint the database to minimize recovery time.\r
+ The raw store does not guarentee that a checkpoint will indeed have\r
+ happened by the time this routine returns.\r
+\r
+ @exception StandardException Standard Derby error policy\r
+ */\r
+ public void checkpoint() throws StandardException;\r
+\r
+\r
+ /**\r
+ Idle the raw store as much as possible. \r
+ @exception StandardException Standard Derby error policy\r
+\r
+ */\r
+ public void idle() throws StandardException;\r
+\r
+ /**\r
+ Get a flushed scan.\r
+ @param start The instant for the beginning of the scan.\r
+ @param groupsIWant log record groups the caller wants to scan.\r
+ @exception StandardException StandardDerby error policy\r
+ */\r
+ ScanHandle openFlushedScan(DatabaseInstant start, int groupsIWant) \r
+ throws StandardException;\r
+\r
+ \r
+ /**\r
+ If this raw store has a daemon that services its need, return the\r
+ daemon. If not, return null\r
+ */\r
+ public DaemonService getDaemon();\r
+\r
+\r
+ /*\r
+ * return the transaction factory module \r
+ */\r
+ public String getTransactionFactoryModule();\r
+\r
+ /*\r
+ * return the data factory module \r
+ */\r
+ public String getDataFactoryModule();\r
+\r
+ /*\r
+ * return the Log factory module \r
+ */\r
+ public String getLogFactoryModule();\r
+\r
+ /*\r
+ * Return the module providing XAresource interface to the transaction \r
+ * table. \r
+ *\r
+ * @exception StandardException Standard Derby exception policy.\r
+ */\r
+ public /* XAResourceManager */ Object getXAResourceManager()\r
+ throws StandardException;\r
+\r
+ /*\r
+ * the database creation phase is finished\r
+ * @exception StandardException Standard Derby exception policy.\r
+ */\r
+ public void createFinished() throws StandardException;\r
+\r
+ /**\r
+ * Get JBMS properties relavent to raw store\r
+ *\r
+ * @exception StandardException Standard Derby exception policy.\r
+ */\r
+ public void getRawStoreProperties(PersistentSet tc) \r
+ throws StandardException; \r
+\r
+ /**\r
+ * Backup / restore support\r
+ */\r
+\r
+ /**\r
+ * Freeze the database from altering any persistent storage.\r
+ *\r
+ * @exception StandardException Standard Derby exception policy.\r
+ */\r
+ public void freezePersistentStore() throws StandardException;\r
+\r
+ /**\r
+ * Unfreeze the database, persistent storage can now be altered.\r
+ *\r
+ * @exception StandardException Standard Derby exception policy.\r
+ */\r
+ public void unfreezePersistentStore() throws StandardException;\r
+\r
+ /**\r
+ Encrypt cleartext into ciphertext.\r
+\r
+ @see org.apache.derby.iapi.services.crypto.CipherProvider#encrypt\r
+ @exception StandardException Standard Derby Error Policy\r
+ */\r
+ public int encrypt(byte[] cleartext, int offset, int length, \r
+ byte[] ciphertext, int outputOffset,\r
+ boolean newEngine) \r
+ throws StandardException ;\r
+\r
+ /**\r
+ Decrypt cleartext from ciphertext.\r
+\r
+ @see org.apache.derby.iapi.services.crypto.CipherProvider#decrypt\r
+ @exception StandardException Standard Derby Error Policy\r
+ */\r
+ public int decrypt(byte[] ciphertext, int offset, int length, \r
+ byte[] cleartext, int outputOffset) \r
+ throws StandardException ;\r
+\r
+ /**\r
+ Returns the encryption block size used during creation of the encrypted database\r
+ */\r
+ public int getEncryptionBlockSize();\r
+\r
+ /**\r
+ Returns a secure random number for this raw store - if database is not\r
+ encrypted, returns 0.\r
+ */\r
+ public int random();\r
+\r
+ /**\r
+ Change the boot password. Return the encrypted form of the secret key.\r
+ The new value must be a String of the form: oldBootPassword, newBootPassword\r
+\r
+ @exception StandardException Standard Derby Error Policy\r
+ */\r
+ public Serializable changeBootPassword(Properties properties, Serializable changePassword)\r
+ throws StandardException ;\r
+\r
+ /**\r
+ * Return an id which can be used to create a container.\r
+ * <p>\r
+ * Return an id number with is greater than any existing container\r
+ * in the current database. Caller will use this to allocate future\r
+ * container numbers - most likely caching the value and then incrementing\r
+ * it as it is used.\r
+ * <p>\r
+ *\r
+ * @return The an id which can be used to create a container.\r
+ *\r
+ * @exception StandardException Standard exception policy.\r
+ **/\r
+ long getMaxContainerId()\r
+ throws StandardException;\r
+\r
+\r
+ /**\r
+ Get the Transaction Factory to use with this store.\r
+ */\r
+ public TransactionFactory getXactFactory();\r
+\r
+ /**\r
+ * Check to see if a database has been upgraded to the required\r
+ * level in order to use a store feature.\r
+ *\r
+ * @param requiredMajorVersion required database Engine major version\r
+ * @param requiredMinorVersion required database Engine minor version\r
+ * @param feature Non-null to throw an exception, null to \r
+ * return the state of the version match.\r
+ *\r
+ * @return <code> true </code> if the database has been upgraded to \r
+ * the required level, <code> false </code> otherwise.\r
+ *\r
+ * @exception StandardException \r
+ * if the database is not at the require version \r
+ * when <code>feature</code> feature is \r
+ * not <code> null </code>. \r
+ */\r
+ public boolean checkVersion(\r
+ int requiredMajorVersion, \r
+ int requiredMinorVersion, \r
+ String feature) \r
+ throws StandardException;\r
+}\r
projects / Benchmarks_CSolver.git / blobdiff