## org.exist.storage.dom
Class DOMFile

    java.lang.Object
      org.exist.storage.btree.Paged
          org.exist.storage.btree.BTree
              org.exist.storage.dom.DOMFile

All Implemented Interfaces:
  Lockable

public class DOMFile
extends BTree
implements Lockable

This is the main storage for XML nodes. Nodes are stored in document order. Every document gets its own sequence of pages, which is bound to the writing thread to avoid conflicting writes. The page structure is as follows: | page header | (tid1 node-data, tid2 node-data, ..., tidn node-data) | node-data contains the raw binary data of the node. Within a page, a node is identified by a unique id, called tuple id (tid). Every node can thus be located by a virtual address pointer, which consists of the page id and the tid. Both components are encoded in a long value (with additional bits used for optional flags). The address pointer is used to reference nodes from the indexes. It should thus remain unchanged during the life-time of a document. However, XUpdate requests may insert new nodes in the middle of a page. In these cases, the page will be split and the upper portion of the page is copied to a split page. The record in the original page will be replaced by a forward link, pointing to the new location of the node data in the split page. As a consequence, the class has to distinguish three different types of data records: 1) Ordinary record: | tid | length | data | 3) Relocated record: | tid | length | address pointer to original location | data | 2) Forward link: | tid | address pointer | tid and length each use two bytes (short), address pointers 8 bytes (long). The upper two bits of the tid are used to indicate the type of the record (see `ItemId`).

Author:
  Wolfgang Meier <wolfgang@exist-db.org>

Nested Class Summary

Nested classes inherited from class org.exist.storage.btree.Paged
`Paged.FileHeader, Paged.Page, Paged.PageHeader`

Field Summary
`static long` `DATA_SYNC_PERIOD`
`static short` `FILE_FORMAT_VERSION_ID`
`static byte` `LOB`
`static byte` `LOG_ADD_LINK`
`static byte` `LOG_ADD_MOVED_REC`
`static byte` `LOG_ADD_VALUE`
`static byte` `LOG_CREATE_PAGE`
`static byte` `LOG_INSERT_RECORD`
`static byte` `LOG_REMOVE_EMPTY_PAGE`
`static byte` `LOG_REMOVE_OVERFLOW`
`static byte` `LOG_REMOVE_PAGE`
`static byte` `LOG_REMOVE_VALUE`
`static byte` `LOG_SPLIT_PAGE`
`static byte` `LOG_UPDATE_HEADER`
`static byte` `LOG_UPDATE_LINK`
`static byte` `LOG_UPDATE_VALUE`
`static byte` `LOG_WRITE_OVERFLOW`
`static short` `OVERFLOW`
`static byte` `RECORD`

Fields inherited from class org.exist.storage.btree.BTree
`KEY_NOT_FOUND, LOG_CREATE_BNODE, LOG_INSERT_VALUE, LOG_SET_PARENT, LOG_UPDATE_PAGE`

Constructor Summary
`DOMFile(BrokerPool pool, java.io.File file, CacheManager cacheManager)`

