XMLKVDatabase (JSimpleDB Simple Key/Value Store Classes 2.3.1 API)

java.lang.Object
- org.jsimpledb.kv.simple.SimpleKVDatabase
- - org.jsimpledb.kv.simple.XMLKVDatabase

All Implemented Interfaces:

Serializable, KVDatabase
```
public class XMLKVDatabase
extends SimpleKVDatabase
```
Simple persistent KVDatabase backed by an XML file stored in a StreamRepository. The data is kept in memory, and the XML file is rewritten in its entirety after each successful commit. In normal usage, the XML file is stored in a regular File using a FileStreamRepository, which guarantees (via the use of AtomicUpdateFileOutputStream) that a partially written XML file can never exist.
If a FileNotFoundException is caught when trying to read the XML file, we assume that the underlying file has not yet been created and the database will initially be empty. Alternately, you can configure a file containing default initial content via setInitialContentFile(), or override getInitialContent() to create the initial content more dynamically.
When a FileStreamRepository is used, instances support "out-of-band" updates of the XML file. In that case, each time a transaction is accessed the modification timestamp of the XML file is examined. If the XML file has been updated by some external process since the time the transaction was created, the database will be reloaded from the XML file and the transaction will fail with a RetryTransactionException.
Note that two different processes modifying the XML file at the same time is not without race conditions: e.g., it's possible for an external process to update the XML file just as a transaction associated with this instance is being committed and written to the file, which will result in overwriting the external process' changes.
Key watches are supported.
Instances are serializable unless a non-serializable StreamRepository is provided to the constructor.

See Also:
XMLSerializer, AtomicUpdateFileOutputStream, org.jsimpledb.spring.SpringXMLKVDatabase, Serialized Form

Field Summary
- Fields inherited from class org.jsimpledb.kv.simple.SimpleKVDatabase
  DEFAULT_HOLD_TIMEOUT, DEFAULT_WAIT_TIMEOUT, kv, log

Constructor Summary

Constructors
Constructor and Description
`XMLKVDatabase(File file)` Constructor.
`XMLKVDatabase(File file, long waitTimeout, long holdTimeout)` Constructor.
`XMLKVDatabase(StreamRepository repository)` Constructor.
`XMLKVDatabase(StreamRepository repository, long waitTimeout, long holdTimeout)` Constructor.

Method Summary

Methods
Modifier and Type	Method and Description
`boolean`	`checkForOutOfBandUpdate()` Check the XML file's timestamp and reload it if it has been modified since the most recent read or write by this instance.
`protected void`	`checkState(SimpleKVTransaction tx)` Verify that the given transaction is still usable.
`XMLKVTransaction`	`createTransaction()`
`int`	`getGeneration()` Get the generation number associated with the XML file.
`protected InputStream`	`getInitialContent()` Get the initial content for an uninitialized database.
`protected void`	`postCommit(SimpleKVTransaction tx, boolean successful)` Invoked during transaction commit just after writing changes to the underlying `KVStore`.
`protected void`	`readXML()`
`void`	`reload()` Forcibly reload this database by re-reading the XML file.
`void`	`setInitialContentFile(File initialContentFile)` Configure the `File` containing default initial content for an uninitialized database.
`void`	`start()`
`protected void`	`writeXML()`

Methods inherited from class org.jsimpledb.kv.simple.SimpleKVDatabase
createTransaction, getHoldTimeout, getWaitTimeout, preCommit, setHoldTimeout, setWaitTimeout, stop

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - XMLKVDatabase
```
public XMLKVDatabase(File file)
```
    Constructor.
    Uses a FileStreamRepository backed by the specified file, with timeouts set to SimpleKVDatabase.DEFAULT_WAIT_TIMEOUT and SimpleKVDatabase.DEFAULT_HOLD_TIMEOUT.
    
    Parameters:
    file - persistent XML file
    
    Throws:
    
    IllegalArgumentException - if file is null
  - XMLKVDatabase
```
public XMLKVDatabase(File file,
             long waitTimeout,
             long holdTimeout)
```
    Constructor.
    Uses a FileStreamRepository backed by the specified file with configurable lock timeouts.
    
    Parameters:
    file - persistent XML file
    waitTimeout - how long a thread will wait for a lock before throwing RetryTransactionException in milliseconds, or zero for unlimited
    holdTimeout - how long a thread may hold a contestested lock before throwing RetryTransactionException in milliseconds, or zero for unlimited
    
    Throws:
    
    IllegalArgumentException - if waitTimeout or holdTimeout is negative
    
    IllegalArgumentException - if file is null
  - XMLKVDatabase
