org.xquark.xml.xdbc
Interface XMLDocumentFiler

All Superinterfaces:
Configurable, org.xml.sax.ContentHandler, org.xml.sax.ErrorHandler, org.xml.sax.ext.LexicalHandler

public interface XMLDocumentFiler
extends org.xml.sax.ContentHandler, org.xml.sax.ErrorHandler, org.xml.sax.ext.LexicalHandler, Configurable

This interface is used to insert XML documents in XML collections. A single filer can store several documents sequentially, however it is an error to try to use a filer before the current storage is finished. Objects implementing this interface can be plugged into a SAX2 XMLReader to process XML data as SAX2 events. Both org.xml.sax.ContentHandler, org.xml.sax.ext.LexicalHandler and org.xml.sax.ErrorHandler are supported, so that comments and processing instructions are not lost during storage.

Notes:

  1. The error handler must absolutely be plugged so that the application could have a consistent behavior in case of parsing error due to to a malformed XML document.
  2. This object is likely to use resources that can be released using the close() method.


Method Summary
 void clearBuffer()
          Discards the XML data buffered by the filer since the last call to flushBuffer() method.
 void close()
          Closes the object and frees its associated resources.
 void flushBuffer()
          Sends buffered XML data to the data source.
 boolean getAutoFlush()
          Retrieves the current buffering mode.
 XMLCollection getCollection()
          Returns the XML collection that produced this object.
 java.lang.String getDocumentId()
          Gets the identifier to be used by the next document to be stored through this object.
 XMLErrorHandler getErrorHandler()
          Return the current error handler.
 XMLDocument insertDocument(org.w3c.dom.Document doc)
          Inserts the XML document in the filer's collection.
 XMLDocument insertDocument(org.w3c.dom.Document doc, java.lang.String id)
          Inserts the XML document in the filer's collection with the specified identifier.
 XMLDocument insertDocument(org.xml.sax.InputSource input)
          Inserts an XML document in the filer's collection using the SAX method.
 XMLDocument insertDocument(org.xml.sax.InputSource input, java.lang.String id)
          Inserts an XML document in the filer's collection using the SAX method.
 XMLDocument insertDocument(java.lang.String doc)
          Inserts the XML document contained in the string in the filer's collection.
 XMLDocument insertDocument(java.lang.String doc, java.lang.String id)
          Inserts the XML document contained in the string in the filer's collection with the specified identifier.
 XMLDocument insertDocument(org.xml.sax.XMLReader parser, org.xml.sax.InputSource input)
          Inserts an XML document in the filer's collection using the SAX method.
 XMLDocument insertDocument(org.xml.sax.XMLReader parser, org.xml.sax.InputSource input, java.lang.String id)
          Inserts an XML document in the filer's collection using the SAX method.
 void setAutoFlush(boolean activated)
          Turns on or off the automatic buffering mode.
 void setDocumentId(java.lang.String id)
          Sets the identifier of the next document to be stored through this object.
 void setErrorHandler(XMLErrorHandler handler)
          Allow an application to register an error event handler for non-fatal errors.
 
Methods inherited from interface org.xml.sax.ContentHandler
characters, endDocument, endElement, endPrefixMapping, ignorableWhitespace, processingInstruction, setDocumentLocator, skippedEntity, startDocument, startElement, startPrefixMapping
 
Methods inherited from interface org.xml.sax.ErrorHandler
error, fatalError, warning
 
Methods inherited from interface org.xml.sax.ext.LexicalHandler
comment, endCDATA, endDTD, endEntity, startCDATA, startDTD, startEntity
 
Methods inherited from interface org.xquark.xml.xdbc.Configurable
getFeature, getFeatureList, getProperty, getPropertyList, setFeature, setProperty
 

Method Detail

close

public void close()
           throws XMLDBCException
Closes the object and frees its associated resources.

Throws:
XMLDBCException - if a data source access error occurs.

getCollection

public XMLCollection getCollection()
Returns the XML collection that produced this object.

Returns:
the XML collection that produced this object.

setDocumentId

public void setDocumentId(java.lang.String id)
                   throws XMLDBCException
Sets the identifier of the next document to be stored through this object. The identifier is reset to null after each storage.

Parameters:
id - the identifier of the next document to be stored.
Throws:
XMLDBCException - if a data source access error occurs.

getDocumentId

public java.lang.String getDocumentId()
Gets the identifier to be used by the next document to be stored through this object. If this is null, an internal identifier will be used.

Returns:
the identifier to be used by the next document to be stored.

insertDocument

public XMLDocument insertDocument(org.xml.sax.InputSource input)
                           throws XMLDBCException,
                                  org.xml.sax.SAXException
Inserts an XML document in the filer's collection using the SAX method. The SAX parser is automatically allocated using JAXP. This method uses the identifier stored through the setDocumentId() method if available, or an internal identifier otherwise.

Parameters:
input - the SAX InputSource.
Returns:
the stored XML document.
Throws:
XMLDBCException - if a data source access error occurs.
org.xml.sax.SAXException - if a parse exception occurs.

insertDocument

public XMLDocument insertDocument(org.xml.sax.InputSource input,
                                  java.lang.String id)
                           throws XMLDBCException,
                                  org.xml.sax.SAXException
Inserts an XML document in the filer's collection using the SAX method. The SAX parser is automatically allocated using JAXP.