Method Summary
`long` `add(Txn transact, byte[] value)` Append a value to the current page.
`long` `addBinary(Txn transaction, DocumentImpl doc, byte[] value)` Store a raw binary resource into the file.
`long` `addBinary(Txn transaction, DocumentImpl doc, java.io.InputStream is)` Store a raw binary resource into the file.
`void` `addToBuffer(org.exist.storage.dom.DOMFile.DOMPage page)`
`boolean` `close()` Close the underlying files.
`void` `closeDocument()`
`boolean` `create()`
`Paged.FileHeader` `createFileHeader()` createFileHeader must be implemented by a Paged implementation in order to create an appropriate subclass instance of a FileHeader.
`Paged.PageHeader` `createPageHeader()` createPageHeader must be implemented by a Paged implementation in order to create an appropriate subclass instance of a PageHeader.
`java.lang.String` `debugPageContents(org.exist.storage.dom.DOMFile.DOMPage page)`
`java.lang.String` `debugPages(DocumentImpl doc, boolean showPageContents)`
`java.util.ArrayList` `findKeys(IndexQuery query)`
`java.util.ArrayList` `findValues(IndexQuery query)` Find matching nodes for the given query.
`boolean` `flush()` Flush all buffers to disk.
`Value` `get(long p)` Retrieve node at virtual address p.
`Value` `get(NodeProxy node)` Retrieve a node described by the given NodeProxy.
`Value` `get(Value key)` Retrieve a node by key
`byte[]` `getBinary(long pageNum)` Return binary data stored with `addBinary(Txn, DocumentImpl, byte[])`.
`BufferStats` `getDataBufferStats()`
`short` `getFileVersion()`
`Lock` `getLock()` Get the active Lock object for this file.
`java.lang.String` `getNodeValue(StoredNode node, boolean addWhitespace)` Retrieve the string value of the specified node.
`long` `insertAfter(Txn transaction, DocumentImpl doc, long address, byte[] value)` Insert a new node after the node located at the specified address.
`long` `insertAfter(Txn transaction, DocumentImpl doc, Value key, byte[] value)` Insert a new node after the specified node.
`boolean` `open()` Open the file.
`void` `printStatistics()`
`long` `put(Txn transaction, Value key, byte[] value)` Put a new key/value pair.
`void` `readBinary(long pageNum, java.io.OutputStream os)`
`void` `remove(Txn transaction, Value key)`
`void` `remove(Txn transaction, Value key, long p)`
`void` `remove(Value key)` Physically remove a node.
`void` `remove(Value key, long p)` Physically remove a node.
`void` `removeAll(Txn transaction, long p)` Remove a sequence of pages, starting with the page denoted by the passed address pointer p.
`void` `removeNode(long p)` Physically remove a node.
`void` `removeNode(Txn transaction, long p)`
`void` `removeOverflowValue(Txn transaction, long pnum)`
`void` `removePage(org.exist.storage.dom.DOMFile.DOMPage page)` Remove the specified page.
`void` `setCurrentDocument(DocumentImpl doc)`
`void` `setOwnerObject(java.lang.Object obj)` The current object owning this file.
`void` `update(Txn transaction, long p, byte[] value)` Update the key/value pair where the value is found at address p.
`boolean` `update(Txn transaction, Value key, byte[] value)` Update the key/value pair.

Methods inherited from class org.exist.storage.btree.BTree
`addValue, addValue, closeAndRemove, createFileHeader, createFileHeader, createFileHeader, dump, findValue, getIndexBufferStats, open, query, query, remove, remove, removeValue, removeValue`

Methods inherited from class org.exist.storage.btree.Paged
`backupToStream, exists, getFile, getFileHeader, getPageSize, hexDump, isOpened, isReadOnly, printFreeSpaceList, setPageSize`

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

Field Detail

### LOG_CREATE_PAGE

    public static final byte LOG_CREATE_PAGE

See Also:
  Constant Field Values

### LOG_ADD_VALUE

    public static final byte LOG_ADD_VALUE

See Also:
  Constant Field Values

### LOG_REMOVE_VALUE

    public static final byte LOG_REMOVE_VALUE

See Also:
  Constant Field Values

### LOG_REMOVE_EMPTY_PAGE

    public static final byte LOG_REMOVE_EMPTY_PAGE

See Also:
  Constant Field Values

### LOG_UPDATE_VALUE

    public static final byte LOG_UPDATE_VALUE

See Also:
  Constant Field Values

### LOG_REMOVE_PAGE

    public static final byte LOG_REMOVE_PAGE

See Also:
  Constant Field Values

### LOG_WRITE_OVERFLOW

    public static final byte LOG_WRITE_OVERFLOW

See Also:
  Constant Field Values

### LOG_REMOVE_OVERFLOW

    public static final byte LOG_REMOVE_OVERFLOW

See Also:
  Constant Field Values

### LOG_INSERT_RECORD

    public static final byte LOG_INSERT_RECORD

See Also:
  Constant Field Values

### LOG_SPLIT_PAGE

    public static final byte LOG_SPLIT_PAGE

See Also:
  Constant Field Values

### LOG_ADD_LINK

    public static final byte LOG_ADD_LINK

See Also:
  Constant Field Values

### LOG_ADD_MOVED_REC

    public static final byte LOG_ADD_MOVED_REC

See Also:
  Constant Field Values

### LOG_UPDATE_HEADER

    public static final byte LOG_UPDATE_HEADER

See Also:
  Constant Field Values

### LOG_UPDATE_LINK

    public static final byte LOG_UPDATE_LINK

See Also:
  Constant Field Values

