public Interface RawStoreFactory

Default value for CONTAINER_CACHE_SIZE_PARAMETER (100).

Maximum container cache size we will accept (MAXINT).

Minimum container cache size accepted (2).

Property name for the number of open files to maintain associated with the page cache. Internally this is referred to as the "ContainerCache". Each object in this cache maps to a java level "open" file on a file in the database directory. Although actual implementation depends on JVM implementation, this usually maps to underlying open file resources in the underlying operating system. Setting this number too high may result in I/O failures reported by Derby, which are the result of hitting some user and/or OS limit on the number of open files allowed. These I/O errors may happen during read, write and/or open operations. Sometimes these limits can be avoided simply by executing an OS specific command to raise the maximum open files allowed by whatever mechanism is used to control resources allowed to be consumed by the JVM. Derby may also open other files separate from this cache, so exausting the open file resource may cause other operations than I/O to data pages to fail. A partial list of these operations includes: recovery logging, error logging, external sorting, and LOB disk overflow. The default maximum size of this cache is 100 open files. The minimum size of this cache is 2 open files, attempting to set this cache to a smaller size or a negative number will result in a size 2 cache. Setting the cache size to a number bigger than an INT, or any sort of illegal format number will result in a cache size of 100 open files. Equal to 'derby.storage.fileCacheSize'

Property name for container which attempts to be created with an initial size of this many pages. Defaults to 1 page.
All containers are guarenteed to be created with at least 1 page, if this property is set, it will attempt to allocate CONTAINER_INITIAL_PAGES, but with no guarentee. CONTAIENR_INITIAL_PAGES legally ranges from 1 to MAX_CONTAINER_INITIAL_PAGES. Values < 1 will be set to 1 and values > MAX_CONTAINER_INITIAL_PAGES will be set to MAX_CONTAINER_INITIAL_PAGES This property should only be set in the PROPERTIES list in a CREATE TABLE or CREATE INDEX statement. The global setting of this property has no effect.

A File used to save the old copy of the verify key (Attribute.CRYPTO_EXTERNAL_KEY_VERIFY_FILE) file during re-encryption of the database.

This variable is used to store the encryption scheme to allow for any future changes in encryption schemes of data This property has been introduced in version 10 Value starts at 1

Tracks the status of any database-wide cryptographic operations.

The relevant operations are encryption, re-encryption and decryption. THe property is required to be able to bring the database back to state it was in before the cryptographic operation started in case the transformation of the database is aborted.

default encryption block size In old existing databases (ie 5.1.x), the default encryption block size used is 8. Do not change this value unless you account for downgrade issues

Derby 10 Store Major version

Derby Store Minor Version (1)

Derby Store Minor Version (10)

Derby Store Minor Version (2)

Derby Store Minor Version (3)

Derby Store Minor Version (4)

If dataEncryption is true, store the encrypted key in services.properties file. It is really the encrypted key, but the property key is called the encryptedBootPassword.

encryption alignment requirement.

encryption block size used during creation of encrypted database This property is not set by the user; it is set by the engine when RawStore boots up during creation of an encrypted database

for debugging, keep all transaction logs intact.

Store the encryption scheme used for logging This will allow for any future changes in encryption schemes of logs This variable has been introduced in version 10 and value starts at 1.

Maximum number of initial pages when a container is created

Default value for MINIMUM_RECORD_SIZE_PARAMETER for heap tables that allow overflow. By setting minimumRecordSize to 12 bytes, we guarantee there is enough space to update the a head row even if there is not enough space on the page. The 12 bytes of user data along with the existing space in the record header will guarantee there is room to write an overflow row header which will use the same initial portion of the record header and at most 12 additional bytes for an overflow pointer (page + id). Note that this is the "user" portion of the record. The record also will contain space for the "non-user" portion which includes the offset table and the record header.

Minimum value for MINIMUM_RECORD_SIZE_PARAMETER (1).

Property name for the default minimum record size to be used in the storage area. Minimum record size is the minimum number of bytes that a record will reserve on disk.

module name

When the datbase is getting re-encrypted old encrypted key is stored in the service.properties until re-encyrption successfully completes or rolled back. It is really the old encryptedkey, but the property key is called the OldEncryptedBootPassword.

Default value for PAGE_CACHE_SIZE_PARAMETER (1000).

Maximum page cache size we will accept (MAXINT).

Minimum page cache size we will accept (40).

Property name for the page cache size to be used in the storage area. Equal to 'derby.storage.pageCacheSize'

Property name for percentage of space to leave free on page for updates.

