org.xquark.bridge
Class XQBridge

java.lang.Object
  org.xquark.bridge.XQBridge

public class XQBridge

extends java.lang.Object

Objects of this class encapsulate a JDBC connection and provide access to both the XQuery and insertion capabilities of the XQBridge.
Objects of this class are thread-safe and can be reused multiple times. However, as they encapsulate a JDBC connection, it is recommended to use different objects with different JDBC connections for different threads.

Constructor Summary

XQBridge(java.sql.Connection jdbcConn)
Deprecated. prevents the use of an external or internal data source.

XQBridge(java.sql.Connection jdbcConn, java.lang.String confURI)
Deprecated. prevents the use of an external or internal data source.

XQBridge(javax.sql.DataSource dataSource)
Constructor to use with a JDBC data source.

XQBridge(javax.sql.DataSource dataSource, java.io.File confFile)
Constructor to use with a JDBC data source and an extractor configuration file.

XQBridge(java.io.File confFile)
Constructor to use with an extractor configuration file.

XQBridge(java.lang.String URI)
Constructor to use with a configuration file URL or a JNDI name referencing a JDBC datasource instance.

XQBridge(java.lang.String url, java.lang.String userName, java.lang.String password)
Construction to use when JDBC connection parameters are available.

Method Summary

void	close() Closes the extractor and the underlying resources among which the internal JDBC data source except if it was passed at construction time.
java.lang.ClassLoader	getClassLoader() Returns the class loader used for loading drivers, mappings and user generators.
java.sql.Connection	getConnection() Deprecated. This method is linked to the deprecated constructor XQBridge(Connection, String).
Mapping	getMapping(org.xml.sax.InputSource source) Deprecated. Prefer the string methods because they do not create a problem for resolving relative URIs in mapping file schemaLocation attribute.
Mapping	getMapping(org.xml.sax.InputSource source, boolean reload) Deprecated. Prefer the string methods because they do not create a problem for resolving relative URIs in mapping file schemaLocation attribute.
Mapping	getMapping(java.lang.String fileURI) Creates a mapping object containing the processed version of the specified mapping file.
Mapping	getMapping(java.lang.String fileURI, boolean reload) Creates a mapping object containing the processed version of the specified mapping file.
ExtractorConnection	getXMLConnection() Returns an extractor XML/DBC connection that can be used to execute XQuery statements over the database.
void	loadSchema(org.xml.sax.InputSource source) Loads an XML schema in memory.
void	resetMappings(boolean resetSchemas) Empties the mappings cache.
void	setClassLoader(java.lang.ClassLoader loader) Set the class loader used for loading drivers, mappings and user generators.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XQBridge

public XQBridge(java.lang.String URI)

Constructor to use with a configuration file URL or a JNDI name referencing a JDBC datasource instance. The configuration file is expected to contain JDBC connection parameters or a JNDI name. Choose this last solution if you both need to specify a configuration file and a JNDI name. See the XQuery Language Reference Guide" for more information about configuration files.

Parameters:

URI - either the configuration file URL, or a JNDI reference that MUST be prefixed with the "jndi:" string to be recognized as this.

XQBridge

public XQBridge(java.io.File confFile)

Constructor to use with an extractor configuration file. See the XQuery Language Reference Guide for more information about configuration files.

XQBridge

public XQBridge(javax.sql.DataSource dataSource)

Constructor to use with a JDBC data source.

Throws:

XMLDBCException - API exception

XQBridge

public XQBridge(javax.sql.DataSource dataSource,
                java.io.File confFile)

Constructor to use with a JDBC data source and an extractor configuration file. See the XQuery Language Reference Guide for more information about configuration files.

Throws:

XMLDBCException - API exception

XQBridge

public XQBridge(java.lang.String url,
                java.lang.String userName,
                java.lang.String password)

Construction to use when JDBC connection parameters are available.

Parameters:

password - the password for the login name.

Throws:

XMLDBCException - API exception

XQBridge

public XQBridge(java.sql.Connection jdbcConn)

Deprecated. prevents the use of an external or internal data source.

Constructs an Extractor using a single JDBC connection. This connection should not be used while the XQBridge object is active.

Throws:

XMLDBCException - API exception

XQBridge

public XQBridge(java.sql.Connection jdbcConn,
                java.lang.String confURI)

Deprecated. prevents the use of an external or internal data source.

