org.exist.storage
Class DBBroker

java.lang.Object
  java.util.Observable
      org.exist.storage.DBBroker

Direct Known Subclasses:

NativeBroker

public abstract class DBBroker

extends java.util.Observable

This is the base class for all database backends. All the basic database operations like storing, removing or index access are provided by subclasses of this class.

Author:

Wolfgang Meier

Field Summary

protected boolean	caseSensitive
protected Configuration	config
protected int	docFragmentationLimit
protected java.lang.String	id
protected static Logger	LOG
static int	MATCH_EXACT
static int	MATCH_REGEXP
static int	MATCH_WILDCARDS
static int	NATIVE
static int	NATIVE_CLUSTER
protected BrokerPool	pool
static java.lang.String	ROOT_COLLECTION
static java.lang.String	ROOT_COLLECTION_NAME
protected SymbolTable	symbols
protected java.io.File	symbolsFile
static java.lang.String	SYSTEM_COLLECTION
static java.lang.String	TEMP_COLLECTION
protected User	user
protected XQuery	xqueryService
protected boolean	xupdateConsistencyChecks
protected int	xupdateGrowthFactor

Constructor Summary

DBBroker(BrokerPool pool, Configuration config)

Method Summary

void	backupSymbolsTo(java.io.OutputStream os)
abstract void	checkXMLResourceConsistency(DocumentImpl doc)
abstract void	checkXMLResourceTree(DocumentImpl doc) Perform a consistency check on the specified document.
abstract void	cleanUpTempCollection() Clean up any temporary resources.
abstract void	cleanUpTempResources() Clean up temporary resources.
abstract void	cleanUpTempResources(java.util.List docs) Remove the temporary document fragments specified by a list of names.
void	closeDocument()
boolean	consistencyChecksEnabled()
abstract void	copyCollection(Txn transaction, Collection collection, Collection destination, java.lang.String newName) Copy a collection to the destination collection and rename it.
abstract void	copyXMLResource(Txn transaction, DocumentImpl doc, Collection destination, java.lang.String newName) Copy a resource to the destination collection and rename it.
void	decReferenceCount()
abstract void	defragXMLResource(Txn transaction, DocumentImpl doc) Defragment pages of this document.
void	endElement(StoredNode node, NodePath currentPath, java.lang.String content)
abstract void	endElement(StoredNode node, NodePath currentPath, java.lang.String content, long oldAddress) Update indexes for the given element node.
abstract void	endRemove()
void	flush() Flush all data that has not been written before.
abstract DocumentSet	getAllXMLResources(DocumentSet docs) Adds all the documents in the database to the specified DocumentSet.
abstract int	getBackendType()
abstract byte[]	getBinaryResource(BinaryDocument blob) Retrieve the binary data stored under the resource descriptor BinaryDocument.
BrokerPool	getBrokerPool()
abstract Collection	getCollection(java.lang.String name) Returns the database collection identified by the specified path.
abstract Collection	getCollection(java.lang.String name, long address) Returns the database collection identified by the specified path.
abstract void	getCollectionResources(Collection collection)
Configuration	getConfiguration() Returns the configuration object used to initialize the current database instance.
java.util.Iterator	getDOMIterator(org.w3c.dom.Document doc, long gid) Return a DOMFileIterator starting at the specified node.
java.util.Iterator	getDOMIterator(NodeProxy proxy) Return a DOMFileIterator starting at the specified node.
abstract ElementIndex	getElementIndex()
int	getFragmentationLimit()
java.lang.String	getId()
abstract IndexSpec	getIndexConfiguration()
abstract int	getNextResourceId(Txn transaction, Collection collection) Get a new document id that does not yet exist within the collection.
java.util.Iterator	getNodeIterator(NodeProxy proxy) Return a NodeIterator starting at the specified node.
abstract org.w3c.dom.NodeList	getNodeRange(org.w3c.dom.Document doc, long first, long last) Get a range of nodes with given owner document from the database, starting at first and ending at last.
abstract NodeSet	getNodesEqualTo(NodeSet context, DocumentSet docs, int relation, int truncation, java.lang.String expr, java.text.Collator collator) Find all Nodes whose string value is equal to expr in the document set.
java.lang.String	getNodeValue(NodeProxy proxy, boolean addWhitespace) Get the string value of the specified node.
Collection	getOrCreateCollection(Txn transaction, java.lang.String name) Returns the database collection identified by the specified path.
abstract int	getPageSize()
abstract NativeValueIndexByQName	getQNameValueIndex()
int	getReferenceCount()
abstract void	getResourceMetadata(DocumentImpl doc)
abstract Serializer	getSerializer() Get an instance of the Serializer used for converting nodes back to XML.
SymbolTable	getSymbols()
abstract TextSearchEngine	getTextEngine() Get the TextSearchEngine associated with this broker.
User	getUser() Get the user that is currently using this DBBroker object.
abstract NativeValueIndex	getValueIndex()
abstract org.w3c.dom.Document	getXMLResource(java.lang.String path) Return the document stored at the specified path.
abstract DocumentImpl	getXMLResource(java.lang.String docPath, int lockMode)
abstract DocumentSet	getXMLResourcesByDoctype(java.lang.String doctype, DocumentSet result)
XQuery	getXQueryService() Returns a reference to the global XQuery service.
int	getXUpdateGrowthFactor()
void	incReferenceCount()
void	indexNode(Txn transaction, StoredNode node)
abstract void	indexNode(Txn transaction, StoredNode node, NodePath currentPath)
abstract void	insertNodeAfter(Txn transaction, StoredNode previous, StoredNode node)
boolean	isCaseSensitive() Is string comparison case sensitive?
boolean	isReadOnly() Is the database running read-only? Returns false by default.
protected void	loadSymbols() Read the global symbol table.
abstract void	moveCollection(Txn transaction, Collection collection, Collection destination, java.lang.String newName) Move a collection and all its subcollections to another collection and rename it.
abstract void	moveXMLResource(Txn transaction, DocumentImpl doc, Collection destination, java.lang.String newName) Move a resource to the destination collection and rename it.
abstract Serializer	newSerializer()
abstract org.w3c.dom.Node	objectWith(org.w3c.dom.Document doc, long gid) Get a node with given owner document and id from the database.
abstract org.w3c.dom.Node	objectWith(NodeProxy p)
abstract Collection	openCollection(java.lang.String name, int lockMode) Open a collection for reading or writing.
abstract void	reindexCollection(java.lang.String collectionName) Reindex a collection.
abstract void	reindexXMLResource(Txn transaction, DocumentImpl oldDoc, DocumentImpl doc, StoredNode node)
abstract void	removeAllNodes(Txn transaction, StoredNode node, NodePath currentPath)
abstract void	removeBinaryResource(Txn transaction, BinaryDocument blob) Completely delete this binary document (descriptor and binary data).
abstract boolean	removeCollection(Txn transaction, Collection collection) Remove the collection and all its subcollections from the database.
abstract void	removeNode(Txn transaction, StoredNode node, NodePath currentPath, java.lang.String content)
void	removeXMLResource(Txn transaction, DocumentImpl document) Remove a document from the database.
abstract void	removeXMLResource(Txn transaction, DocumentImpl document, boolean freeDocId)
abstract void	repair()
abstract void	saveCollection(Txn transaction, Collection collection) Saves the specified collection to storage.
protected void	saveSymbols() Save the global symbol table.
void	setId(java.lang.String id)
void	setUser(User user) Set the user that is currently using this DBBroker object.
void	shutdown() Shut down the database instance.
abstract void	storeBinaryResource(Txn transaction, BinaryDocument blob, byte[] data) Stores the given data under the given binary resource descriptor (BinaryDocument).
void	storeNode(Txn transaction, StoredNode node, NodePath currentPath)
abstract void	storeNode(Txn transaction, StoredNode node, NodePath currentPath, boolean index) Store a node into the database.
abstract DocumentImpl	storeTempResource(DocumentImpl doc) Create a temporary document in the temp collection and store the supplied data.
abstract void	storeXMLResource(Txn transaction, DocumentImpl doc) Store a document (descriptor) into the database (all metadata information which is returned by org.exist.dom.DocumentImpl#serialize()).
abstract void	sync(int syncEvent) Sync dom and collection state data (pages) to disk.
java.lang.String	toString()
abstract void	updateNode(Txn transaction, StoredNode node) Update a node's data.

Methods inherited from class java.util.Observable

addObserver, clearChanged, countObservers, deleteObserver, deleteObservers, hasChanged, notifyObservers, notifyObservers, setChanged

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

MATCH_EXACT

public static final int MATCH_EXACT

See Also:

Constant Field Values

MATCH_REGEXP

public static final int MATCH_REGEXP

See Also:

Constant Field Values

MATCH_WILDCARDS

public static final int MATCH_WILDCARDS

See Also:

Constant Field Values

NATIVE

public static final int NATIVE

See Also:

Constant Field Values

NATIVE_CLUSTER

public static final int NATIVE_CLUSTER

See Also:

Constant Field Values

ROOT_COLLECTION_NAME

public static final java.lang.String ROOT_COLLECTION_NAME

See Also:

Constant Field Values

ROOT_COLLECTION

public static final java.lang.String ROOT_COLLECTION

See Also:

Constant Field Values

SYSTEM_COLLECTION

public static final java.lang.String SYSTEM_COLLECTION

See Also:

Constant Field Values

TEMP_COLLECTION

public static final java.lang.String TEMP_COLLECTION

See Also:

Constant Field Values

LOG

protected static final Logger LOG

caseSensitive

protected boolean caseSensitive

config

protected Configuration config

pool

protected BrokerPool pool

symbolsFile

protected java.io.File symbolsFile

symbols

protected SymbolTable symbols

user

protected User user

xqueryService

protected XQuery xqueryService

xupdateGrowthFactor

protected int xupdateGrowthFactor

docFragmentationLimit

protected int docFragmentationLimit

xupdateConsistencyChecks

protected boolean xupdateConsistencyChecks

id

protected java.lang.String id

Constructor Detail

DBBroker

public DBBroker(BrokerPool pool,
                Configuration config)
         throws EXistException

Method Detail

saveSymbols

protected void saveSymbols()
                    throws EXistException

Save the global symbol table. The global symbol table stores QNames and namespace/prefix mappings.

Throws:

EXistException

loadSymbols

protected void loadSymbols()
                    throws EXistException

Read the global symbol table. The global symbol table stores QNames and namespace/prefix mappings.

Throws:

EXistException

backupSymbolsTo

public void backupSymbolsTo(java.io.OutputStream os)
                     throws java.io.IOException

Throws:

java.io.IOException

getSymbols

public SymbolTable getSymbols()

setUser

public void setUser(User user)

Set the user that is currently using this DBBroker object.

Parameters:

user -

getUser

public User getUser()

Get the user that is currently using this DBBroker object.

Returns:

getXQueryService

public XQuery getXQueryService()

Returns a reference to the global XQuery service.

Returns:

getElementIndex

public abstract ElementIndex getElementIndex()

flush

public void flush()

Flush all data that has not been written before.

getAllXMLResources

public abstract DocumentSet getAllXMLResources(DocumentSet docs)

Adds all the documents in the database to the specified DocumentSet.

Parameters:

docs - a (possibly empty) document set to which the found documents are added.

getCollection

public abstract Collection getCollection(java.lang.String name)

Returns the database collection identified by the specified path. The path should be absolute, e.g. /db/shakespeare.

Returns:

collection or null if no collection matches the path

getCollection

public abstract Collection getCollection(java.lang.String name,
                                         long address)

Returns the database collection identified by the specified path. The storage address is used to locate the collection without looking up the path in the btree.

Returns:

openCollection

public abstract Collection openCollection(java.lang.String name,
                                          int lockMode)

Open a collection for reading or writing. The collection is identified by its absolute path, e.g. /db/shakespeare. It will be loaded and locked according to the lockMode argument. The caller should take care to release the collection lock properly.

Parameters:

name - the collection path

lockMode - one of the modes specified in class Lock

Returns:

collection or null if no collection matches the path

getOrCreateCollection

public Collection getOrCreateCollection(Txn transaction,
                                        java.lang.String name)
                                 throws PermissionDeniedException

Returns the database collection identified by the specified path. If the collection does not yet exist, it is created - including all ancestors. The path should be absolute, e.g. /db/shakespeare.

Returns:

collection or null if no collection matches the path

Throws:

PermissionDeniedException

getConfiguration

public Configuration getConfiguration()

Returns the configuration object used to initialize the current database instance.

getDOMIterator

public java.util.Iterator getDOMIterator(org.w3c.dom.Document doc,
                                         long gid)

Return a DOMFileIterator starting at the specified node.

getDOMIterator

public java.util.Iterator getDOMIterator(NodeProxy proxy)

Return a DOMFileIterator starting at the specified node.

getNodeIterator

public java.util.Iterator getNodeIterator(NodeProxy proxy)

Return a NodeIterator starting at the specified node.

Parameters:

proxy -

Returns:

getXMLResource

public abstract org.w3c.dom.Document getXMLResource(java.lang.String path)
                                             throws PermissionDeniedException

Return the document stored at the specified path. The path should be absolute, e.g. /db/shakespeare/plays/hamlet.xml.

Returns:

the document or null if no document could be found at the specified location.

Throws:

PermissionDeniedException

getXMLResource

public abstract DocumentImpl getXMLResource(java.lang.String docPath,
                                            int lockMode)
                                     throws PermissionDeniedException

Throws:

PermissionDeniedException

getNextResourceId

public abstract int getNextResourceId(Txn transaction,
                                      Collection collection)

Get a new document id that does not yet exist within the collection.

getNodeValue

public java.lang.String getNodeValue(NodeProxy proxy,
                                     boolean addWhitespace)

Get the string value of the specified node. If addWhitespace is set to true, an extra space character will be added between adjacent elements in mixed content nodes.

getNodesEqualTo

public abstract NodeSet getNodesEqualTo(NodeSet context,
                                        DocumentSet docs,
                                        int relation,
                                        int truncation,
                                        java.lang.String expr,
                                        java.text.Collator collator)

Find all Nodes whose string value is equal to expr in the document set.

Parameters:

context - the set of nodes to process

docs - the current set of documents

relation - less-than, equal etc. One of the constants specified in Constants

expr - the string value to search for

getNodeRange

public abstract org.w3c.dom.NodeList getNodeRange(org.w3c.dom.Document doc,
                                                  long first,
                                                  long last)

Get a range of nodes with given owner document from the database, starting at first and ending at last.

Parameters:

doc - the document the nodes belong to

first - unique id of the first node to retrieve

last - unique id of the last node to retrieve

getSerializer

public abstract Serializer getSerializer()

Get an instance of the Serializer used for converting nodes back to XML. Subclasses of DBBroker may have specialized subclasses of Serializer to convert a node into an XML-string

getTextEngine

public abstract TextSearchEngine getTextEngine()

Get the TextSearchEngine associated with this broker. Every subclass of DBBroker will have it's own implementation of TextSearchEngine.

getValueIndex

public abstract NativeValueIndex getValueIndex()

getQNameValueIndex

public abstract NativeValueIndexByQName getQNameValueIndex()

isCaseSensitive

public boolean isCaseSensitive()

Is string comparison case sensitive?

newSerializer

public abstract Serializer newSerializer()

objectWith

public abstract org.w3c.dom.Node objectWith(org.w3c.dom.Document doc,
                                            long gid)

Get a node with given owner document and id from the database.

Parameters:

doc - the document the node belongs to

gid - the node's unique identifier

objectWith

public abstract org.w3c.dom.Node objectWith(NodeProxy p)

removeCollection

public abstract boolean removeCollection(Txn transaction,
                                         Collection collection)
                                  throws PermissionDeniedException

Remove the collection and all its subcollections from the database.

Throws:

PermissionDeniedException

removeXMLResource

public void removeXMLResource(Txn transaction,
                              DocumentImpl document)
                       throws PermissionDeniedException

Remove a document from the database.

Throws:

PermissionDeniedException

removeXMLResource

public abstract void removeXMLResource(Txn transaction,
                                       DocumentImpl document,
                                       boolean freeDocId)
                                throws PermissionDeniedException

Throws:

PermissionDeniedException

reindexCollection

public abstract void reindexCollection(java.lang.String collectionName)
                                throws PermissionDeniedException

Reindex a collection.

Parameters:

collectionName -

Throws:

PermissionDeniedException

repair

public abstract void repair()
                     throws PermissionDeniedException

Throws:

PermissionDeniedException

saveCollection

public abstract void saveCollection(Txn transaction,
                                    Collection collection)
                             throws PermissionDeniedException

Saves the specified collection to storage. Collections are usually cached in memory. If a collection is modified, this method needs to be called to make the changes persistent. Note: appending a new document to a collection does not require a save. Instead, #addDocument(Collection, DocumentImpl) is called.

Parameters:

collection - to store

Throws:

PermissionDeniedException

closeDocument

public void closeDocument()

shutdown

public void shutdown()

Shut down the database instance. All open files, jdbc connections etc. should be closed.

storeNode

public abstract void storeNode(Txn transaction,
                               StoredNode node,
                               NodePath currentPath,
                               boolean index)

Store a node into the database. This method is called by the parser to write a node to the storage backend.

Parameters:

node - the node to be stored

currentPath - path expression which points to this node's element-parent or to itself if it is an element (currently used by the Broker to determine if a node's content should be fulltext-indexed).