Property name for container which reuses recordId when a page is reused. Defaults to false, which means recordId is never reused. This property should NOT be set by the end user, only Access should set it for special conglomerates which does not count on permanant unique recordIds for all records.

Default value for PAGE_SIZE_PARAMETER (4096).

Minimum page size we will accept (1024).

The following is a to enable patch for databases with recovery errors during redo of InitPage. If this property is set and the page on the disk is corrupted and is getting exceptions like invalid page format ids, we cook up the page during the recovery time. We have seen this kind of problem with 1.5.1 databases from customer Tridium ( Bug no: 3813). This patch needs to be kept unless we find the problem is during recovery process. If we discover this problem is actaully happening at the recovery then this patch should be backed out.

Property name for the number of pages we try to pre-allocate in one /** synchronous I/O

Default value for STREAM_FILE_BUFFER_SIZE_PARAMETER (16384).

Maximum stream file buffer size we will accept (MAXINT).

Minimum stream file buffer size we will accept (1024).

Property name for buffer size to be used in the stream file container. Equal to 'derby.storage.streamFileBufferSize'

Backup the database to backupDir.

Please see Derby on line documentation on backup and restore.

Parameters

backupDir:String

the name of the directory where the backup should be stored.

wait:boolean

if true, waits for all the backup blocking operations in progress to finish.

Exceptions

StandardException:

Thrown on error

Backup the database to a backup directory and enable the log archive mode that will keep the archived log files required for roll-forward from this version backup.

Parameters

backupDir:String

the directory name where the database backup should go. This directory will be created if not it does not exist.

deleteOnlineArchivedLogFiles:boolean

If true deletes online archived log files that exist before this backup, delete will occur only after backup is complete.

wait:boolean

if true, waits for all the backup blocking operations in progress to finish.

Exceptions

StandardException:

Thrown on error

Change the boot password. Return the encrypted form of the secret key. The new value must be a String of the form: oldBootPassword, newBootPassword

Exceptions

StandardException:

Standard Derby Error Policy

Checkpoint the database. The raw store will wait for any current checkpoints to complete. It will start a new checkpoint and not return until that checkpoint completes.

Exceptions

StandardException:

Standard Derby error policy

Check to see if a database has been upgraded to the required level in order to use a store feature.

Parameters

requiredMajorVersion:int

required database Engine major version

requiredMinorVersion:int

required database Engine minor version

feature:String

Non-null to throw an exception, null to return the state of the version match.

Returns:boolean

true if the database has been upgraded to the required level, false otherwise.

Exceptions

StandardException:

if the database is not at the require version when feature feature is not null .

Use the available storage factory handle to create a readme file in "seg0" directory warning users to not edit/delete any files in the directory to avoid database corruption.

Decrypt cleartext from ciphertext.

Exceptions

StandardException:

Standard Derby Error Policy

See Also

org.apache.derby.iapi.services.crypto.CipherProvider#decrypt

disables the log archival process, i.e No old log files will be kept around for a roll-forward recovery.

Parameters

deleteOnlineArchivedLogFiles:boolean

If true deletes all online archived log files that exist before this call immediately; Only restore that can be performed after disabling log archive mode is version recovery.

Exceptions

StandardException:

Thrown on error

Encrypt cleartext into ciphertext.

Exceptions

StandardException:

Standard Derby Error Policy

See Also

org.apache.derby.iapi.services.crypto.CipherProvider#encrypt

Start failover for this database.

Parameters

dbname:String

the replication database that is being failed over.

Exceptions

StandardException:

Standard Derby exception policy, 1) If the failover succeeds, an exception is thrown to indicate that the master database was shutdown after a successful failover 2) If a failure occurs during network communication with slave.

Find a user transaction in the context manager, which must be the current context manager. If a user transaction does not already exist, then create one @see #startTransaction

Parameters

contextMgr:ContextManager

the context manager to use. An exception will be thrown if context is not the current context.

transName:String

If a new transaction is started, it will be given this name. The name is displayed in the transactiontable VTI.

Exceptions

StandardException:

Standard Derby error policy

See Also

startTransaction

Freeze the database temporarily so a backup can be taken.

Please see Derby on line documentation on backup and restore.

Exceptions

StandardException:

Thrown on error

Freeze the database from altering any persistent storage.

Exceptions

StandardException:

Standard Derby exception policy.

If this raw store has a daemon that services its need, return the daemon. If not, return null

Returns the encryption block size used during creation of the encrypted database

Get the LockFactory to use with this store.

Return an id which can be used to create a container.

Return an id number with is greater than any existing container in the current database. Caller will use this to allocate future container numbers - most likely caching the value and then incrementing it as it is used.

Returns:long

The an id which can be used to create a container.

Exceptions

StandardException:

Standard exception policy.

Get JBMS properties relevant to raw store

Exceptions

StandardException:

Standard Derby exception policy.

See Also

org.apache.derby.iapi.store.access.AccessFactory#getTransactionInfo

Get the Transaction Factory to use with this store.

Idle the raw store as much as possible.

Exceptions

StandardException:

Standard Derby error policy

Is the store read-only.

Get a flushed scan.

Parameters

start:DatabaseInstant

The instant for the beginning of the scan.

groupsIWant:int

log record groups the caller wants to scan.

Exceptions

StandardException:

StandardDerby error policy

Returns a secure random number for this raw store - if database is not encrypted, returns 0.

Register a handler class for insert undo events.

Register a class to be called when an undo of an insert is executed. When an undo of an event is executed by the raw store UndoHandler.insertUndoNotify() will be called, allowing upper level callers to execute code as necessary. The initial need is for the access layer to be able to queue post commit reclaim space in the case of inserts which are aborted (including the normal case of inserts failed for duplicate key violations) (see DERBY-4057)

Exceptions

StandardException:

Standard Derby error policy

Create a global user transaction, almost all work within the raw store is performed in the context of a transaction.

The (format_id, global_id, branch_id) triplet is meant to come exactly from a javax.transaction.xa.Xid. We don't use Xid so that the system can be delivered on a non-1.2 vm system and not require the javax classes in the path.

Starting a transaction always performs the following steps.

1. Create an raw store transaction context
2. Create a new idle transaction and then link it to the context.

Raw Store Transaction Context Behaviour
The cleanupOnError() method of this context behaves as follows:

• If error is an instance of StandardException that has a severity less than ExceptionSeverity.TRANSACTION_SEVERITY then no action is taken.
• If error is an instance of StandardException that has a severity equal to ExceptionSeverity.TRANSACTION_SEVERITY then the context's transaction is aborted, and the transaction returned to the idle state.
• If error is an instance of StandardException that has a severity greater than ExceptionSeverity.TRANSACTION_SEVERITY then the context's transaction is aborted, the transaction closed, and the context is popped off the stack.
• If error is not an instance of StandardException then the context's transaction is aborted, the transaction closed, and the context is popped off the stack.

Parameters

contextMgr:ContextManager

is the context manager to use. An exception will be thrown if context is not the current context.

format_id:int

the format id part of the Xid - ie. Xid.getFormatId().

global_id:byte[]

the global transaction identifier part of XID - ie. Xid.getGlobalTransactionId().

local_id:byte[]

The branch qualifier of the Xid - ie. Xid.getBranchQaulifier()

Exceptions

StandardException:

Standard Derby error policy

See Also

Transaction, org.apache.derby.iapi.services.context.Context, StandardException

Create an internal transaction.

Starting an internal transaction always performs the following steps.

1. Create an raw store internal transaction context
2. Create a new idle internal transaction and then link it to the context.

AN internal transaction is identical to a user transaction with the exception that

• Logical operations are not supported
• Savepoints are not supported
• Containers are not closed when commit() is called.
• Pages are not unlatched (since containers are not closed) when commit() is called.
• During recovery time internal transactions are rolled back before user transactions.

Raw Store Internal Transaction Context Behaviour
The cleanupOnError() method of this context behaves as follows:

• If error is an instance of StandardException that has a severity less than ExceptionSeverity.TRANSACTION_SEVERITY then the internal transaction is aborted, the internal transaction is closed, the context is popped off the stack, and an exception of severity Transaction exception is re-thrown.
• If error is an instance of StandardException that has a severity greater than or equal to ExceptionSeverity.TRANSACTION_SEVERITY then the context's internal transaction is aborted, the internal transaction is closed and the context is popped off the stack.
• If error is not an instance of StandardException then the context's internal transaction is aborted, the internal transaction is closed and the context is popped off the stack.

Exceptions

StandardException:

Standard Derby error policy

See Also

Transaction, org.apache.derby.iapi.services.context.Context, StandardException

Create a nested user transaction, almost all work within the raw store is performed in the context of a transaction.

A nested user transaction is exactly the same as a user transaction, except that one can specify a compatibility space to associate with the transaction. Starting a transaction always performs the following steps.

1. Create an raw store transaction context
2. Create a new idle transaction and then link it to the context.

Raw Store Transaction Context Behaviour
The cleanupOnError() method of this context behaves as follows:

• If error is an instance of StandardException that has a severity less than ExceptionSeverity.TRANSACTION_SEVERITY then no action is taken.
• If error is an instance of StandardException that has a severity equal to ExceptionSeverity.TRANSACTION_SEVERITY then the context's transaction is aborted, and the transaction returned to the idle state. If a user transaction exists on the context stack then that transaction is aborted also.
• If error is an instance of StandardException that has a severity greater than ExceptionSeverity.TRANSACTION_SEVERITY then the context's transaction is aborted, the transaction closed, and the context is popped off the stack.
• If error is not an instance of StandardException then the context's transaction is aborted, the transaction closed, and the context is popped off the stack.

Parameters

parentTransaction:Transaction

parent transaction

compatibilitySpace:CompatibilitySpace

compatibility space to use for locks.

contextMgr:ContextManager

is the context manager to use. An exception will be thrown if context is not the current context.

transName:String

is the name of the transaction. This name will be displayed by the transactiontable VTI.

Exceptions

StandardException:

Standard Derby error policy

See Also

Transaction, org.apache.derby.iapi.services.context.Context, StandardException

Create a nested user transaction, almost all work within the raw store is performed in the context of a transaction.

A nested user transaction is exactly the same as a user transaction, except that one can specify a compatibility space to associate with the transaction. Starting a transaction always performs the following steps.

1. Create an raw store transaction context.
2. Create a new idle transaction and then link it to the context.

Raw Store Transaction Context Behaviour
The cleanupOnError() method of this context behaves as follows:

• If error is an instance of StandardException that has a severity less than ExceptionSeverity.TRANSACTION_SEVERITY then no action is taken.
• If error is an instance of StandardException that has a severity equal to ExceptionSeverity.TRANSACTION_SEVERITY then the context's transaction is aborted, and the transaction returned to the idle state. If a user transaction exists on the context stack then that transaction is aborted also.
• If error is an instance of StandardException that has a severity greater than ExceptionSeverity.TRANSACTION_SEVERITY then the context's transaction is aborted, the transaction closed, and the context is popped off the stack.
• If error is not an instance of StandardException then the context's transaction is aborted, the transaction closed, and the context is popped off the stack.

Parameters

parentTransaction:Transaction

parent transaction

contextMgr:ContextManager

is the context manager to use. An exception will be thrown if context is not the current context.

transName:String

is the name of the transaction. This name will be displayed by the transactiontable VTI.

flush_log_on_xact_end:boolean

By default should the transaction commit and abort be synced to the log. Normal usage should pick true, unless there is specific performance need and usage works correctly if a commit can be lost on system crash.

Exceptions

StandardException:

Standard Derby error policy

See Also

Transaction, org.apache.derby.iapi.services.context.Context, StandardException

Start the replication master role for this database

Parameters

dbmaster:String

The master database that is being replicated.

host:String

The hostname for the slave

port:int

The port the slave is listening on

replicationMode:String

The type of replication contract. Currently only asynchronous replication is supported, but 1-safe/2-safe/very-safe modes may be added later.

Exceptions

StandardException:

Standard Derby exception policy, thrown on error.

Create a user transaction, almost all work within the raw store is performed in the context of a transaction.

Starting a transaction always performs the following steps.

1. Create an raw store transaction context
2. Create a new idle transaction and then link it to the context.

Raw Store Transaction Context Behaviour
The cleanupOnError() method of this context behaves as follows:

• If error is an instance of StandardException that has a severity less than ExceptionSeverity.TRANSACTION_SEVERITY then no action is taken.
• If error is an instance of StandardException that has a severity equal to ExceptionSeverity.TRANSACTION_SEVERITY then the context's transaction is aborted, and the transaction returned to the idle state.
• If error is an instance of StandardException that has a severity greater than ExceptionSeverity.TRANSACTION_SEVERITY then the context's transaction is aborted, the transaction closed, and the context is popped off the stack.
• If error is not an instance of StandardException then the context's transaction is aborted, the transaction closed, and the context is popped off the stack.

Parameters

contextMgr:ContextManager

is the context manager to use. An exception will be thrown if context is not the current context.

transName:String

is the name of the transaction. Thsi name will be displayed by the transactiontable VTI.

Exceptions

StandardException:

Standard Derby error policy

See Also

Transaction, org.apache.derby.iapi.services.context.Context, StandardException

Stop the replication master role for this database.

Exceptions

StandardException:

Standard Derby exception policy, thrown on error.

Unfreeze the database after a backup has been taken.

Please see Derby on line documentation on backup and restore.

Exceptions

StandardException:

Thrown on error

Unfreeze the database, persistent storage can now be altered.

Exceptions

StandardException:

Standard Derby exception policy.