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 other components rely on the methods defined here.

Author:
Wolfgang Meier

Field Summary
protected  boolean caseSensitive
           
protected  Configuration config
           
static int DBM
           
static int MATCH_EXACT
           
static int MATCH_REGEXP
           
static int MATCH_WILDCARDS
           
static int MYSQL
           
static int NATIVE
           
static int ORACLE
           
protected  BrokerPool pool
           
static int POSTGRESQL
           
 
Constructor Summary
DBBroker(BrokerPool pool, Configuration config)
          Constructor for the DBBroker object
 
Method Summary
 void addDocument(Collection collection, DocumentImpl doc)
           
 void closeDocument()
           
 void endRemove()
           
abstract  NodeSet findElementsByTagName(DocumentSet docs, java.lang.String tagName)
          find elements by their tag name.
 void flush()
          flush all data that has not been written before.
 DocumentSet getAllDocuments()
          Gets the allDocuments attribute of the DBBroker object
abstract  DocumentSet getAllDocuments(User user)
          get all the documents in this database repository.
abstract  NodeSet getAttributesByName(DocumentSet docs, java.lang.String name)
          find elements by their tag name.
 BrokerPool getBrokerPool()
           
abstract  Collection getCollection(java.lang.String name)
          Gets the collection attribute of the DBBroker object
 Collection getCollection(java.lang.String name, long address)
           
 Configuration getConfiguration()
          get the configuration.
abstract  int getDatabaseType()
          return the type of database this broker is connected to.
 org.w3c.dom.Document getDocument(java.lang.String fileName)
          Gets the document attribute of the DBBroker object
abstract  org.w3c.dom.Document getDocument(User user, java.lang.String fileName)
          get a document by it's file name.
 DocumentSet getDocumentsByCollection(java.lang.String collection)
          Gets the documentsByCollection attribute of the DBBroker object
abstract  DocumentSet getDocumentsByCollection(User user, java.lang.String collection)
          Gets the documentsByCollection attribute of the DBBroker object
abstract  DocumentSet getDocumentsByCollection(User user, java.lang.String collection, boolean inclusive)
          Gets the documentsByCollection attribute of the DBBroker object
 DocumentSet getDocumentsByDoctype(java.lang.String doctype)
          Gets the documentsByDoctype attribute of the DBBroker object
abstract  DocumentSet getDocumentsByDoctype(User user, java.lang.String doctypeName)
          get all the documents in this database matching the given document-type's name.
 java.util.Iterator getDOMIterator(org.w3c.dom.Document doc, long gid)
          Gets the dOMIterator attribute of the DBBroker object
 java.util.Iterator getDOMIterator(NodeProxy proxy)
          Gets the dOMIterator attribute of the DBBroker object
 java.lang.String getNamespacePrefix(java.lang.String namespace)
          get a common prefix for a namespace URI.
 java.lang.String getNamespaceURI(java.lang.String prefix)
          get the namespace associated with the given prefix.
abstract  int getNextDocId(Collection collection)
          Gets the nextDocId attribute of the DBBroker object
 java.util.Iterator getNodeIterator(NodeProxy proxy)
           
abstract  NodeSet[] getNodesContaining(DocumentSet doc, java.lang.String[] expr)
          get all the nodes containing the search terms given by the array expr using the fulltext-index.
 NodeSet[] getNodesContaining(DocumentSet doc, java.lang.String[] expr, int type)
          Gets the nodesContaining attribute of the DBBroker object
abstract  NodeSet getNodesEqualTo(NodeSet context, DocumentSet docs, int relation, java.lang.String expr)
          find all Nodes whose string value is equal to expr in the document set.
 java.lang.String getNodeValue(NodeProxy proxy)
          Gets the nodeValue attribute of the DBBroker object
 Collection getOrCreateCollection(java.lang.String name)
          Gets the orCreateCollection attribute of the DBBroker object
 Collection getOrCreateCollection(User user, java.lang.String name)
          Retrieve a collection by name.
abstract  org.w3c.dom.NodeList getRange(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  Serializer getSerializer()
          get an instance of the Serializer used for converting nodes back to XML.
static SymbolTable getSymbols()
           
abstract  TextSearchEngine getTextEngine()
          get the TextSearchEngine associated with this broker.
 void index(NodeImpl node)
           
 void insertAfter(NodeImpl previous, NodeImpl node)
           
 boolean isCaseSensitive()
          Gets the caseSensitive attribute of the DBBroker object
 boolean isReadOnly()
          Is the database running read-only? Returns false by default.
abstract  Serializer newSerializer()
          Description of the Method
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)
           
 void readDocumentMetadata(DocumentImpl doc)
           
 void registerNamespace(java.lang.String namespace, java.lang.String prefix)
          associate a prefix with a given namespace.
 void reindex(DocumentImpl oldDoc, DocumentImpl doc, NodeImpl node)
           
 boolean removeCollection(java.lang.String name)
          Description of the Method