```
public XMLKVDatabase(StreamRepository repository)
```
    Constructor.
    Allows storage in any user-supplied StreamRepository, with timeouts set to SimpleKVDatabase.DEFAULT_WAIT_TIMEOUT and SimpleKVDatabase.DEFAULT_HOLD_TIMEOUT.
    
    Parameters:
    repository - XML file storage
    
    Throws:
    
    IllegalArgumentException - if repository is null
  - XMLKVDatabase
```
public XMLKVDatabase(StreamRepository repository,
             long waitTimeout,
             long holdTimeout)
```
    Constructor.
    Allows storage in any user-supplied StreamRepository with configurable lock timeouts.
    
    Parameters:
    repository - XML file storage
    waitTimeout - how long a thread will wait for a lock before throwing RetryTransactionException in milliseconds, or zero for unlimited
    holdTimeout - how long a thread may hold a contestested lock before throwing RetryTransactionException in milliseconds, or zero for unlimited
    
    Throws:
    
    IllegalArgumentException - if waitTimeout or holdTimeout is negative
    
    IllegalArgumentException - if repository is null
- Method Detail
  - getInitialContent
```
protected InputStream getInitialContent()
                                 throws IOException
```
    Get the initial content for an uninitialized database. This method is invoked when, on the first load, the backing XML file is not found. It should return a stream that reads initial content for the database, if any, otherwise null.
    The implementation in XMLKVDatabase opens and returns the File configured by setInitialContentFile(), if any, otherwise null.
    
    Returns:
    default initial XML database content, or null for none
    
    Throws:
    
    IOException - if an error occurs accessing the initial content file
  - setInitialContentFile
```
public void setInitialContentFile(File initialContentFile)
```
    Configure the File containing default initial content for an uninitialized database. This method is invoked by getInitialContent() when, on the first load, the backing XML file is not found.
    
    Parameters:
    initialContentFile - file containing default initial XML database content, or null for none
  - start
```
public void start()
```
    Specified by:
    
    start in interface KVDatabase
    
    Overrides:
    
    start in class SimpleKVDatabase
  - createTransaction
```
public XMLKVTransaction createTransaction()
```
    Specified by:
    
    createTransaction in interface KVDatabase
    
    Overrides:
    
    createTransaction in class SimpleKVDatabase
  - reload
```
public void reload()
```
    Forcibly reload this database by re-reading the XML file.
    Any transactions that are in-progress when this method is called immediately become unusable.
  - getGeneration
```
public int getGeneration()
```
    Get the generation number associated with the XML file. The generation number is incremented every time the database is wholesale updated by reading the file into memory, e.g., by invoking reload().
    
    Returns:
    XML file generation number
    See Also:
    XMLKVTransaction.getGeneration()
  - checkForOutOfBandUpdate
```
public boolean checkForOutOfBandUpdate()
```
    Check the XML file's timestamp and reload it if it has been modified since the most recent read or write by this instance.
    
    Returns:
    true if file was updated and re-read, otherwise false
  - checkState
```
protected void checkState(SimpleKVTransaction tx)
```
    Description copied from class: SimpleKVDatabase
    
    Verify that the given transaction is still usable.
    This method is invoked at the start of the KVStore data access and commit() methods of the SimpleKVTransaction associated with this instance. This allows for any checks which depend on a consistent view of the transaction and database together. This instance's lock will be held when this method is invoked. Note: transaction state is also protected by this instance's lock.
    The implementation in SimpleKVDatabase does nothing.
    
    Overrides:
    
    checkState in class SimpleKVDatabase
    
    Parameters:
    tx - the transaction being accessed
  - postCommit
```
protected void postCommit(SimpleKVTransaction tx,
              boolean successful)
```
    Description copied from class: SimpleKVDatabase
    
    Invoked during transaction commit just after writing changes to the underlying KVStore.
    SimpleKVDatabase guarantees this method and preCommit() will be invoked in matching pairs, and that this instance will be locked when these methods are invoked.
    This method is invoked even if the underlying KVStore throws an exception while changes were being written to it. In that case, successful will be false.
    The implementation in SimpleKVDatabase does nothing.
    
    Overrides:
    
    postCommit in class SimpleKVDatabase
    
    Parameters:
    tx - the transaction that was committed
    successful - true if all changes were written back successfully, false if the underlying KVStore threw an exception during commit update
  - readXML
```
protected void readXML()
```
  - writeXML
```
protected void writeXML()
```

Class XMLKVDatabase

Field Summary

Fields inherited from class org.jsimpledb.kv.simple.SimpleKVDatabase

Constructor Summary

Method Summary

Methods inherited from class org.jsimpledb.kv.simple.SimpleKVDatabase

Methods inherited from class java.lang.Object

Constructor Detail

XMLKVDatabase

XMLKVDatabase

XMLKVDatabase

XMLKVDatabase

Method Detail

getInitialContent

setInitialContentFile

start

createTransaction

reload

getGeneration

checkForOutOfBandUpdate

checkState

postCommit

readXML

writeXML