org.slamb.axamol.library
Class Statement

java.lang.Object
  org.slamb.axamol.library.Statement

public class Statement
extends java.lang.Object

Parameterized SQL statement stored in XML.

Instances of this class are not tied to any particular database connection. They are also immutable (threadsafe) once parsed. Together, these two characteristics make this class work with database pools.

Version:

$Id: Statement.java 1234 2005-07-03 02:46:16Z slamb $

Author:

Scott Lamb <slamb@slamb.org>

Field Summary

protected java.util.Map	columns Information about explicitly specified columns.
protected java.util.Map	databases SQL stuff for each supported database type.
protected org.slamb.axamol.library.Statement.Handler	handler The handler parsing this or null if parsing is complete.
protected static org.apache.commons.logging.Log	log
protected java.lang.String	name The name of this statement.
static java.lang.String	NS_STATEMENT XML namespace for a statement.
protected java.util.Map	parameters Information for each parameter.
protected int	type The type of this query, TYPE_xxx.
static int	TYPE_QUERY Query statement.
static int	TYPE_UPDATE Update statement.
protected static java.util.Map	types

Constructor Summary

Statement()

Method Summary

void	clearTimings() Resets all peformance timings for this statement.
java.sql.ResultSet	executeQuery(java.sql.PreparedStatement p, java.util.Map params) Executes this statement as a query, returning the ResultSet.
int	executeUpdate(java.sql.PreparedStatement p, java.util.Map params) Executes this statement as an update.
java.util.Map	getColumns() Returns information about explicit columns.
org.xml.sax.ContentHandler	getHandler() Returns the handler being used to parse this statement.
java.lang.String	getName()
org.slamb.common.stats.Sample	getTimings() Retrieves statistics on time to execute.
int	getType() Returns the type of this statement.
boolean	isComplete() Returns true iff this statement is completely parsed.
java.lang.String	makeSQL(java.sql.Connection connection, java.util.Map params, java.lang.String orderByClause) Creates SQL for the given parameters.
void	setServerPrepare(java.sql.PreparedStatement ps) Tells the database server if it should use server-side prepared statements.

Methods inherited from class java.lang.Object

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

Field Detail

log

protected static final org.apache.commons.logging.Log log

types

protected static final java.util.Map types

NS_STATEMENT

public static final java.lang.String NS_STATEMENT

XML namespace for a statement.

See Also:

Constant Field Values

TYPE_QUERY

public static final int TYPE_QUERY

Query statement. Queries (select statements) return java.sql.ResultSet.

See Also:

Constant Field Values

TYPE_UPDATE

public static final int TYPE_UPDATE

Update statement. Updates (DML or DDL statements) return integers.

See Also:

Constant Field Values

type

protected int type

The type of this query, TYPE_xxx.

handler

protected org.slamb.axamol.library.Statement.Handler handler

The handler parsing this or null if parsing is complete.

name

protected java.lang.String name

The name of this statement. We need to know this mostly just for error messages; it's Library's responsibility to keep track of finding the right statement.

parameters

protected java.util.Map parameters

Information for each parameter. Keys are java.lang.String. Values are Parameter.

columns

protected java.util.Map columns

Information about explicitly specified columns. Queries only. Keys are java.lang.String. Values are Column. All columns are lowercased, to avoid differences between databases.

databases

protected java.util.Map databases

SQL stuff for each supported database type. Note that the same SQL section can be used for multiple databases. In this case, the values of two keys will be the same. Keys are java.lang.String. Values are java.util.Vector of java.lang.String.

Constructor Detail

Statement

public Statement()

Method Detail

getName

public java.lang.String getName()

getHandler

public org.xml.sax.ContentHandler getHandler()

Returns the handler being used to parse this statement.

Pre-condition: The statement is being parsed.

isComplete

public boolean isComplete()

Returns true iff this statement is completely parsed.

getType

public int getType()

Returns the type of this statement.

Returns:

TYPE_QUERY or TYPE_UPDATE as appropriate.

getColumns

public java.util.Map getColumns()

Returns information about explicit columns. Key: java.lang.String (lowercased name). Value: org.slamb.axamol.library.Statement.Column. The map is unmodifiable.

makeSQL

public java.lang.String makeSQL(java.sql.Connection connection,
                                java.util.Map params,
                                java.lang.String orderByClause)
                         throws java.sql.SQLException

Creates SQL for the given parameters. For simple queries, this will always return the same SQL. (Potential future optimization: find such cases, cache the SQL.) But for ones featuring bind lists or dynamic "order by" clauses, it can generate different SQL each time.

Parameters:

params - The parameters. If null, an empty map is used.

orderByClause - If non-null, will be appended with the leading text " order by ". Only makes sense for queries.

Throws:

java.sql.SQLException

setServerPrepare

public void setServerPrepare(java.sql.PreparedStatement ps)
                      throws java.sql.SQLException

Tells the database server if it should use server-side prepared statements. This should be called once per PreparedStatement, immediately after it is created. It just passes along what the user said, which might be nothing. In some cases featuring potentially-large bind lists, though, the user might tell us that it is more efficient to not mess around with server-side prepared statements, since each one is likely to be used only once.

Throws:

java.sql.SQLException

executeQuery

public java.sql.ResultSet executeQuery(java.sql.PreparedStatement p,
                                       java.util.Map params)
                                throws java.sql.SQLException

Executes this statement as a query, returning the ResultSet.

Pre-condition: This is a query statement, not an update statement.

Parameters:

p - A prepared statement, as returned by p.

params - The invocation parameters. If null, an empty map is used.

Returns:

The result set. It is the caller's responsibility to dispose of it when finished.

Throws:

java.sql.SQLException

See Also:

makeSQL(java.sql.Connection, java.util.Map, java.lang.String), executeUpdate(java.sql.PreparedStatement, java.util.Map), PreparedStatement.executeQuery()

executeUpdate

public int executeUpdate(java.sql.PreparedStatement p,
                         java.util.Map params)
                  throws java.sql.SQLException

Executes this statement as an update.

Pre-condition: This is an update statement, not a query statement.

Parameters:

p - A prepared statement, as returned by p.

params - The invocation parameters. If null, an empty map is used.

Returns:

The number of affected rows for DML operations. 0 for DDL operations.

Throws:

java.sql.SQLException

See Also:

makeSQL(java.sql.Connection, java.util.Map, java.lang.String), executeQuery(java.sql.PreparedStatement, java.util.Map), PreparedStatement.executeUpdate()

clearTimings

public void clearTimings()

Resets all peformance timings for this statement. Use when the earlier timings are no longer valid—perhaps when adding indexes to the database.

getTimings

public org.slamb.common.stats.Sample getTimings()

Retrieves statistics on time to execute. The timings describe all runs since statemnt initiation or the last call to clearTimings. The returned Sample is cloned from this statement's sample, so it will not be changed by further executions.