org.ozoneDB.xml.util
Class XMLContainer

java.lang.Object
  extended byorg.ozoneDB.xml.util.XMLContainer
All Implemented Interfaces:
java.io.Externalizable, org.ozoneDB.xml.util.SAXChunkProducerDelegate, java.io.Serializable

public class XMLContainer
extends java.lang.Object
implements java.io.Externalizable, org.ozoneDB.xml.util.SAXChunkProducerDelegate

This class is the central part of the ozone/XML API. Basically it provides a persistent container for a XML document, which is stored in an ozone database.

IMPORTANT:
Before calling one of the store or extract methods the thread must have joined a transaction.

Usage of the SAX methods is recomended, because of the better performance.

Version:
$Revision$ $Date$
Author:
SMB
See Also:
Serialized Form

Field Summary
static boolean debug
           
 
Constructor Summary
protected XMLContainer(org.ozoneDB.OzoneInterface _db, XMLContainerHelper _helper)
           
 
Method Summary
 void delete()
          Deletes the container (and the associated document) from the database.
protected  org.infozone.tools.xml.queries.XObject executeXPath(OzoneXPathQuery _query)
           
protected  void executeXUpdate(OzoneXUpdateQuery _query)
           
 org.w3c.dom.Document extractDOM(org.w3c.dom.Document _domFactory)
           
 org.w3c.dom.NodeList extractDOM(org.w3c.dom.Document _domFactory, org.w3c.dom.NodeList _pNodes, org.w3c.dom.Node _appendTo, int _depth)
           
 org.w3c.dom.Node extractDOM(org.w3c.dom.Document _domFactory, org.w3c.dom.Node _pNode, org.w3c.dom.Node _appendTo)
           
 org.w3c.dom.Node extractDOM(org.w3c.dom.Document _domFactory, org.w3c.dom.Node _pNode, org.w3c.dom.Node _appendTo, int _depth)
          Extracts a given DOM node and all its descendants.
 void extractSAX(org.xml.sax.ContentHandler _contentHandler)
           
 void extractSAX(org.xml.sax.ContentHandler _contentHandler, org.w3c.dom.Node _pNode)
           
 void extractSAX(org.xml.sax.ContentHandler _contentHandler, org.w3c.dom.Node _pNode, int _depth)
          Extracts a given DOM node and all its descendants.
static XMLContainer forName(org.ozoneDB.OzoneInterface _db, java.lang.String _docName)
          Returns the XMLContainer representing the document with the given name.
static XMLContainer forNode(org.ozoneDB.OzoneInterface _db, org.w3c.dom.Node _pNode)
          Returns the XMLContainer representing the document the given node belongs to.
 org.w3c.dom.Document getPDocument()
          Get the underlying persistent document that this container is working on.
static XMLContainer newContainer(org.ozoneDB.OzoneInterface _db, java.lang.String _docName)
          Creates a new container with the given name.
 OzoneXPathQuery newXPathQuery()
          Create a new XPath query.
 OzoneXUpdateQuery newXUpdateQuery()
          Create a new XUpdate query.
 void processChunk(org.ozoneDB.xml.util.SAXChunkProducer _producer)
          This method is for internal use only.
 void readExternal(java.io.ObjectInput _in)
           
 void setName(java.lang.String _name)
          Changes the name of this container.
 void storeDOM(org.w3c.dom.Document _tNode)
          Stores a transient DOM tree database.
 void storeDOM(org.w3c.dom.Node _pNode, org.w3c.dom.Node _tNode)
          Stores a transient node into the database.
 org.xml.sax.ContentHandler storeSAX()
          Stores a DOM tree represented by SAX events in the datasabase.
 org.xml.sax.ContentHandler storeSAX(org.w3c.dom.Node _pNode)
          Stores XML represented by SAX events into the database.
 void writeExternal(java.io.ObjectOutput _out)
           
 java.lang.String xpathForNode(org.w3c.dom.Node _pnode)
          Determines the absolute XPath for the given node.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

debug

public static final boolean debug
See Also:
Constant Field Values
Constructor Detail

XMLContainer

protected XMLContainer(org.ozoneDB.OzoneInterface _db,
                       XMLContainerHelper _helper)
Method Detail

newContainer

public static XMLContainer newContainer(org.ozoneDB.OzoneInterface _db,
                                        java.lang.String _docName)
                                 throws java.lang.Exception
