|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
public interface Options
Options for the Journal. Options are specified as property values to
the Journal.Journal(Properties) constructor.
Some operating systems, file systems, disk controllers, and disk drives may
re-order writes, processing them in a different order from the sequence in
which they are issued by the application, and may return from
FileChannel.force(boolean) or FileDescriptor.sync() before
the data are on stable media. This can have the consequence that the root
blocks are laid down on the disk before the application data. In this
situation a hard failure during (or after!) the write could result in the
loss of application data since the root blocks representing the atomic commit
point MIGHT be updated before the application data was successfully made
stable on disk. Further, IAtomicStore.commit() MAY return before the
data are stable on disk.
Depending on your needs there are several steps which you can take to
increase data security, including backups, media replication, etc. In terms
of the Journal itself, you can use FORCE_WRITES to request
synchronous writes or disable the write cache on your platform. While
FORCE_WRITES is trivially specified as a configuration option,
please note that the behavior of FORCE_WRITES can vary from platform
to platform and that disabling the write cache on your platform may give you
a greater assurance that writes are neither being reordered nor returning
before the data are on stable storage. Also note that some high end disk
systems have battery backup for the on-disk write cache, in which case you
may choose to leave the write cache on the disk enabled.
| Field Summary | |
|---|---|
static String |
ALTERNATE_ROOT_BLOCK
WARNING - The use of this option is dangerous. This option MAY be used if you have a commit point whose root block is valid but where the data associated with that root block is invalid. |
static String |
BUFFER_MODE
The name of the property whose value controls the nature of the backing store (default DEFAULT_BUFFER_MODE). |
static String |
CREATE
An optional boolean property (default is "true"). |
static String |
CREATE_TEMP_FILE
This boolean option causes a new file to be created using the File.createTempFile(String, String, File) temporary file
mechanism. |
static String |
CREATE_TIME
An optional property allowed iff a new journal is being created whose value is the timestamp to be written in the IRootBlockView.getCreateTime() field of the root block. |
static String |
DEFAULT_BUFFER_MODE
The default for the BUFFER_MODE. |
static String |
DEFAULT_CREATE
The default for the CREATE option. |
static String |
DEFAULT_CREATE_TEMP_FILE
The default for the CREATE_TEMP_FILE option. |
static String |
DEFAULT_DELETE_ON_CLOSE
The default for the DELETE_ON_CLOSE option. |
static String |
DEFAULT_DELETE_ON_EXIT
The default for the DELETE_ON_EXIT option. |
static String |
DEFAULT_DOUBLE_SYNC
The default for the DOUBLE_SYNC option (application data is NOT
forced to disk before we write the root blocks). |
static String |
DEFAULT_FILE_LOCK_ENABLED
|
static String |
DEFAULT_FORCE_ON_COMMIT
The default for the FORCE_ON_COMMIT option (file data and
metadata are forced). |
static String |
DEFAULT_FORCE_WRITES
The default for the FORCE_WRITES option (writes are not forced). |
static String |
DEFAULT_HISTORICAL_INDEX_CACHE_CAPACITY
The default for the HISTORICAL_INDEX_CACHE_CAPACITY option. |
static String |
DEFAULT_HISTORICAL_INDEX_CACHE_TIMEOUT
|
static String |
DEFAULT_INITIAL_EXTENT
The default initial extent for a new journal. |
static String |
DEFAULT_LIVE_INDEX_CACHE_CAPACITY
The default for the LIVE_INDEX_CACHE_CAPACITY option. |
static String |
DEFAULT_LIVE_INDEX_CACHE_TIMEOUT
|
static String |
DEFAULT_MAXIMUM_EXTENT
The default maximum extent for a new journal before a commit triggers an overflow event (200M). |
static String |
DEFAULT_MINIMUM_EXTENSION
The default minimum extension of the journal when the user extent runs out of room. |
static String |
DEFAULT_READ_CACHE_CAPACITY
The default for #READ_CACHE_CAPACITY. |
static String |
DEFAULT_READ_CACHE_MAX_RECORD_SIZE
The default for #READ_CACHE_MAX_RECORD_SIZE. |
static String |
DEFAULT_READ_ONLY
The default for the READ_ONLY option. |
static String |
DEFAULT_USE_DIRECT_BUFFERS
The default for USE_DIRECT_BUFFERS. |
static String |
DEFAULT_VALIDATE_CHECKSUM
|
static String |
DEFAULT_WRITE_CACHE_BUFFER_COUNT
The #of WriteCache buffers used by the WriteCacheService. |
static String |
DEFAULT_WRITE_CACHE_ENABLED
The WriteCacheService is enabled by default. |
static String |
DELETE_ON_CLOSE
This boolean option causes the journal file to be deleted when the journal is closed (default false). |
static String |
DELETE_ON_EXIT
This boolean option causes the journal file to be deleted when the VM exits (default false). |
static String |
DOUBLE_SYNC
This boolean option may be used to request that application data are forced to stable storage before we update the root blocks (default "false"). |
static String |
FILE
The name of the file. |
static String |
FILE_LOCK_ENABLED
Deprecated. FileLockUtility is going away since advisory locks
are not automatically removed if an application dies. |
static String |
FORCE_ON_COMMIT
A trinary property {no, force, forceMetadata} that determines whether the journal will be forced to stable storage on a commit (default ). |
static String |
FORCE_WRITES
A trinary property {no, force, forceMetadata} that determines whether the journal will be opened in a mode that writes through synchronously to stable storage (default ). |
static String |
HISTORICAL_INDEX_CACHE_CAPACITY
The capacity of the LRU cache for canonicalizing mapping maintained by the AbstractJournal for index Checkpoints. |
static String |
HISTORICAL_INDEX_CACHE_TIMEOUT
The timeout in milliseconds for stale entries in the historical index cache -or- ZERO (0) to disable the timeout (default "60000"). |
static String |
IGNORE_BAD_ROOT_BLOCK
WARNING - The use of this option is dangerous. This option MAY be used to permit the database to be opened if one of the root blocks is bad. |
static String |
INITIAL_EXTENT
The initial extent of the journal (bytes). |
static String |
JNL
The recommended extension for journal files. |
static String |
LIVE_INDEX_CACHE_CAPACITY
The capacity of the LRU cache for the "live" Name2Addr object
(default "60"). |
static String |
LIVE_INDEX_CACHE_TIMEOUT
The timeout in milliseconds for stale entries in the live index cache -or- ZERO (0) to disable the timeout (default "60000"). |
static String |
MAXIMUM_EXTENT
The maximum extent of the journal (bytes). |
static long |
MEM_MAX_EXTENT
Maxmimum extent for stores backed by a byte[] in Java. |
static String |
MINIMUM_EXTENSION
The minimum #of bytes that the journal will be extended when it runs out of room in the user extent. |
static long |
minimumInitialExtent
|
static long |
minimumMinimumExtension
|
static String |
OFFSET_BITS
The #of bits in a 64-bit long integer identifier that are used to encode the byte offset of a record in the store as an unsigned integer. |
static long |
OTHER_MAX_EXTENT
A default used for BufferModes which do not have a fixed maximum
extent. |
static String |
READ_ONLY
When true, the journal must pre-exist and will be
read-only (optional, default is "false"). |
static long |
RW_MAX_EXTENT
Maximum extent for the RW style stores ( MemStore and
RWStore). |
static String |
SEG
The recommended extension for IndexSegment files. |
static String |
TMP_DIR
The property whose value is the name of the directory in which temporary files will be created. |
static String |
UPDATE_ICU_VERSION
WARNING - The use of this option is dangerous. This option may be used to update the ICUVersionRecord associated with
the journal. |
static String |
USE_DIRECT_BUFFERS
A boolean property whose value controls whether a direct (native) or heap-based ByteBuffer will be allocated by the selected
BufferMode. |
static String |
VALIDATE_CHECKSUM
An optional boolean property (default "true"). |
static String |
WRITE_CACHE_BUFFER_COUNT
Option may be used to override the #of WriteCache buffers which
will be used with a WriteCacheService. |
static String |
WRITE_CACHE_ENABLED
Option may be used to disable the WriteCacheService on the
WORMStrategy. |
| Field Detail |
|---|
static final String FILE
CREATE is true, then a new journal will be created.
The filename extension ".jnl" is recommended.
static final String BUFFER_MODE
DEFAULT_BUFFER_MODE).
BufferMode,
DEFAULT_BUFFER_MODEstatic final String HISTORICAL_INDEX_CACHE_CAPACITY
AbstractJournal for index Checkpoints. The capacity
of this cache indirectly controls how many historical
indices the journal will hold open. The main reason for keeping a
historical index open is to reuse its buffers, including its node and
leaf cache, if another request arrives "soon" for that historical commit
point of the index.
The effect of this parameter is indirect owning to the semantics of weak references and the control of the JVM over when they are cleared. Once an index becomes weakly reachable, the JVM will eventually GC the index object, thereby effectively closing it (or at least releasing all resources associated with that index). Since indices which are strongly reachable are never "closed" this provides our guarentee that indices are never closed if they are in use.
DEFAULT_HISTORICAL_INDEX_CACHE_CAPACITY,
#LIVE_INDEX_CACHE_CAPACITY, which governs the retention of clean
"live" indices.,
AbstractJournal.getIndex(long)static final String HISTORICAL_INDEX_CACHE_TIMEOUT
HardReferenceQueue will be cleared. Note that the entry will
remain in the historical index cache regardless as long as it is strongly
reachable.
AbstractJournal.getIndex(long)static final String DEFAULT_HISTORICAL_INDEX_CACHE_TIMEOUT
static final String LIVE_INDEX_CACHE_CAPACITY
Name2Addr object
(default "60"). A special
Name2Addr instance is maintained for the "live" index objects,
gives the most recent Checkpoint address from which the "live"
version of the index may be loaded, and provides a canonicalizing cache
for the "live" index objects by name.
The capacity of this cache for this special Name2Addr instance
indirectly controls how many clean "live" indices the
journal will hold open. A "live" index is only clean when it has just
been loaded from the store or when it has just been committed, so this
really effects how long an index which has been committed will be keep
open. The main reason for keeping the index open after a commit is to
reuse its buffers, including its node and leaf cache, if another request
arrives "soon" for an operation on that index.
The effect of this parameter is indirect owning to the semantics of weak references and the control of the JVM over when they are cleared. Once an index becomes weakly reachable, the JVM will eventually GC the index object, thereby effectively closing it (or at least releasing all resources associated with that index). Dirty indices will be held open until the next commit/abort regardless since a hard reference is placed on the commit list.
DEFAULT_LIVE_INDEX_CACHE_CAPACITY,
HISTORICAL_INDEX_CACHE_CAPACITY,
Name2Addrstatic final String LIVE_INDEX_CACHE_TIMEOUT
HardReferenceQueue
will be cleared. Note that the entry will remain in the live index cache
regardless as long as it is strongly reachable.
Name2Addrstatic final String DEFAULT_LIVE_INDEX_CACHE_TIMEOUT
static final String USE_DIRECT_BUFFERS
ByteBuffer will be allocated by the selected
BufferMode. Note that this only applies to fully buffered modes,
e.g., BufferMode.Transient or BufferMode.Direct. This
parameter has no effect for the memory-mapped or disk-only buffer modes.
static final String WRITE_CACHE_ENABLED
WriteCacheService on the
WORMStrategy. Generally, this option is only used by some unit
tests to avoid direct buffer allocation using the
DirectBufferPool.
DEFAULT_WRITE_CACHE_ENABLEDstatic final String WRITE_CACHE_BUFFER_COUNT
WriteCache buffers which
will be used with a WriteCacheService.
DEFAULT_WRITE_CACHE_BUFFER_COUNTstatic final String INITIAL_EXTENT
Note: When using a partitioned index strategy the initial extent and the maximum extent should be the same so that the cost of extending the journal may be avoided as much as possible.
DEFAULT_INITIAL_EXTENTstatic final long minimumInitialExtent
static final String MAXIMUM_EXTENT
IResourceManager.overflow() once it approaches this limit.
DEFAULT_MAXIMUM_EXTENTstatic final String MINIMUM_EXTENSION
DEFAULT_MINIMUM_EXTENSIONstatic final long minimumMinimumExtension
static final String OFFSET_BITS
WormAddressManager.SCALE_UP_OFFSET_BITS for a
Journal and WormAddressManager.SCALE_OUT_OFFSET_BITS for
a StoreManager.ManagedJournal.
WormAddressManager.SCALE_UP_OFFSET_BITS,
WormAddressManager.SCALE_OUT_OFFSET_BITSstatic final String VALIDATE_CHECKSUM
true, the checksum stored in the root blocks of an
existing store will be validated when the store file is opened. This
property may be set to false if you are engaged in a desperate attempt to
use a bad root block or to patch a bad root block using a hex editor.
DEFAULT_VALIDATE_CHECKSUMstatic final String ALTERNATE_ROOT_BLOCK
READ_ONLY so that you do not
accidentally trigger a commit and thereby make the data
associated with the other root block unreachable. You may of course
deliberately allow a commit as an attempt to restore the database to
service accepting that you have rolled back the database by one commit
point in doing so.
static final String IGNORE_BAD_ROOT_BLOCK
READ_ONLY so that you do not accidentally trigger a
commit. You may of course deliberately allow a commit as an attempt to
restore the database to service accepting that you may have rolled back
the database by one commit point in doing so.
static final String UPDATE_ICU_VERSION
ICUVersionRecord associated with
the journal. ICU provides a Unicode sort key generation service for
bigdata. Unicode sort keys are used in many indices, including the
Name2Addr index. If the new ICU version produces Unicode sort
keys which are not binary compatible with the Journal, then your data may
become inaccessible since you will be unable to probe the
Name2Addr index to locate named indices. The same problem can
manifest with application indices which use Unicode sort keys.
static final String CREATE
true and the named file is not found, a new journal will be
created. If the file exists but is empty, then a new journal will be
initialized on that file (this makes it possible to use the temporary
file mechanism to atomically create the file on which the journal will be
initialized).
static final String CREATE_TIME
IRootBlockView.getCreateTime() field of the root block. This is
used by the ResourceManager to place consistent createTime
timestamps on its managed journal resources.
static final String READ_ONLY
true, the journal must pre-exist and will be
read-only (optional, default is "false").
static final String FORCE_WRITES
#FORCE_ON_COMMIT, which controls the stability of the data on disk.,
DEFAULT_FORCE_WRITES,
ForceEnumstatic final String FORCE_ON_COMMIT
DOUBLE_SYNC,
IRawStore.force(boolean),
FileChannel.force(boolean),
ForceEnumstatic final String DOUBLE_SYNC
FileChannel.force(boolean) before root blocks are updated as part
of the atomic commit protocol in an attempt to guard against operating
systems and/or file systems which may otherwise reorders writes with the
consequence that the root blocks are laid down on the disk before the
application data. In this situation a hard failure during the root block
write could result in the loss of application data since the updated root
blocks represent the atomic commit point but not all application data was
successfully made stable on disk.
However, note that there are often multiple cache layers in use by the operating system, the disk controller, and the disk and it can be difficult to have an assurance that the various cache layers are all correctly configured so as to obey a "sync" command. Durability, therefore, is best achieved through a mixture of methods, which can include battery powered hardware write cache and/or replication.
DEFAULT_DOUBLE_SYNCstatic final String CREATE_TEMP_FILE
File.createTempFile(String, String, File) temporary file
mechanism. However, if all you need is an atomic create of a new
filename, you can just create the temporary file and then pass it in
using FILE since an empty file will be initialized as a new
journal.
Note: If DELETE_ON_EXIT is also specified, then the temporary
file will be marked for deletion when the JVM
exits.
Note: This option is often used when preparing a journal for a unit test.
Note: The default temporary directory is used unless it is overridden by
the TMP_DIR option.
Note: In order to re-open a journal that was created with this option you
MUST (a) set this option to false and (b) set FILE
to the value returned by AbstractJournal.getFile().
static final String DELETE_ON_CLOSE
static final String DELETE_ON_EXIT
static final String TMP_DIR
java.io.tmpdir. There
are several kinds of temporary files that can be created, including
temporary journals, intermediate files from an index merge process, etc.
static final String FILE_LOCK_ENABLED
FileLockUtility is going away since advisory locks
are not automatically removed if an application dies.true (default "true") a
FileLock will be sought for the journal by default. When
false only an advisory lock will be sought. Note that
FileLock is never used for memory-mapped (causes problems) or
read-only files (does not work) and MAY fail on NFS mounts. If
FileLock fails then we always back down to an advisory lock.
FileLockUtility.openFile(File, String, boolean)static final String DEFAULT_FILE_LOCK_ENABLED
static final String DEFAULT_BUFFER_MODE
BUFFER_MODE.
static final String DEFAULT_USE_DIRECT_BUFFERS
USE_DIRECT_BUFFERS.
static final String DEFAULT_WRITE_CACHE_ENABLED
WriteCacheService is enabled by default.
WRITE_CACHE_ENABLED,
Constant Field Valuesstatic final String DEFAULT_WRITE_CACHE_BUFFER_COUNT
WriteCache buffers used by the WriteCacheService.
WRITE_CACHE_BUFFER_COUNT,
Constant Field Valuesstatic final String DEFAULT_READ_CACHE_CAPACITY
#READ_CACHE_CAPACITY.
static final String DEFAULT_READ_CACHE_MAX_RECORD_SIZE
#READ_CACHE_MAX_RECORD_SIZE.
static final String DEFAULT_INITIAL_EXTENT
INITIAL_EXTENT,
Constant Field Valuesstatic final String DEFAULT_MAXIMUM_EXTENT
MAXIMUM_EXTENT,
Constant Field Valuesstatic final String DEFAULT_MINIMUM_EXTENSION
MINIMUM_EXTENSION,
Constant Field Valuesstatic final String DEFAULT_VALIDATE_CHECKSUM
static final String DEFAULT_CREATE
CREATE option.
static final String DEFAULT_READ_ONLY
READ_ONLY option.
static final String DEFAULT_FORCE_WRITES
FORCE_WRITES option (writes are not forced).
static final String DEFAULT_FORCE_ON_COMMIT
FORCE_ON_COMMIT option (file data and
metadata are forced).
static final String DEFAULT_DOUBLE_SYNC
DOUBLE_SYNC option (application data is NOT
forced to disk before we write the root blocks).
static final String DEFAULT_DELETE_ON_CLOSE
DELETE_ON_CLOSE option.
static final String DEFAULT_DELETE_ON_EXIT
DELETE_ON_EXIT option.
static final String DEFAULT_CREATE_TEMP_FILE
CREATE_TEMP_FILE option.
static final String DEFAULT_HISTORICAL_INDEX_CACHE_CAPACITY
HISTORICAL_INDEX_CACHE_CAPACITY option.
static final String DEFAULT_LIVE_INDEX_CACHE_CAPACITY
LIVE_INDEX_CACHE_CAPACITY option.
static final String JNL
static final String SEG
IndexSegment files.
static final long RW_MAX_EXTENT
MemStore and
RWStore).
static final long MEM_MAX_EXTENT
static final long OTHER_MAX_EXTENT
BufferModes which do not have a fixed maximum
extent. For example, the WORM modes depend on the partitioning of the
address bits into bits for the offset and bits for the data length.
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||