storeNode

public void storeNode(Txn transaction,
                      StoredNode node,
                      NodePath currentPath)

endElement

public void endElement(StoredNode node,
                       NodePath currentPath,
                       java.lang.String content)

endElement

public abstract void endElement(StoredNode node,
                                NodePath currentPath,
                                java.lang.String content,
                                long oldAddress)

Update indexes for the given element node. This method is called when the indexer encounters a closing element tag. It updates any range indexes defined on the element value and adds the element id to the structural index.

Parameters:

node - the current element node

currentPath - node path leading to the element

content - contains the string value of the element. Needed if a range index is defined on it.

oldAddress - when copying a node, contains the storage address of the old node.

storeXMLResource

public abstract void storeXMLResource(Txn transaction,
                                      DocumentImpl doc)

Store a document (descriptor) into the database (all metadata information which is returned by org.exist.dom.DocumentImpl#serialize()).

Parameters:

doc - the document's metadata to store.

storeBinaryResource

public abstract void storeBinaryResource(Txn transaction,
                                         BinaryDocument blob,
                                         byte[] data)

Stores the given data under the given binary resource descriptor (BinaryDocument).

Parameters:

blob - the binary document descriptor

data - the document binary data

getCollectionResources

public abstract void getCollectionResources(Collection collection)

getBinaryResource

public abstract byte[] getBinaryResource(BinaryDocument blob)

Retrieve the binary data stored under the resource descriptor BinaryDocument.

Parameters:

blob - the binary document descriptor

Returns:

the document binary data

getResourceMetadata

public abstract void getResourceMetadata(DocumentImpl doc)

removeBinaryResource

public abstract void removeBinaryResource(Txn transaction,
                                          BinaryDocument blob)
                                   throws PermissionDeniedException

Completely delete this binary document (descriptor and binary data).

Parameters:

blob - the binary document descriptor

Throws:

PermissionDeniedException - if you don't have the right to do this

moveCollection

public abstract void moveCollection(Txn transaction,
                                    Collection collection,
                                    Collection destination,
                                    java.lang.String newName)
                             throws PermissionDeniedException,
                                    LockException

Move a collection and all its subcollections to another collection and rename it. Moving a collection just modifies the collection path and all resource paths. The data itself remains in place.

Parameters:

collection - the collection to move

destination - the destination collection

newName - the new name the collection should have in the destination collection

Throws:

PermissionDeniedException

LockException

moveXMLResource

public abstract void moveXMLResource(Txn transaction,
                                     DocumentImpl doc,
                                     Collection destination,
                                     java.lang.String newName)
                              throws PermissionDeniedException,
                                     LockException

Move a resource to the destination collection and rename it.

Parameters:

doc - the resource to move

destination - the destination collection

Throws:

PermissionDeniedException

LockException

copyCollection

public abstract void copyCollection(Txn transaction,
                                    Collection collection,
                                    Collection destination,
                                    java.lang.String newName)
                             throws PermissionDeniedException,
                                    LockException

Copy a collection to the destination collection and rename it.

Parameters:

destination - the destination collection

Throws:

PermissionDeniedException

LockException

copyXMLResource

public abstract void copyXMLResource(Txn transaction,
                                     DocumentImpl doc,
                                     Collection destination,
                                     java.lang.String newName)
                              throws PermissionDeniedException,
                                     LockException

Copy a resource to the destination collection and rename it.

Parameters:

doc - the resource to copy

destination - the destination collection

newName - the new name the resource should have in the destination collection

Throws:

PermissionDeniedException

LockException

defragXMLResource

public abstract void defragXMLResource(Txn transaction,
                                       DocumentImpl doc)

Defragment pages of this document. This will minimize the number of split pages.

Parameters:

doc - to defrag

checkXMLResourceTree

public abstract void checkXMLResourceTree(DocumentImpl doc)

Perform a consistency check on the specified document. This checks if the DOM tree is consistent.

Parameters:

doc -

checkXMLResourceConsistency

public abstract void checkXMLResourceConsistency(DocumentImpl doc)
                                          throws EXistException

Throws:

EXistException

sync

public abstract void sync(int syncEvent)

Sync dom and collection state data (pages) to disk. In case of org.exist.storage.sync.Sync.MAJOR_SYNC, sync all states (dom, collection, text and element) to disk.

Parameters:

syncEvent - Sync.MAJOR_SYNC or Sync.MINOR_SYNC

updateNode

public abstract void updateNode(Txn transaction,
                                StoredNode node)

Update a node's data. To keep nodes in a correct sequential order, it is sometimes necessary to update a previous written node. Warning: don't use it for other purposes.

Parameters:

node - Description of the Parameter

isReadOnly

public boolean isReadOnly()

Is the database running read-only? Returns false by default. Storage backends should override this if they support read-only mode.

Returns:

boolean

getBrokerPool

public BrokerPool getBrokerPool()

insertNodeAfter

public abstract void insertNodeAfter(Txn transaction,
                                     StoredNode previous,
                                     StoredNode node)

reindexXMLResource

public abstract void reindexXMLResource(Txn transaction,
                                        DocumentImpl oldDoc,
                                        DocumentImpl doc,
                                        StoredNode node)

indexNode

public void indexNode(Txn transaction,
                      StoredNode node)

indexNode

public abstract void indexNode(Txn transaction,
                               StoredNode node,
                               NodePath currentPath)

removeNode

public abstract void removeNode(Txn transaction,
                                StoredNode node,
                                NodePath currentPath,
                                java.lang.String content)

removeAllNodes

public abstract void removeAllNodes(Txn transaction,
                                    StoredNode node,
                                    NodePath currentPath)

endRemove

public abstract void endRemove()

storeTempResource

public abstract DocumentImpl storeTempResource(DocumentImpl doc)
                                        throws EXistException,
                                               PermissionDeniedException,
                                               LockException

Create a temporary document in the temp collection and store the supplied data.

Returns:

Throws:

EXistException

PermissionDeniedException

LockException

cleanUpTempCollection

public abstract void cleanUpTempCollection()

Clean up any temporary resources.

cleanUpTempResources

public abstract void cleanUpTempResources()

Clean up temporary resources. Called by the sync daemon.

cleanUpTempResources

public abstract void cleanUpTempResources(java.util.List docs)

Remove the temporary document fragments specified by a list of names.

Parameters:

docs -

getXMLResourcesByDoctype

public abstract DocumentSet getXMLResourcesByDoctype(java.lang.String doctype,
                                                     DocumentSet result)

getReferenceCount

public int getReferenceCount()

incReferenceCount

public void incReferenceCount()

decReferenceCount

public void decReferenceCount()

getXUpdateGrowthFactor

public int getXUpdateGrowthFactor()

getFragmentationLimit

public int getFragmentationLimit()

consistencyChecksEnabled

public boolean consistencyChecksEnabled()

getPageSize

public abstract int getPageSize()

getIndexConfiguration

public abstract IndexSpec getIndexConfiguration()

setId

public void setId(java.lang.String id)

getId

public java.lang.String getId()

toString

public java.lang.String toString()

getBackendType

public abstract int getBackendType()