org.exist.storage
Class DBBroker

java.lang.Object
  extended byjava.util.Observable
      extended byorg.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
static java.lang.String COLLECTION_CONFIG_FILENAME
           
static java.lang.String CONFIG_COLLECTION
           
 java.util.HashMap customProperties
           
static int MATCH_EXACT
           
static int MATCH_REGEXP
           
static int MATCH_WILDCARDS
           
static int NATIVE
           
static int NATIVE_CLUSTER
           
static java.lang.String PROPERTY_XUPDATE_CONSISTENCY_CHECKS
           
static java.lang.String PROPERTY_XUPDATE_FRAGMENTATION_FACTOR
           
static java.lang.String PROPERTY_XUPDATE_GROWTH_FACTOR
           
static java.lang.String ROOT_COLLECTION
           
static java.lang.String ROOT_COLLECTION_NAME
           
static java.lang.String SYSTEM_COLLECTION
           
static java.lang.String TEMP_COLLECTION
           
 
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()
           
abstract  void copyCollection(Txn transaction, Collection collection, Collection destination, XmldbURI newName)
          Copy a collection to the destination collection and rename it.
abstract  void copyXMLResource(Txn transaction, DocumentImpl doc, Collection destination, XmldbURI 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(XmldbURI uri)
          Returns the database collection identified by the specified path.
abstract  Collection getCollection(XmldbURI uri, 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(StoredNode node)
          Return a DOMFileIterator starting at the specified node.
abstract  ElementIndex getElementIndex()
           
 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(StoredNode node)
          Return a NodeIterator starting at the specified node.
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(StoredNode node, boolean addWhitespace)
          Get the string value of the specified node.
 Collection getOrCreateCollection(Txn transaction, XmldbURI uri)
          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()
           
abstract  NativeValueIndex getValueIndex()
           
abstract  org.w3c.dom.Document getXMLResource(XmldbURI docURI)
          Return the document stored at the specified path.
abstract  DocumentImpl getXMLResource(XmldbURI docURI, int lockMode)
          Return the document stored at the specified path.
abstract  DocumentSet getXMLResourcesByDoctype(java.lang.String doctype, DocumentSet result)
           
 XQuery getXQueryService()
           
 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.
abstract  void moveCollection(Txn transaction, Collection collection, Collection destination, XmldbURI newName)
          Move a collection and all its subcollections to another collection and rename it.
abstract  void moveXMLResource(Txn transaction, DocumentImpl doc, Collection destination, XmldbURI newName)
          Move a resource to the destination collection and rename it.
abstract  Serializer newSerializer()
           
abstract  StoredNode objectWith(org.w3c.dom.Document doc, NodeId nodeId)
          Get a node with given owner document and id from the database.
abstract  StoredNode objectWith(NodeProxy p)
           
abstract  Collection openCollection(XmldbURI uri, int lockMode)
          Open a collection for reading or writing.
abstract  void readBinaryResource(BinaryDocument blob, java.io.OutputStream os)
           
abstract  void reindexCollection(XmldbURI collectionName)
          Reindex a collection.
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.
 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).
abstract  void storeBinaryResource(Txn transaction, BinaryDocument blob, java.io.InputStream is)
          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.
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, countObservers, deleteObserver, deleteObservers, hasChanged, notifyObservers, notifyObservers
 
Methods inherited from class java.lang.Object
equals, 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

CONFIG_COLLECTION

public static final java.lang.String CONFIG_COLLECTION
See Also:
Constant Field Values

COLLECTION_CONFIG_FILENAME

public static final java.lang.String COLLECTION_CONFIG_FILENAME
See Also:
Constant Field Values

PROPERTY_XUPDATE_GROWTH_FACTOR

public static java.lang.String PROPERTY_XUPDATE_GROWTH_FACTOR

PROPERTY_XUPDATE_FRAGMENTATION_FACTOR

public static java.lang.String PROPERTY_XUPDATE_FRAGMENTATION_FACTOR

PROPERTY_XUPDATE_CONSISTENCY_CHECKS

public static java.lang.String PROPERTY_XUPDATE_CONSISTENCY_CHECKS

customProperties

public java.util.HashMap customProperties
Constructor Detail

DBBroker

public DBBroker(BrokerPool pool,
                Configuration config)
         throws EXistException
Method Detail

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()
Returns:
The user that is currently using this DBBroker object

getXQueryService

public XQuery getXQueryService()
Returns:
A reference to the global XQuery service.

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(XmldbURI uri)
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(XmldbURI uri,
                                         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:
Database collection

openCollection

public abstract Collection openCollection(XmldbURI uri,
                                          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:
uri - 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,
                                        XmldbURI uri)
                                 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(StoredNode node)
Return a DOMFileIterator starting at the specified node.


getNodeIterator

public java.util.Iterator getNodeIterator(StoredNode node)
Return a NodeIterator starting at the specified node.

Parameters:
node -
Returns:
NodeIterator of node.

getXMLResource

public abstract org.w3c.dom.Document getXMLResource(XmldbURI docURI)
                                             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(XmldbURI docURI,
                                            int lockMode)
                                     throws PermissionDeniedException
Return the document stored at the specified path. The path should be absolute, e.g. /db/shakespeare/plays/hamlet.xml, with the specified lock.

Returns:
the document or null if no document could be found at the specified location.
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(StoredNode node,
                                     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

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 StoredNode objectWith(org.w3c.dom.Document doc,
                                      NodeId nodeId)
Get a node with given owner document and id from the database.

Parameters:
doc - the document the node belongs to
nodeId - the node's unique identifier

objectWith

public abstract StoredNode 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(XmldbURI collectionName)
                                throws PermissionDeniedException
Reindex a collection.

Parameters:
collectionName -
Throws:
PermissionDeniedException - public abstract void reindexCollection(String 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.

Parameters:
transaction -
collection - 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.

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

storeBinaryResource

public abstract void storeBinaryResource(Txn transaction,
                                         BinaryDocument blob,
                                         java.io.InputStream is)
Stores the given data under the given binary resource descriptor (BinaryDocument).

Parameters:
blob - the binary document descriptor
is - the document binary data as input stream

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

readBinaryResource

public abstract void readBinaryResource(BinaryDocument blob,
                                        java.io.OutputStream os)

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,
                                    XmldbURI 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,
                                     XmldbURI newName)
                              throws PermissionDeniedException,
                                     LockException
Move a resource to the destination collection and rename it.

Parameters:
doc - the resource to move
destination - the destination collection
newName - the new name the resource should have in the destination collection
Throws:
PermissionDeniedException
LockException

copyCollection

public abstract void copyCollection(Txn transaction,
                                    Collection collection,
                                    Collection destination,
                                    XmldbURI newName)
                             throws PermissionDeniedException,
                                    LockException
Copy a collection to the destination collection and rename it.

Parameters:
collection - the resource to move
destination - the destination collection
newName - the new name the resource should have in the destination collection
Throws:
PermissionDeniedException
LockException

copyXMLResource

public abstract void copyXMLResource(Txn transaction,
                                     DocumentImpl doc,
                                     Collection destination,
                                     XmldbURI 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 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)

indexNode

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

indexNode

public void indexNode(Txn transaction,
                      StoredNode node)

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.

Parameters:
doc -
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()

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()


Copyright (C) Wolfgang Meier. All rights reserved.