abstract  boolean removeCollection(User user, java.lang.String name)
          Description of the Method
 void removeDocument(java.lang.String docName)
          Description of the Method
abstract  void removeDocument(User user, java.lang.String docName)
          remove the document with the given document name.
 void removeNode(NodeImpl node, java.lang.String currentPath)
           
abstract  void saveCollection(Collection collection)
          Store a collection into the database.
 Occurrences[] scanIndexedElements(User user, Collection collection, boolean inclusive)
           
 void shutdown()
          shutdown the broker.
abstract  void store(NodeImpl node, java.lang.CharSequence currentPath)
          Store a node into the database.
abstract  void storeDocument(DocumentImpl doc)
          Store a document into the database.
 void sync()
          Description of the Method
 void update(NodeImpl 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, toString, 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

MYSQL

public static final int MYSQL
See Also:
Constant Field Values

NATIVE

public static final int NATIVE
See Also:
Constant Field Values

ORACLE

public static final int ORACLE
See Also:
Constant Field Values

POSTGRESQL

public static final int POSTGRESQL
See Also:
Constant Field Values

DBM

public static final int DBM
See Also:
Constant Field Values

caseSensitive

protected boolean caseSensitive

config

protected Configuration config

pool

protected BrokerPool pool
Constructor Detail

DBBroker

public DBBroker(BrokerPool pool,
                Configuration config)
Constructor for the DBBroker object

Parameters:
config - Description of the Parameter
Method Detail

findElementsByTagName

public abstract NodeSet findElementsByTagName(DocumentSet docs,
                                              java.lang.String tagName)
find elements by their tag name. This method is comparable to the DOM's method call getElementsByTagName. All elements matching tagName and belonging to one of the documents in the DocumentSet docs are returned.

Parameters:
docs - Description of the Parameter
tagName - Description of the Parameter
Returns:
Description of the Return Value

flush

public void flush()
flush all data that has not been written before.


getAllDocuments

public DocumentSet getAllDocuments()
Gets the allDocuments attribute of the DBBroker object

Returns:
The allDocuments value

getAllDocuments

public abstract DocumentSet getAllDocuments(User user)
get all the documents in this database repository. The documents are returned as a DocumentSet.

Parameters:
user - Description of the Parameter
Returns:
The allDocuments value

getAttributesByName

public abstract NodeSet getAttributesByName(DocumentSet docs,
                                            java.lang.String name)
find elements by their tag name. This method is comparable to the DOM's method call getElementsByTagName. All elements matching tagName and belonging to one of the documents in the DocumentSet docs are returned.

Parameters:
docs - Description of the Parameter
name - Description of the Parameter
Returns:
The attributesByName value

getCollection

public abstract Collection getCollection(java.lang.String name)
Gets the collection attribute of the DBBroker object

Parameters:
name - Description of the Parameter
Returns:
The collection value

getCollection

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

getConfiguration

public Configuration getConfiguration()
get the configuration.

Returns:
The configuration value

getDOMIterator

public java.util.Iterator getDOMIterator(org.w3c.dom.Document doc,
                                         long gid)
Gets the dOMIterator attribute of the DBBroker object

Parameters:
doc - Description of the Parameter
gid - Description of the Parameter
Returns:
The dOMIterator value

getDOMIterator

public java.util.Iterator getDOMIterator(NodeProxy proxy)
Gets the dOMIterator attribute of the DBBroker object

Parameters:
proxy - Description of the Parameter
Returns:
The dOMIterator value

getNodeIterator

public java.util.Iterator getNodeIterator(NodeProxy proxy)

getDatabaseType

public abstract int getDatabaseType()
return the type of database this broker is connected to.

Returns:
one of the constants defined above.

getDocument

public org.w3c.dom.Document getDocument(java.lang.String fileName)
                                 throws PermissionDeniedException
Gets the document attribute of the DBBroker object

Parameters:
fileName - Description of the Parameter
Returns:
The document value
Throws:
PermissionDeniedException - Description of the Exception

getDocument

public abstract org.w3c.dom.Document getDocument(User user,
                                                 java.lang.String fileName)
                                          throws PermissionDeniedException
get a document by it's file name. The document's file name is used to identify a document. File names are stored without the leading path.

Parameters:
fileName - Description of the Parameter
user - Description of the Parameter
Returns:
The document value
Throws:
PermissionDeniedException - Description of the Exception

getDocumentsByCollection

public DocumentSet getDocumentsByCollection(java.lang.String collection)
                                     throws PermissionDeniedException
Gets the documentsByCollection attribute of the DBBroker object

Parameters:
collection - Description of the Parameter
Returns:
The documentsByCollection value
Throws:
PermissionDeniedException - Description of the Exception

getDocumentsByCollection

public abstract DocumentSet getDocumentsByCollection(User user,
                                                     java.lang.String collection)
                                              throws PermissionDeniedException
Gets the documentsByCollection attribute of the DBBroker object

Parameters:
collection - Description of the Parameter
user - Description of the Parameter
Returns:
The documentsByCollection value
Throws:
PermissionDeniedException - Description of the Exception

getDocumentsByCollection

public abstract DocumentSet getDocumentsByCollection(User user,
                                                     java.lang.String collection,
                                                     boolean inclusive)
                                              throws PermissionDeniedException
Gets the documentsByCollection attribute of the DBBroker object

Parameters:
collection - Description of the Parameter
inclusive - Description of the Parameter
user - Description of the Parameter
Returns:
The documentsByCollection value
Throws:
PermissionDeniedException - Description of the Exception

getDocumentsByDoctype

public DocumentSet getDocumentsByDoctype(java.lang.String doctype)
Gets the documentsByDoctype attribute of the DBBroker object

Parameters:
doctype - Description of the Parameter
Returns:
The documentsByDoctype value

getDocumentsByDoctype

public abstract DocumentSet getDocumentsByDoctype(User user,
                                                  java.lang.String doctypeName)
get all the documents in this database matching the given document-type's name.

Parameters:
doctypeName - Description of the Parameter
user - Description of the Parameter
Returns:
The documentsByDoctype value

getNamespacePrefix

public java.lang.String getNamespacePrefix(java.lang.String namespace)
get a common prefix for a namespace URI. It should be guaranteed that only one prefix is associated with one namespace URI throughout the database.

Parameters:
namespace - Description of the Parameter
Returns:
The namespacePrefix value

getNamespaceURI

public java.lang.String getNamespaceURI(java.lang.String prefix)
get the namespace associated with the given prefix. Every broker subclass should keep an internal map, where it stores the prefixes used for different namespaces. It should be guaranteed that only one prefix is associated with one namespace URI.

Parameters:
prefix - Description of the Parameter
Returns:
The namespaceURI value

getNextDocId

public abstract int getNextDocId(Collection collection)
Gets the nextDocId attribute of the DBBroker object

Parameters:
collection - Description of the Parameter
Returns:
The nextDocId value

getNodeValue

public java.lang.String getNodeValue(NodeProxy proxy)
Gets the nodeValue attribute of the DBBroker object

Parameters:
proxy - Description of the Parameter
Returns:
The nodeValue value

getNodesContaining

public abstract NodeSet[] getNodesContaining(DocumentSet doc,
                                             java.lang.String[] expr)
get all the nodes containing the search terms given by the array expr using the fulltext-index. Calls to this method are normally delegated to the associated instance of class TextSearchEngine.

Parameters:
doc - the set of documents to search through
expr - an array of search terms. a query is executed for each of them
Returns:
NodeSet[] an array of node sets, one for each search term

getNodesContaining

public NodeSet[] getNodesContaining(DocumentSet doc,
                                    java.lang.String[] expr,
                                    int type)
Gets the nodesContaining attribute of the DBBroker object

Parameters:
doc - Description of the Parameter
expr - Description of the Parameter
type - Description of the Parameter
Returns:
The nodesContaining value

getNodesEqualTo

public abstract NodeSet getNodesEqualTo(NodeSet context,
                                        DocumentSet docs,
                                        int relation,
                                        java.lang.String expr)
find all Nodes whose string value is equal to expr in the document set.

Parameters:
context - Description of the Parameter
docs - Description of the Parameter
relation - Description of the Parameter
expr - Description of the Parameter
Returns:
The nodesEqualTo value

getOrCreateCollection

public Collection getOrCreateCollection(java.lang.String name)
                                 throws PermissionDeniedException
Gets the orCreateCollection attribute of the DBBroker object

Parameters:
name - Description of the Parameter
Returns:
The orCreateCollection value
Throws:
PermissionDeniedException - Description of the Exception

getOrCreateCollection

public Collection getOrCreateCollection(User user,
                                        java.lang.String name)
                                 throws PermissionDeniedException
Retrieve a collection by name. This method is used by NativeBroker.java.

Parameters:
name - Description of the Parameter
user - Description of the Parameter
Returns:
The orCreateCollection value
Throws:
PermissionDeniedException - Description of the Exception

getRange

public abstract org.w3c.dom.NodeList getRange(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 node's belong to
first - unique id of the first node to retrieve
last - unique id of the last node to retrieve
Returns:
The range value

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

Returns:
The serializer value

getTextEngine

public abstract TextSearchEngine getTextEngine()
get the TextSearchEngine associated with this broker. Every subclass of DBBroker will have it's own implementation of TextSearchEngine.

Returns:
The textEngine value

isCaseSensitive

public boolean isCaseSensitive()
Gets the caseSensitive attribute of the DBBroker object

Returns:
The caseSensitive value

newSerializer

public abstract Serializer newSerializer()
Description of the Method

Returns:
Description of the Return Value

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
Returns:
Description of the Return Value

objectWith

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

registerNamespace

public void registerNamespace(java.lang.String namespace,
                              java.lang.String prefix)
associate a prefix with a given namespace. Every broker subclass should keep an internal map, where it stores the prefixes used for different namespaces. It should be guaranteed that only one prefix is associated with one namespace URI.

Parameters:
namespace - Description of the Parameter
prefix - Description of the Parameter

removeCollection

public boolean removeCollection(java.lang.String name)
                         throws PermissionDeniedException
Description of the Method

Parameters:
name - Description of the Parameter
Returns:
Description of the Return Value
Throws:
PermissionDeniedException - Description of the Exception

removeCollection

public abstract boolean removeCollection(User user,
                                         java.lang.String name)
                                  throws PermissionDeniedException
Description of the Method

Parameters:
name - Description of the Parameter
user - Description of the Parameter
Returns:
Description of the Return Value
Throws:
PermissionDeniedException - Description of the Exception

removeDocument

public void removeDocument(java.lang.String docName)
                    throws PermissionDeniedException
Description of the Method

Parameters:
docName - Description of the Parameter
Throws:
PermissionDeniedException - Description of the Exception

removeDocument

public abstract void removeDocument(User user,
                                    java.lang.String docName)
                             throws PermissionDeniedException
remove the document with the given document name.

Parameters:
docName - Description of the Parameter
user - Description of the Parameter
Throws:
PermissionDeniedException - Description of the Exception

saveCollection

public abstract void saveCollection(Collection collection)
                             throws PermissionDeniedException
Store a collection into the database.

Parameters:
collection - Description of the Parameter
Throws:
PermissionDeniedException

addDocument

public void addDocument(Collection collection,
                        DocumentImpl doc)
                 throws PermissionDeniedException
Throws:
PermissionDeniedException

closeDocument

public void closeDocument()

getSymbols

public static SymbolTable getSymbols()

shutdown

public void shutdown()
shutdown the broker. All open files, jdbc connections etc. should be closed.


store

public abstract void store(NodeImpl node,
                           java.lang.CharSequence currentPath)
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).

storeDocument

public abstract void storeDocument(DocumentImpl doc)
Store a document into the database.

Parameters:
doc - Description of the Parameter

sync

public void sync()
Description of the Method


update

public void update(NodeImpl node)
Update a node's data. This method is only used by the NativeBroker. To keep nodes in a correct sequential order, it sometimes needs to update a previous written node. Warning: don't use it for other purposes. RelationalBroker does not implement this method.

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

insertAfter

public void insertAfter(NodeImpl previous,
                        NodeImpl node)

reindex

public void reindex(DocumentImpl oldDoc,
                    DocumentImpl doc,
                    NodeImpl node)

index

public void index(NodeImpl node)

removeNode

public void removeNode(NodeImpl node,
                       java.lang.String currentPath)

endRemove

public void endRemove()

scanIndexedElements

public Occurrences[] scanIndexedElements(User user,
                                         Collection collection,
                                         boolean inclusive)
                                  throws PermissionDeniedException
Throws:
PermissionDeniedException

readDocumentMetadata

public void readDocumentMetadata(DocumentImpl doc)


Copyright (C) Wolfgang Meier. All rights reserved.