Creates a new container with the given name.

Parameters:
_db - The database where the container will be stored.
_docName - The name of the container (and the document).
Returns:
the new container.
Throws:
java.lang.Exception

forName

public static XMLContainer forName(org.ozoneDB.OzoneInterface _db,
                                   java.lang.String _docName)
                            throws java.lang.Exception
Returns the XMLContainer representing the document with the given name.

Parameters:
_db - The database where the container is stored.
_docName - The name under which the container has been stored.
Returns:
the container for the given name or null if the container does not exist.
Throws:
java.lang.Exception

forNode

public static XMLContainer forNode(org.ozoneDB.OzoneInterface _db,
                                   org.w3c.dom.Node _pNode)
                            throws java.lang.Exception
Returns the XMLContainer representing the document the given node belongs to.

Parameters:
_db - The database where the container is stored.
_pNode - A node of the document the container represents.
Returns:
the container for the given node or null if the node has not been stored using the XMLContainer class.
Throws:
java.lang.Exception

setName

public void setName(java.lang.String _name)
             throws java.lang.Exception
Changes the name of this container.

Parameters:
_name - The new name of this container or null to remove the current name.
Throws:
java.lang.Exception

delete

public void delete()
            throws java.lang.Exception
Deletes the container (and the associated document) from the database.

Throws:
java.lang.Exception

getPDocument

public org.w3c.dom.Document getPDocument()
                                  throws java.lang.Exception
Get the underlying persistent document that this container is working on.

Returns:
The persistent document.
Throws:
java.lang.Exception

storeDOM

public void storeDOM(org.w3c.dom.Document _tNode)
              throws java.lang.Exception
Stores a transient DOM tree database. The newly created Nodes are appended to the Document Node of this container.

Throws:
java.lang.Exception
See Also:
storeDOM(Node, Node)

storeDOM

public void storeDOM(org.w3c.dom.Node _pNode,
                     org.w3c.dom.Node _tNode)
              throws java.lang.Exception
Stores a transient node into the database.

Before calling this method the current thread must have joined an explicit Transaction. This is an exception to the normal case, where an implicit transaction (handled by Ozone) is more appropriate.

Note:
If ever possible the corresponding SAX method should be used, because the performance of SAX storage is much better.

Parameters:
_pNode - The persistent node where the stored node will be appended to. Null replaces the current document.
_tNode - The transient node to be stored.
Throws:
java.lang.IllegalStateException - if the underlying document has already been deleted.
java.lang.IllegalArgumentException - if _tnode was null.
java.lang.IllegalStateException - if the current thread has not joined a transaction.
java.lang.Exception
See Also:
ExternalTransaction, ExternalDatabase.newTransaction()

storeSAX

public org.xml.sax.ContentHandler storeSAX()
                                    throws java.lang.Exception
Stores a DOM tree represented by SAX events in the datasabase. The newly created Nodes are appended to the Document Node of this container.

Throws:
java.lang.Exception
See Also:
storeSAX(Node)

storeSAX

public org.xml.sax.ContentHandler storeSAX(org.w3c.dom.Node _pNode)
                                    throws java.lang.Exception
Stores XML represented by SAX events into the database.

The entire storage process must be enclosed by an explicit Transaction. This is an exception to the normal case, where an implicit transaction (handled by Ozone) is more appropriate. The storage process starts with the call to this method and ends with the last event send to the content handler. The SAX events must be properly terminated, i.e. there must be an end event for for every start event, otherwise the correct storage can't be guaranteed.

Parameters:
_pNode - The persistent node where the stored data will be appended to.
Returns:
the content handler which stores all XML data it recieves into the database.
Throws:
java.lang.IllegalStateException - if the underlying document has already been deleted.
java.lang.IllegalStateException - if the current thread has not joined a transaction.
java.lang.Exception
See Also:
ExternalTransaction, ExternalDatabase.newTransaction()

processChunk

public void processChunk(org.ozoneDB.xml.util.SAXChunkProducer _producer)
                  throws java.lang.Exception
This method is for internal use only. Don't call it directly.

Specified by:
processChunk in interface org.ozoneDB.xml.util.SAXChunkProducerDelegate
Throws:
java.lang.Exception

extractDOM

public org.w3c.dom.Document extractDOM(org.w3c.dom.Document _domFactory)
                                throws java.lang.Exception