Constructs an Extractor using a single JDBC connection and a configuration file. The connection should not be used while the XQBridge object is active.

Throws:

XMLDBCException - API exception

Method Detail

getConnection

public java.sql.Connection getConnection()
                                  throws XMLDBCException

Deprecated. This method is linked to the deprecated constructor XQBridge(Connection, String).

Returns a JDBC connection used to access the underlying database.

Returns:

a JDBC connection. Null when no connection to the database is available.

Throws:

XMLDBCException

getXMLConnection

public ExtractorConnection getXMLConnection()
                                     throws XMLDBCException

Returns an extractor XML/DBC connection that can be used to execute XQuery statements over the database.

Returns:

an XMLConnection object

Throws:

XMLDBCException

close

public void close()
           throws XMLDBCException

Closes the extractor and the underlying resources among which the internal JDBC data source except if it was passed at construction time.

Throws:

XMLDBCException - API exception

setClassLoader

public void setClassLoader(java.lang.ClassLoader loader)

Set the class loader used for loading drivers, mappings and user generators.

Parameters:

loader - ClassLoader

getClassLoader

public java.lang.ClassLoader getClassLoader()

Returns the class loader used for loading drivers, mappings and user generators.

getMapping

public Mapping getMapping(org.xml.sax.InputSource source)
                   throws XMLDBCException

Deprecated. Prefer the string methods because they do not create a problem for resolving relative URIs in mapping file schemaLocation attribute.

Creates a mapping object containing the processed version of the specified mapping file. This object can subsequently be used to store XML documents in the database, according to the specified mapping.
The mapping file is specified as a SAX input source. If the systemId property of the input source is set, the object will first be looked up, based on this property, in the mapping cache, and only be created if not found.

Parameters:

source - a SAX input source encapsulating the mapping file.

Returns:

a Mapping object

Throws:

XMLDBCException - if an error occured while loading the mapping file. The underlying exception provides the root cause for the exception

getMapping

public Mapping getMapping(org.xml.sax.InputSource source,
                          boolean reload)
                   throws XMLDBCException

Deprecated. Prefer the string methods because they do not create a problem for resolving relative URIs in mapping file schemaLocation attribute.

Creates a mapping object containing the processed version of the specified mapping file. This object can subsequently be used to store XML documents in the database, according to the specified mapping.
The mapping file is specified as a SAX input source. If the systemId property of the input source is set, and the reload flag is false, the object will first be looked up, based on this property, in the mapping cache, and only be created if not found.

Parameters:

source - a SAX input source encapsulating the mapping file.

reload - true if the mapping file must be reloaded even if found in the cache.

Returns:

a Mapping object

Throws:

XMLDBCException - if an error occured while loading the mapping file. The underlying exception provides the root cause for the exception

getMapping

public Mapping getMapping(java.lang.String fileURI)
                   throws XMLDBCException

Creates a mapping object containing the processed version of the specified mapping file. This object can subsequently be used to store XML documents in the database, according to the specified mapping.
the object will first be looked up, based on the file URI, in the mapping cache, and only be created if not found.

Parameters:

fileURI - the URI of the mapping file.

Returns:

a Mapping object

Throws:

XMLDBCException - if an error occured while loading the mapping file. The underlying exception provides the root cause for the exception

getMapping

public Mapping getMapping(java.lang.String fileURI,
                          boolean reload)
                   throws XMLDBCException

Creates a mapping object containing the processed version of the specified mapping file. This object can subsequently be used to store XML documents in the database, according to the specified mapping.
If the reload flag is false, the object will first be looked up, based on the file URI, in the mapping cache, and only be created if not found.

Parameters:

fileURI - the URI of the mapping file.

reload - true if the mapping file must be reloaded even if found in the cache.

Returns:

a Mapping object

Throws:

XMLDBCException - if an error occured while loading the mapping file. The underlying exception provides the root cause for the exception

loadSchema

public void loadSchema(org.xml.sax.InputSource source)
                throws org.xml.sax.SAXException

Loads an XML schema in memory. This is useful for bypassing the automatic schema loading based upon the schemaLocation attribute (e.g. if there is no such attribute).

Throws:

org.xml.sax.SAXException

resetMappings

public void resetMappings(boolean resetSchemas)

Empties the mappings cache. All Mapping objects that were not closed will continue working with the old metadata.

Parameters:

resetSchemas - if the schema cache must be cleared as well