org.exist.storage
Class DBBroker

java.lang.Object
  extended by java.util.Observable
      extended by org.exist.storage.DBBroker
Direct Known Subclasses:
NativeBroker

public abstract class DBBroker
extends 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 String CONFIGURATION_ELEMENT_NAME
           
static int MATCH_EXACT
           
static int MATCH_REGEXP
           
static int MATCH_WILDCARDS
           
static String PROPERTY_XUPDATE_CONSISTENCY_CHECKS
           
static String PROPERTY_XUPDATE_FRAGMENTATION_FACTOR
           
static String ROOT_COLLECTION
           
static String ROOT_COLLECTION_NAME
           
static String SYSTEM_COLLECTION
           
static String SYSTEM_COLLECTION_NAME
           
static String TEMP_COLLECTION
           
static String TEMP_COLLECTION_NAME
           
static String XUPDATE_CONSISTENCY_CHECKS_ATTRIBUTE
           
static String XUPDATE_FRAGMENTATION_FACTOR_ATTRIBUTE
           
 
Constructor Summary
DBBroker(BrokerPool pool, Configuration config)
           
 
Method Summary
 void addContentLoadingObserver(ContentLoadingObserver observer)
          Observer Design Pattern: add an observer.
abstract  void backupToArchive(RawDataBackup backup)
           
abstract  void checkAvailableMemory()
          Convenience method that allows to check available memory during broker-related processes.
abstract  void checkXMLResourceConsistency(DocumentImpl doc)
           
abstract  void checkXMLResourceTree(DocumentImpl doc)
          Perform a consistency check on the specified document.
abstract  void cleanUpTempResources()
          Clean up temporary resources.
abstract  void cleanUpTempResources(boolean forceRemoval)
          Clean up temporary resources.
 void clearContentLoadingObservers()
          Remove all observers
 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, String content)
           
abstract  void endElement(StoredNode node, NodePath currentPath, String content, boolean remove)
           
abstract  void endRemove(Txn transaction)
           
 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  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  void getCollectionResources(Collection collection)
           
abstract  void getCollectionsFailsafe(BTreeCallback callback)
           
 Configuration getConfiguration()
          Returns the configuration object used to initialize the current database instance.
abstract  ElementIndex getElementIndex()
           
 String getId()
           
abstract  IndexSpec getIndexConfiguration()
           
 IndexController getIndexController()
           
abstract  int getNextResourceId(Txn transaction, Collection collection)
          Get a new document id that does not yet exist within the collection.
 Iterator getNodeIterator(StoredNode node)
          Return a NodeIterator starting at the specified node.
 String getNodeValue(StoredNode node, boolean addWhitespace)
          Get the string value of the specified node.
abstract  Collection getOrCreateCollection(Txn transaction, XmldbURI uri)
          Returns the database collection identified by the specified path.
 int getReferenceCount()
           
abstract  void getResourceMetadata(DocumentImpl doc)
           
abstract  void getResourcesFailsafe(BTreeCallback callback)
           
abstract  Serializer getSerializer()
          Get an instance of the Serializer used for converting nodes back to XML.
abstract  TextSearchEngine getTextEngine()
          Get the TextSearchEngine associated with this broker.
 User getUser()
           
abstract  NativeValueIndex getValueIndex()
           
abstract  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(String doctype, DocumentSet result)
           
abstract  EmbeddedXMLStreamReader getXMLStreamReader(NodeProxy node, boolean reportAttributes)
           
abstract  EmbeddedXMLStreamReader getXMLStreamReader(StoredNode node, boolean reportAttributes)
           
 XQuery getXQueryService()
           
 void incReferenceCount()
           
 void indexNode(Txn transaction, StoredNode node)
           
abstract  void indexNode(Txn transaction, StoredNode node, NodePath currentPath)
           
 void initIndexModules()
           
abstract  void insertNodeAfter(Txn transaction, StoredNode previous, StoredNode node)
           
 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(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, OutputStream os)
           
abstract  void reindexCollection(XmldbURI collectionName)
          Reindex a collection.
abstract  void removeAllNodes(Txn transaction, StoredNode node, NodePath currentPath, StreamListener listener)
           
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.
 void removeContentLoadingObserver(ContentLoadingObserver observer)
          Observer Design Pattern: remove an observer.
