org.xquark.bridge
Interface Mapper

All Superinterfaces:
org.xml.sax.ContentHandler, org.xml.sax.ErrorHandler

public interface Mapper
extends org.xml.sax.ContentHandler, org.xml.sax.ErrorHandler

Objects implementing this class are used to store XML data into a database according to the parent mapping.
An object of this class cannot be used in multiple threads concurrently. Different Mappers can be used concurrently by different threads.
A Mapper may be used multiple times, to store several documents based on the same mapping.
A Mapper provides three different interfaces to store XML data: the most efficient is based on SAX2, as the Mapper can be plugged directly as a org.xml.sax.ContentHandler into any XML parser implementing the org.xml.sax.XMLReader interface. Note that with this method the error handler must also be plugged so that the mapper can have a consistent behavior in case of parsing error due to a malformed XML document (perform a rollback). For convenience, a DOM2-based and a string-based interfaces are also provided.
A Mapper object must be explicitly closed after use, in order to free its associated database resources.

See Also:
XMLReader

Field Summary
static java.lang.String RCSName
           
static java.lang.String RCSRevision
           
 
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.
 java.sql.Connection getConnection()
          Return the JDBC connection used by this object.
 java.lang.String getDocumentBase()
          Retrieves the current document base used by this object.
 XMLErrorHandler getErrorHandler()
          Return the current error handler.
 Mapping getMapping()
          Returns the mapping used by this object
 void insertDocument(org.w3c.dom.Document doc)
          Inserts the XML data contained in the DOM2 document in the database.
 void insertDocument(org.xml.sax.InputSource input)
          Inserts an XML document in the database using the SAX method.
 void insertDocument(java.lang.String doc)
          Inserts the XML data contained in the string in the database.
 void insertDocument(org.xml.sax.XMLReader parser, org.xml.sax.InputSource input)
          Inserts an XML document in database using the SAX method.
 void setAutoFlush(boolean activated)
          Turns on or off the automatic buffering mode.
 void setDocumentBase(java.lang.String URI)
          This method is to be used when the document stored contains an 'xsi:schemaLocation' attribute (or any element or attribute with the XML Schema type 'anyURI') that uses relatives URIs and when the API used to store documents does not use an InputSource with the SystemID set (e.g.
 void setErrorHandler(XMLErrorHandler handler)
          Allows 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
 

Field Detail

RCSRevision

public static final java.lang.String RCSRevision
See Also:
Constant Field Values

RCSName

public static final java.lang.String RCSName
See Also:
Constant Field Values
Method Detail

getMapping

public Mapping getMapping()
Returns the mapping used by this object

Returns:
the parent mapping

close

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

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

insertDocument

public void insertDocument(org.xml.sax.InputSource input)
                    throws XMLDBCException,
                           org.xml.sax.SAXException
Inserts an XML document in the database using the SAX method. The SAX parser is automatically allocated using JAXP.

Parameters:
input - the SAX InputSource.
Throws:
XMLDBCException - if a data source access error occurs.
SAXException - if a parsing error occurs.

insertDocument

public void insertDocument(org.xml.sax.XMLReader parser,
                           org.xml.sax.InputSource input)
                    throws XMLDBCException,
                           org.xml.sax.SAXException
Inserts an XML document in database using the SAX method.

Parameters:
parser - the SAX 2 XMLReader implementation.
input - the SAX InputSource.
Throws:
XMLDBCException - if a data source access error occurs.
SAXException - if a parsing error occurs.

insertDocument

public void insertDocument(org.w3c.dom.Document doc)
                    throws XMLDBCException
Inserts the XML data contained in the DOM2 document in the database.

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

insertDocument

public void insertDocument(java.lang.String doc)
                    throws XMLDBCException,
                           org.xml.sax.SAXException
Inserts the XML data contained in the string in the database.

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

getConnection

public java.sql.Connection getConnection()
Return the JDBC connection used by this object. It can be used to perform custom queries in the relational database.

Returns:
A JDBC connection.

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)

setErrorHandler

public void setErrorHandler(XMLErrorHandler handler)
Allows 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()

setDocumentBase

public void setDocumentBase(java.lang.String URI)
This method is to be used when the document stored contains an 'xsi:schemaLocation' attribute (or any element or attribute with the XML Schema type 'anyURI') that uses relatives URIs and when the API used to store documents does not use an InputSource with the SystemID set (e.g. DOM or String ones). The document base provided is then used to resolve the relative URI into an absolute one.

Parameters:
URI - The URI to be used as base during document storage.
See Also:
getDocumentBase()

getDocumentBase

public java.lang.String getDocumentBase()
Retrieves the current document base used by this object.

Returns:
an URI.
See Also:
setDocumentBase(String)

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 until the flushBuffer() method is called, providing a kind of 'manual' mode for controlling data flush. If the automatic mode is on (the default) data is automatically flushed after each document insertion.

Important note: The manual mode is only useful if the JDBC connection autoCommit mode is false (otherwise, a flushBuffer() and commit() are automatically called at the end of each document insertion, regardless of the autoFlush mode). When both autoCommit and autoFlush are turned off, the user MUST call flushBuffer() before committing the changes.

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)


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