Parameters:
input - the SAX InputSource.
id - the document identifier in the collection.
Returns:
the stored XML document.
Throws:
XMLDBCException - if a data source access error occurs.
org.xml.sax.SAXException - if a parse exception occurs.

insertDocument

public XMLDocument insertDocument(org.xml.sax.XMLReader parser,
                                  org.xml.sax.InputSource input)
                           throws XMLDBCException,
                                  org.xml.sax.SAXException
Inserts an XML document in the filer's collection using the SAX method. This method uses the identifier stored through the setDocumentId() method if available, or an internal identifier otherwise.

Parameters:
parser - the SAX 2 XMLReader implementation.
input - the SAX InputSource.
Returns:
the stored XML document.
Throws:
XMLDBCException - if a data source access error occurs.
org.xml.sax.SAXException - if a parse exception occurs.

insertDocument

public XMLDocument insertDocument(org.xml.sax.XMLReader parser,
                                  org.xml.sax.InputSource input,
                                  java.lang.String id)
                           throws XMLDBCException,
                                  org.xml.sax.SAXException
Inserts an XML document in the filer's collection using the SAX method.

Parameters:
parser - the SAX 2 XMLReader implementation.
input - the SAX InputSource.
id - the document identifier in the collection.
Returns:
the stored XML document.
Throws:
XMLDBCException - if a data source access error occurs.
org.xml.sax.SAXException - if a parse exception occurs.

insertDocument

public XMLDocument insertDocument(org.w3c.dom.Document doc)
                           throws XMLDBCException
Inserts the XML document in the filer's collection. This method uses the identifier stored through the setDocumentId() method if available, or an internal identifier otherwise.

Parameters:
doc - the XML document as a DOM2 org.w3c.dom.Document.
Returns:
the stored XML document.
Throws:
XMLDBCException - if a data source access error occurs.

insertDocument

public XMLDocument insertDocument(org.w3c.dom.Document doc,
                                  java.lang.String id)
                           throws XMLDBCException
Inserts the XML document in the filer's collection with the specified identifier.

Parameters:
doc - the XML document as a DOM2 org.w3c.dom.Document.
id - the document identifier in the collection.
Returns:
the stored XML document.
Throws:
XMLDBCException - if a data source access error occurs.

insertDocument

public XMLDocument insertDocument(java.lang.String doc)
                           throws XMLDBCException,
                                  org.xml.sax.SAXException
Inserts the XML document contained in the string in the filer's collection. This method uses the identifier stored through the setDocumentId() method if available, or an internal identifier otherwise.

Parameters:
doc - a string containing the XML document.
Returns:
the stored XML document.
Throws:
XMLDBCException - if a data source access error occurs.
org.xml.sax.SAXException - if a parse exception occurs.

insertDocument

public XMLDocument insertDocument(java.lang.String doc,
                                  java.lang.String id)
                           throws XMLDBCException,
                                  org.xml.sax.SAXException
Inserts the XML document contained in the string in the filer's collection with the specified identifier.

Parameters:
doc - a string containing the XML document.
id - the document identifier in the collection.
Returns:
the stored XML document.
Throws:
XMLDBCException - if a data source access error occurs.
org.xml.sax.SAXException - if a parse exception occurs.

setAutoFlush

public void setAutoFlush(boolean activated)
                  throws XMLDBCException
Turns on or off the automatic buffering mode. If this mode is off XML documents are buffered by the filer until the flushBuffer() method is called providing a kind of 'manual' mode for controlling data flush. If the batch mode is on (the default) data is automatically flushed when a certain amount of data is reached or when a commit is performed on the connection.

Parameters:
activated - 'true' is the default and means that autoflush is on.
Throws:
XMLDBCException - if a data source access error occurs.

getAutoFlush

public boolean getAutoFlush()
Retrieves the current buffering mode.

Returns:
true if the 'automatic' buffering mode is activated.
See Also:
setAutoFlush(boolean)

flushBuffer

public void flushBuffer()
                 throws XMLDBCException
Sends buffered XML data to the data source. This method is to be called only when the automatic buffering mode is off.

Throws:
XMLDBCException - if a data source access error occurs.
See Also:
setAutoFlush(boolean)

clearBuffer

public void clearBuffer()
                 throws XMLDBCException
Discards the XML data buffered by the filer since the last call to flushBuffer() method. This method is to be called only when the automatic buffering mode is off.

Throws:
XMLDBCException - if a data source access error occurs.
See Also:
setAutoFlush(boolean)

setErrorHandler

public void setErrorHandler(XMLErrorHandler handler)
Allow an application to register an error event handler for non-fatal errors.

If the application does not register an error handler, all warning and non-fatal error events reported by the filer will be silently ignored and storage will continue.

Applications may register a new or different handler in the middle of a storage operation, and the filer must begin using the new handler immediately.

Parameters:
handler - The error handler.
Throws:
java.lang.NullPointerException - If the handler argument is null.
See Also:
getErrorHandler()

getErrorHandler

public XMLErrorHandler getErrorHandler()
Return the current error handler.

Returns:
The current error handler, or null if none has been registered.
See Also:
setErrorHandler(org.xquark.xml.xdbc.XMLErrorHandler)


Copyright © 2004 Université de Versailles Saint-Quentin, XQuark Group. All rights reserved.