Throws:
java.lang.Exception
See Also:
extractDOM(Document, Node, Node , int)

extractDOM

public org.w3c.dom.Node extractDOM(org.w3c.dom.Document _domFactory,
                                   org.w3c.dom.Node _pNode,
                                   org.w3c.dom.Node _appendTo)
                            throws java.lang.Exception
Throws:
java.lang.Exception
See Also:
extractDOM(Document, Node, Node , int)

extractDOM

public org.w3c.dom.Node extractDOM(org.w3c.dom.Document _domFactory,
                                   org.w3c.dom.Node _pNode,
                                   org.w3c.dom.Node _appendTo,
                                   int _depth)
                            throws java.lang.Exception
Extracts a given DOM node and all its descendants.

Before calling this method the current thread must have joined an explicit Transaction. This is an exception to the normal case, where an implicit transaction (handled by Ozone) is more appropriate.

Note:
If possible, the corresponding SAX method should be used, because the performance of SAX retrieval is much better.

Parameters:
_domFactory - The DOM Document that is used to create the extracted DOM nodes.
_pNode - The persistent DOM node
_appendTo - The transient DOM node where the extracted content will will be appended to.
_depth - The number of hierarchy steps that should be extracted or null if the entire hierarchy should be extracted.
Throws:
java.lang.Exception

extractDOM

public org.w3c.dom.NodeList extractDOM(org.w3c.dom.Document _domFactory,
                                       org.w3c.dom.NodeList _pNodes,
                                       org.w3c.dom.Node _appendTo,
                                       int _depth)
                                throws java.lang.Exception
Throws:
java.lang.Exception

extractSAX

public void extractSAX(org.xml.sax.ContentHandler _contentHandler)
                throws java.lang.Exception
Throws:
java.lang.Exception
See Also:
extractSAX(ContentHandler, Node, int)

extractSAX

public void extractSAX(org.xml.sax.ContentHandler _contentHandler,
                       org.w3c.dom.Node _pNode)
                throws java.lang.Exception
Throws:
java.lang.Exception
See Also:
extractSAX(ContentHandler, Node , int )

extractSAX

public void extractSAX(org.xml.sax.ContentHandler _contentHandler,
                       org.w3c.dom.Node _pNode,
                       int _depth)
                throws java.lang.Exception
Extracts a given DOM node and all its descendants.

Before calling this method the current thread must have joined an explicit Transaction. This is an exception to the normal case, where an implicit transaction (handled by Ozone) is more appropriate.

Parameters:
_contentHandler - The ContentHandler that will receive the generated SAX events.
_pNode - The persistent DOM node that is the starting point, or null if the entire document should be extracted.
_depth - The number of hierarchy steps that should be extracted or null if the entire hierarchy should be extracted.
Throws:
java.lang.Exception

newXUpdateQuery

public OzoneXUpdateQuery newXUpdateQuery()
Create a new XUpdate query. XUpdate is a descriptive XML update language. XUpdate is the recommended way to change a document in the database. See www.xmldb.org for more information and some XUpdate documentation.

See Also:
OzoneXUpdateQuery

newXPathQuery

public OzoneXPathQuery newXPathQuery()
Create a new XPath query.

See Also:
OzoneXPathQuery

executeXUpdate

protected void executeXUpdate(OzoneXUpdateQuery _query)
                       throws java.lang.Exception
Throws:
java.lang.Exception

executeXPath

protected org.infozone.tools.xml.queries.XObject executeXPath(OzoneXPathQuery _query)
                                                       throws java.lang.Exception
Throws:
java.lang.Exception

xpathForNode

public java.lang.String xpathForNode(org.w3c.dom.Node _pnode)
Determines the absolute XPath for the given node.

Parameters:
_pnode - The W3C DOM node whose XPath is to determine.
Returns:
The string representing the absolute XPath for this node.

writeExternal

public void writeExternal(java.io.ObjectOutput _out)
                   throws java.io.IOException
Specified by:
writeExternal in interface java.io.Externalizable
Throws:
java.io.IOException

readExternal

public void readExternal(java.io.ObjectInput _in)
                  throws java.io.IOException,
                         java.lang.ClassNotFoundException
Specified by:
readExternal in interface java.io.Externalizable
Throws:
java.io.IOException
java.lang.ClassNotFoundException


Copyright © 2004 The Ozone Database Project - www.ozone-db.org. All Rights Reserved.