### FILE_FORMAT_VERSION_ID

    public static final short FILE_FORMAT_VERSION_ID

See Also:
  Constant Field Values

### LOB

    public static final byte LOB

See Also:
  Constant Field Values

### RECORD

    public static final byte RECORD

See Also:
  Constant Field Values

### OVERFLOW

    public static final short OVERFLOW

See Also:
  Constant Field Values

### DATA_SYNC_PERIOD

    public static final long DATA_SYNC_PERIOD

See Also:
  Constant Field Values

Constructor Detail

### DOMFile

    public DOMFile(BrokerPool pool,
                   java.io.File file,
                   CacheManager cacheManager)
            throws DBException

Method Detail

### getFileVersion

    public short getFileVersion()

  Overrides:
    `getFileVersion` in class `Paged`
  Returns:
    file version.

### setCurrentDocument

    public void setCurrentDocument(DocumentImpl doc)

### add

    public long add(Txn transact,
                    byte[] value)
             throws ReadOnlyException

  Append a value to the current page. This method is called when storing a new document. Each writing thread gets its own sequence of pages for writing a document, so all document nodes are stored in sequential order. A new page will be allocated if the current page is full. If the value is larger than the page size, it will be written to an overflow page.

  Parameters:
    `value` - the value to append
  Returns:
    the virtual storage address of the value
  Throws:
    `ReadOnlyException`

### addBinary

    public long addBinary(Txn transaction,
                          DocumentImpl doc,
                          byte[] value)

  Store a raw binary resource into the file. The data will always be written into an overflow page.

  Parameters:
    `value` - Binary resource as byte array

### addBinary

    public long addBinary(Txn transaction,
                          DocumentImpl doc,
                          java.io.InputStream is)

  Store a raw binary resource into the file. The data will always be written into an overflow page.

  Parameters:
    `is` - Binary resource as stream.

### getBinary

    public byte[] getBinary(long pageNum)

  Return binary data stored with `addBinary(Txn, DocumentImpl, byte[])`.

  Parameters:
    `pageNum` -

### readBinary

    public void readBinary(long pageNum,
                           java.io.OutputStream os)

### insertAfter

    public long insertAfter(Txn transaction,
                            DocumentImpl doc,
                            Value key,
                            byte[] value)

  Insert a new node after the specified node.

  Parameters:
    `key` -
    `value` -

### insertAfter

    public long insertAfter(Txn transaction,
                            DocumentImpl doc,
                            long address,
                            byte[] value)

  Insert a new node after the node located at the specified address. If the previous node is in the middle of a page, the page is split. If the node is appended at the end and the page does not have enough room for the node, a new page is added to the page sequence.

  Parameters:
    `doc` - the document to which the new node belongs.
    `address` - the storage address of the node after which the new value should be inserted.
    `value` - the value of the new node.

### debugPageContents

    public java.lang.String debugPageContents(org.exist.storage.dom.DOMFile.DOMPage page)

### close

    public boolean close()
                  throws DBException

  Description copied from class: `Paged`
  Close the underlying files.

  Overrides:
    `close` in class `BTree`
  Throws:
    `DBException`

### create

    public boolean create()
                   throws DBException

  Overrides:
    `create` in class `Paged`
  Throws:
    `DBException`

### createFileHeader

    public Paged.FileHeader createFileHeader()

  Description copied from class: `Paged`
  createFileHeader must be implemented by a Paged implementation in order to create an appropriate subclass instance of a FileHeader.

  Overrides:
    `createFileHeader` in class `BTree`
  See Also:
    `Paged.createFileHeader()`

### createPageHeader

    public Paged.PageHeader createPageHeader()

  Description copied from class: `Paged`
  createPageHeader must be implemented by a Paged implementation in order to create an appropriate subclass instance of a PageHeader.

  Overrides:
    `createPageHeader` in class `BTree`
  See Also:
    `Paged.createPageHeader()`

### findKeys

    public java.util.ArrayList findKeys(IndexQuery query)
                                 throws java.io.IOException,
                                        BTreeException

  Throws:
    `java.io.IOException`
    `BTreeException`

### findValues

    public java.util.ArrayList findValues(IndexQuery query)
                                   throws java.io.IOException,
                                          BTreeException

  Find matching nodes for the given query.

  Parameters:
    `query` - Description of the Parameter
  Returns:
    Description of the Return Value
  Throws:
    `java.io.IOException` - Description of the Exception
    `BTreeException` - Description of the Exception

