org.exist.storage.dom
Class DOMFile

java.lang.Object
  extended byorg.exist.storage.btree.Paged
      extended byorg.exist.storage.btree.BTree
          extended byorg.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

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.