org.nsdl.mptstore.core
Class GenericDatabaseAdaptor

java.lang.Object
  org.nsdl.mptstore.core.GenericDatabaseAdaptor

All Implemented Interfaces:

DatabaseAdaptor

public class GenericDatabaseAdaptor
extends java.lang.Object
implements DatabaseAdaptor

A DatabaseAdaptor designed to work with any database. This implementation uses only a subset of standard SQL92 syntax and thus should be compatible with most RDBMS.

Author:

cwilper@cs.cornell.edu

Constructor Summary

GenericDatabaseAdaptor(TableManager tableManager, boolean backslashIsEscape)
Get an instance supporting the built-in query languages.

GenericDatabaseAdaptor(TableManager tableManager, java.util.Map<QueryLanguage,QueryCompiler> compilerMap)
Get an instance supporting the specified query languages.

Method Summary

void	addTriples(java.sql.Connection conn, java.util.Iterator<Triple> triples) Add the given triples.
void	deleteAllTriples(java.sql.Connection conn) Delete all triples.
void	deleteTriples(java.sql.Connection conn, java.util.Iterator<Triple> triples) Delete the given triples.
QueryResults	query(java.sql.Connection connection, QueryLanguage language, int fetchSize, boolean autoReleaseConnection, java.lang.String query) Evaluate the given query in the specified language and return the results.

Methods inherited from class java.lang.Object

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

Constructor Detail

GenericDatabaseAdaptor

public GenericDatabaseAdaptor(TableManager tableManager,
                              boolean backslashIsEscape)

Get an instance supporting the built-in query languages.

Parameters:

tableManager - The TableManager this instance should use.

backslashIsEscape - A database vendor-specific specific value indicating whether the backslash character in a string is considered to be an escape character.

GenericDatabaseAdaptor

public GenericDatabaseAdaptor(TableManager tableManager,
                              java.util.Map<QueryLanguage,QueryCompiler> compilerMap)

Get an instance supporting the specified query languages.

Parameters:

tableManager - The TableManager this instance should use.

compilerMap - A map of query language to query compiler.

Method Detail

addTriples

public void addTriples(java.sql.Connection conn,
                       java.util.Iterator<Triple> triples)
                throws ModificationException

Add the given triples.

Specified by:

addTriples in interface DatabaseAdaptor

Parameters:

conn - The database connection to use.

triples - The triples to add.

Throws:

ModificationException - if the operation failed for any reason.

deleteTriples

public void deleteTriples(java.sql.Connection conn,
                          java.util.Iterator<Triple> triples)
                   throws ModificationException

Delete the given triples.

Specified by:

deleteTriples in interface DatabaseAdaptor

Parameters:

conn - The database connection to use.

triples - The triples to delete.

Throws:

ModificationException - if the operation failed for any reason.

deleteAllTriples

public void deleteAllTriples(java.sql.Connection conn)
                      throws ModificationException

Delete all triples.

Specified by:

deleteAllTriples in interface DatabaseAdaptor

Parameters:

conn - The database connection to use.

Throws:

ModificationException - if the operation failed for any reason.

query

public QueryResults query(java.sql.Connection connection,
                          QueryLanguage language,
                          int fetchSize,
                          boolean autoReleaseConnection,
                          java.lang.String query)
                   throws QueryException

Evaluate the given query in the specified language and return the results.

Who releases the connection?

That depends. If autoReleaseConnection is true, the caller is guaranteed that if the query fails or the results are closed at any time, the connection will be restored to auto-commit mode and released. This can greatly simplify the caller's job as it can forget about the connection and just make sure the QueryResults object is closed.

On the other hand, if autoReleaseConnection is false, the caller is entirely responsible for the connection. This is useful in cases where the query is only part of an as-yet incomplete transaction.

How do I avoid running out of memory?

The fetchSize parameter can be used to avoid memory exhaustion when the number of expected results may be very large. The parameter acts as a hint to the JDBC driver as to the number of rows that should be retrieved from the database at a time.

If specified as 0, the hint is ignored and the database will likely send all results at once for each ResultSet. On very large result sets, this can result in memory exhaustion.

If you don't want to accept the default behavior, you should also be aware of how the underlying RDBMS handles fetch sizes. For example:

• As of MySQL 5.0, the only valid values for fetchSize are 0 and Integer.MIN_VALUE. The latter actually provides one result at a time and has table locking consequences.
• As of Postgres 8.1, any custom fetch size will work, but "implicit cursors" are not supported, so the query must occur within a transaction in order for the value to be respected.

Specified by:

query in interface DatabaseAdaptor

Parameters:

connection - the database connection to use.

language - the language of the query.

fetchSize - gives the JDBC driver a hint as to the number of rows that should be fetched from the database when more rows are needed. If zero, the hint is ignored and the database may send all results to the driver at once.

autoReleaseConnection - whether to automatically release/close the connection if the query fails or the results are closed.

query - The query.

Returns:

the results.

Throws:

QueryException - if the query failed for any reason.