### flush

    public boolean flush()
                  throws DBException

  Flush all buffers to disk.

  Overrides:
    `flush` in class `BTree`
  Returns:
    Description of the Return Value
  Throws:
    `DBException` - Description of the Exception

### printStatistics

    public void printStatistics()

  Overrides:
    `printStatistics` in class `BTree`

### getDataBufferStats

    public BufferStats getDataBufferStats()

### get

    public Value get(Value key)

  Retrieve a node by key

  Parameters:
    `key` -
  Returns:
    Description of the Return Value

### get

    public Value get(NodeProxy node)

  Retrieve a node described by the given NodeProxy.

  Parameters:
    `node` - Description of the Parameter
  Returns:
    Description of the Return Value

### get

    public Value get(long p)

  Retrieve node at virtual address p.

  Parameters:
    `p` - Description of the Parameter
  Returns:
    Description of the Return Value

### removeOverflowValue

    public void removeOverflowValue(Txn transaction,
                                    long pnum)

### closeDocument

    public void closeDocument()

### open

    public boolean open()
                 throws DBException

  Open the file.

  Returns:
    Description of the Return Value
  Throws:
    `DBException` - Description of the Exception

### put

    public long put(Txn transaction,
                    Value key,
                    byte[] value)
             throws ReadOnlyException

  Put a new key/value pair.

  Parameters:
    `key` - Description of the Parameter
    `value` - Description of the Parameter
  Returns:
    Description of the Return Value
  Throws:
    `ReadOnlyException`

### remove

    public void remove(Value key)

  Physically remove a node. The data of the node will be removed from the page and the occupied space is freed.

### remove

    public void remove(Txn transaction,
                       Value key)

### removeNode

    public void removeNode(long p)

  Physically remove a node. The data of the node will be removed from the page and the occupied space is freed.

  Parameters:
    `p` -

### removeNode

    public void removeNode(Txn transaction,
                           long p)

### remove

    public void remove(Value key,
                       long p)

  Physically remove a node. The data of the node will be removed from the page and the occupied space is freed.

### remove

    public void remove(Txn transaction,
                       Value key,
                       long p)

### removePage

    public void removePage(org.exist.storage.dom.DOMFile.DOMPage page)

  Remove the specified page. The page is added to the list of free pages.

  Parameters:
    `page` -

### removeAll

    public void removeAll(Txn transaction,
                          long p)

  Remove a sequence of pages, starting with the page denoted by the passed address pointer p.

  Parameters:
    `transaction` -
    `p` -

### debugPages

    public java.lang.String debugPages(DocumentImpl doc,
                                       boolean showPageContents)

### getLock

    public final Lock getLock()

  Get the active Lock object for this file.

  Specified by:
    `getLock` in interface `Lockable`
  See Also:
    `Lockable.getLock()`

### setOwnerObject

    public final void setOwnerObject(java.lang.Object obj)

  The current object owning this file.

  Parameters:
    `obj` - The new ownerObject value

### update

    public boolean update(Txn transaction,
                          Value key,
                          byte[] value)
                   throws ReadOnlyException

  Update the key/value pair.

  Parameters:
    `key` - Description of the Parameter
    `value` - Description of the Parameter
  Returns:
    Description of the Return Value
  Throws:
    `ReadOnlyException`

### update

    public void update(Txn transaction,
                       long p,
                       byte[] value)
                throws ReadOnlyException

  Update the key/value pair where the value is found at address p.

  Parameters:
    `transaction` -
    `p` -
    `value` -
  Throws:
    `ReadOnlyException`

### getNodeValue

    public java.lang.String getNodeValue(StoredNode node,
                                         boolean addWhitespace)

  Retrieve the string value of the specified node. This is an optimized low-level method which will directly traverse the stored DOM nodes and collect the string values of the specified root node and all its descendants. By directly scanning the stored node data, we do not need to create a potentially large amount of node objects and thus save memory and time for garbage collection.

  Parameters:
    `node` -
  Returns:
    string value of the specified node

### addToBuffer

    public final void addToBuffer(org.exist.storage.dom.DOMFile.DOMPage page)

Copyright (C) Wolfgang Meier. All rights reserved.