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)