org.nsdl.mptstore.core
Interface DatabaseAdaptor

All Known Implementing Classes:

GenericDatabaseAdaptor

public interface DatabaseAdaptor

The main high-level interface for working with a triplestore.

With a DatabaseAdaptor, you can add and delete triples and perform interpreted queries against the triplestore.

Note that each method takes an existing JDBC Connection as a parameter. Client applications are expected to open/close or borrow/release connections as needed. In addition, transaction boundaries are expected to be managed externally.

Author:

cwilper@cs.cornell.edu

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 lang, int fetchSize, boolean autoReleaseConnection, java.lang.String queryText) Evaluate the given query in the specified language and return the results.

Method Detail

addTriples

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

Add the given triples.

Parameters:

conn - The database connection to use.

triples - The triples to add.

Throws:

ModificationException - if the operation failed for any reason.

deleteTriples

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

Delete the given triples.

Parameters:

conn - The database connection to use.

triples - The triples to delete.

Throws:

ModificationException - if the operation failed for any reason.

deleteAllTriples

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

Delete all triples.

Parameters:

conn - The database connection to use.

Throws:

ModificationException - if the operation failed for any reason.

query

QueryResults query(java.sql.Connection connection,
                   QueryLanguage lang,
                   int fetchSize,
                   boolean autoReleaseConnection,
                   java.lang.String queryText)
                   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.

Parameters:

connection - the database connection to use.

lang - 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.

queryText - The query.

Returns:

the results.

Throws:

QueryException - if the query failed for any reason.