abstract  void removeNode(Txn transaction, StoredNode node, NodePath currentPath, 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(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, InputStream is)
          Stores the given data under the given binary resource descriptor (BinaryDocument).
 void storeNode(Txn transaction, StoredNode node, NodePath currentPath, IndexSpec indexSpec)
           
abstract  void storeNode(Txn transaction, StoredNode node, NodePath currentPath, IndexSpec indexSpec, 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.
 String toString()
           
abstract  void updateNode(Txn transaction, StoredNode node, boolean reindex)
          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

ROOT_COLLECTION_NAME

public static final String ROOT_COLLECTION_NAME
See Also:
Constant Field Values

ROOT_COLLECTION

public static final String ROOT_COLLECTION
See Also:
Constant Field Values

SYSTEM_COLLECTION_NAME

public static final String SYSTEM_COLLECTION_NAME
See Also:
Constant Field Values

SYSTEM_COLLECTION

public static final String SYSTEM_COLLECTION
See Also:
Constant Field Values

TEMP_COLLECTION_NAME

public static final String TEMP_COLLECTION_NAME
See Also:
Constant Field Values

TEMP_COLLECTION

public static final String TEMP_COLLECTION
See Also:
Constant Field Values

CONFIGURATION_ELEMENT_NAME

public static final String CONFIGURATION_ELEMENT_NAME
See Also:
Constant Field Values

XUPDATE_FRAGMENTATION_FACTOR_ATTRIBUTE

public static final String XUPDATE_FRAGMENTATION_FACTOR_ATTRIBUTE
See Also:
Constant Field Values

PROPERTY_XUPDATE_FRAGMENTATION_FACTOR

public static final String PROPERTY_XUPDATE_FRAGMENTATION_FACTOR
See Also:
Constant Field Values

XUPDATE_CONSISTENCY_CHECKS_ATTRIBUTE

public static final String XUPDATE_CONSISTENCY_CHECKS_ATTRIBUTE
See Also:
Constant Field Values

PROPERTY_XUPDATE_CONSISTENCY_CHECKS

public static final String PROPERTY_XUPDATE_CONSISTENCY_CHECKS
See Also:
Constant Field Values
Constructor Detail

DBBroker

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

initIndexModules

public void initIndexModules()

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

getIndexController

public IndexController getIndexController()

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.


clearContentLoadingObservers

public void clearContentLoadingObservers()
Remove all observers


addContentLoadingObserver

public void addContentLoadingObserver(ContentLoadingObserver observer)
Observer Design Pattern: add an observer.


removeContentLoadingObserver

public void removeContentLoadingObserver(ContentLoadingObserver observer)
Observer Design Pattern: remove an observer.


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.

getResourcesFailsafe

public abstract void getResourcesFailsafe(BTreeCallback callback)

getCollectionsFailsafe

public abstract void getCollectionsFailsafe(BTreeCallback callback)

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

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 abstract Collection getOrCreateCollection(Txn transaction,
                                                 XmldbURI uri)
                                          throws PermissionDeniedException,
                                                 IOException
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.

Parameters:
transaction - The transaction, which registers the acquired write locks. The locks should be released on commit/abort.
uri - The collection's URI
Returns:
The collection or null if no collection matches the path
Throws:
PermissionDeniedException
IOException

getConfiguration

public Configuration getConfiguration()
Returns the configuration object used to initialize the current database instance.


getNodeIterator

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

Parameters:
node -
Returns:
NodeIterator of node.

getXMLResource

public abstract 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 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.


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

newSerializer

public abstract Serializer newSerializer()

objectWith

public abstract StoredNode objectWith(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,
                                         IOException
Remove the collection and all its subcollections from the database.

Throws:
PermissionDeniedException
IOException

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,
                                    IOException
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
IOException

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,
                               IndexSpec indexSpec,
                               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,
                      IndexSpec indexSpec)

endElement

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

endElement

public abstract void endElement(StoredNode node,
                                NodePath currentPath,
                                String content,
                                boolean remove)

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,
                                         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,
                                        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,
                                    IOException
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
IOException

moveXMLResource

public abstract void moveXMLResource(Txn transaction,
                                     DocumentImpl doc,
                                     Collection destination,
                                     XmldbURI newName)
                              throws PermissionDeniedException,
                                     LockException,
                                     IOException
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
IOException

copyCollection

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

Parameters:
transaction - The transaction, which registers the acquired write locks. The locks should be released on commit/abort.
collection - The origin collection
destination - The destination parent collection
newName - The new name of the collection
Throws:
PermissionDeniedException
LockException
IOException

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,
                                boolean reindex)
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,
                                String content)

removeAllNodes

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

endRemove

public abstract void endRemove(Txn transaction)

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

cleanUpTempResources

public abstract void cleanUpTempResources()
Clean up temporary resources. Called by the sync daemon.


cleanUpTempResources

public abstract void cleanUpTempResources(boolean forceRemoval)
Clean up temporary resources. Called by the sync daemon.

Parameters:
forceRemoval - Should temporary resources be forcefully removed

checkAvailableMemory

public abstract void checkAvailableMemory()
Convenience method that allows to check available memory during broker-related processes. This method should eventually trigger flush() events.


getXMLResourcesByDoctype

public abstract DocumentSet getXMLResourcesByDoctype(String doctype,
                                                     DocumentSet result)

getReferenceCount

public int getReferenceCount()

incReferenceCount

public void incReferenceCount()

decReferenceCount

public void decReferenceCount()

getIndexConfiguration

public abstract IndexSpec getIndexConfiguration()

setId

public void setId(String id)

getId

public String getId()

toString

public String toString()
Overrides:
toString in class Object

getXMLStreamReader

public abstract EmbeddedXMLStreamReader getXMLStreamReader(StoredNode node,
                                                           boolean reportAttributes)
                                                    throws IOException,
                                                           XMLStreamException
Throws:
IOException
XMLStreamException

getXMLStreamReader

public abstract EmbeddedXMLStreamReader getXMLStreamReader(NodeProxy node,
                                                           boolean reportAttributes)
                                                    throws IOException,
                                                           XMLStreamException
Throws:
IOException
XMLStreamException

backupToArchive

public abstract void backupToArchive(RawDataBackup backup)
                              throws IOException
Throws:
IOException


Copyright (C) Wolfgang Meier. All rights reserved.