|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface Statement
The representation of a SQL statement. Here is the lifecycle of a statement:
Database.createStatement(String)
Statement.prepare()
Statement.bind(int, int)
and associated methods, starting from 1 for the first formal.
Statement.getCursor()
, which returns a Cursor
; or
update execution: via Statement.execute()
.
bind()
, parameters can be bound to actual values. All bindings can be reset via Statement.reset()
.
There are two main ways to number the parameters:
bind()
takes the number of the parameter and the value to be bound to it.
An illegal index (out of the allowed range) causes a DatabaseException
to be thrown.
Here's an example of a statement using parameters that are numbered sequentially.
// Create a SELECT statement with the bounds specified as sequentially assigned parameters. Statement s = Database.createStatement("SELECT * FROM T WHERE a < ? AND a > ?"); s.prepare(); s.bind(1, upperBound); // an integer specifying the upper bound. s.bind(2, lowerBound); // an integer specifying the lower bound. Cursor c = s.getCursor(); // Now iterate over the data set using the Cursor.The statement can also specify explicitly numbered values:
Statement s = Database.createStatement("SELECT * FROM T WHERE a < ?5 AND a > ?12");
s.prepare();
// In this case, bind()
should be used with the value numbers:
s.bind(5, upperBound); // an integer specifying the upper bound.
s.bind(12, lowerBound); // an integer specifying the lower bound.
// Now iterate over the data set using the Cursor.
For getFormalName()
to return the parameter name, you must provide a name in the query.
For example, when you call getFormalName
, the statement "SELECT * FROM T WHERE a = :a"
will
return :a
.
When parameters such as a question mark (?
) are used as placeholders, the getFormalName()
method cannot return a parameter name.
For example, getFormalName
will not return the name for the parameter in this statement:
"SELECT * FROM T WHERE a = ?"
Method Summary | ||
---|---|---|
|
void |
bind(int index,
boolean value)
Binds a Boolean parameter in the statement. |
|
void |
bind(int index,
byte value)
Binds a byte parameter in the statement. |
|
void |
bind(int index,
byte[] value)
Binds a byte[] parameter in the statement. |
|
void |
bind(int index,
byte[] value,
int offset)
Binds a byte[] parameter in the statement. |
|
void |
bind(int index,
byte[] value,
int offset,
int length)
Binds a byte[] parameter in the statement. |
|
void |
bind(int index,
double value)
Binds a double parameter in the statement. |
|
void |
bind(int index,
float value)
Binds a float parameter in the statement. |
|
void |
bind(int index,
int value)
Binds an integer parameter in the statement. |
|
void |
bind(int index,
String value)
Binds a String parameter in the statement. |
|
void |
bind(int index,
long value)
Binds a long parameter in the statement. |
|
void |
bind(int index,
short value)
Binds a short parameter in the statement. |
|
void |
close()
Closes the current statement and releases all resources. |
|
void |
execute()
Executes an UPDATE statement. |
|
String[] |
getColumnNames()
Gets the names of the columns of this statement. |
|
Cursor |
getCursor()
Executes a query statement and returns a cursor with selected rows. |
|
int |
getFormalIndex(String paramName)
Converts the named SQL parameter into a parameter index that can be used in bind() calls. |
|
String |
getFormalName(int index)
Converts a parameter index to a SQL parameter name. |
|
int |
getParameterCount()
Returns the largest index of all SQL parameters in a statement, or 0 if there are no SQL parameters. |
|
String |
getTail()
Gets the unparsed portion of a prepared statement (the "tail"); this method is applicable for multiple statements separated by semicolons (;). |
|
void |
prepare()
Prepares a statement for execution. |
|
void |
reset()
Resets a Statement to its state just after Statement.prepare() . |
|
void |
rewind()
Statement.prepare() . |
Method Detail |
---|
void prepare() throws DatabaseException
DatabaseException
- Database is closed or a SQL statement has already been prepared.String getTail() throws DatabaseException
DatabaseException
- If the database is closed or the
statement has not been prepared.void execute() throws DatabaseException
This method should be called only with statements that do not return a result set. These include INSERT, UPDATE, DELETE and similar SQL statements.
Only the first call to this method performs data updates. Subsequent calls are disregarded.
DatabaseException
Statement.getCursor()
Cursor getCursor() throws DatabaseException
This method should be called only with statements that return
a result set, such as SELECT.
For statements that return no result set (such as UPDATE), use Statement.execute()
.
The first call to getCursor()
creates a Cursor. Each subsequent call to
getCursor()
for the same instance of the statement returns the same Cursor instance.
reset()
on the statement
discards all bound values, and invalidates the current Cursor. A
subsequent call to getCursor()
allocates a fresh Cursor for the reset
statement.
Note that the returned cursor is positioned before the first row and an
attempt to get the current row will fail. Navigate to the first row through
Cursor.first()
or Cursor.next()
methods.
DatabaseException
Statement.execute()
void bind(int index, int value) throws DatabaseException, DatabaseBindingException
index
- Index of the parameter.value
- The value to bind.
DatabaseBindingException
- If binding failed.
DatabaseException
- If a statement has not been prepared or is closed, or if the database is closed.void bind(int index, long value) throws DatabaseException, DatabaseBindingException
index
- Index of the parameter.value
- The value to bind.
DatabaseBindingException
- If binding failed.
DatabaseException
- If a statement has not been prepared or is closed, or if the database is closed.void bind(int index, float value) throws DatabaseException, DatabaseBindingException
index
- Index of the parameter.value
- The value to bind.
DatabaseBindingException
- If binding failed.
DatabaseException
- If a statement has not been prepared or is closed, or if the database is closed.void bind(int index, double value) throws DatabaseException, DatabaseBindingException
index
- Index of the parameter.value
- The value to bind.
DatabaseBindingException
- If binding failed.
DatabaseException
- If a statement has not been prepared or is closed, or if the
database is closed.void bind(int index, short value) throws DatabaseException, DatabaseBindingException
index
- Index of the parameter.value
- The value to bind.
DatabaseBindingException
- If binding failed.
DatabaseException
- If a statement has not been prepared or is closed, or if the database is closed.void bind(int index, byte value) throws DatabaseException, DatabaseBindingException
index
- Index of the parameter.value
- The value to bind.
DatabaseBindingException
- If binding failed.
DatabaseException
- If a statement has not been prepared or is closed, or if the database is closed.void bind(int index, boolean value) throws DatabaseException, DatabaseBindingException
true
is bound as 1,
and false
is bound as 0.
index
- Index of the parameter.value
- The value to bind.
DatabaseBindingException
- If binding failed.
DatabaseException
- If a statement has not been prepared or is closed, or if the database is closed.void bind(int index, String value) throws DatabaseException, DatabaseBindingException
index
- Index of the parameter.value
- The value to bind (null is also allowed).
DatabaseBindingException
- If binding failed.
DatabaseException
- If a statement has not been prepared or is closed, or if the database is closed.void bind(int index, byte[] value) throws DatabaseException, DatabaseBindingException
index
- Index of the parameter.value
- The value to bind. NULL can also be bound.
DatabaseBindingException
- If binding failed.
DatabaseException
- If a statement has not been prepared or is closed, or if the database is closed.void bind(int index, byte[] value, int offset) throws DatabaseException, DatabaseBindingException
index
- Index of the parameter.value
- The value to bind. NULL can also be bound.offset
- The offset from which to bind value[].
DatabaseBindingException
- If binding failed
DatabaseException
- If a statement has not been prepared or is closed, or if the database is closed.void bind(int index, byte[] value, int offset, int length) throws DatabaseException, DatabaseBindingException
index
- Index of the parameter.value
- The value to bind. NULL can also be bound.offset
- The offset from which to bind value[]
.length
- The number of bytes to take from value[]
.
DatabaseBindingException
- If binding failed.
DatabaseException
- If a statement has not been prepared or is closed, or if the database is closed.void reset() throws DatabaseException
Statement.prepare()
.
Also clears all bindings.
After a reset, Statement.getCursor()
must be called to get a new Cursor.
DatabaseException
void rewind() throws DatabaseException
Statement.prepare()
.
Does not clear any bindings.
DatabaseException
- After a rewind, Statement.getCursor()
must be called to get a new Cursor.void close() throws DatabaseException
close()
, any cursors based on
this statement will fail.
DatabaseException
int getFormalIndex(String paramName) throws DatabaseException, DatabaseBindingException
bind()
calls.
DatabaseBindingException
- If no matching parameter is found.
DatabaseException
- If a statement has not been prepared or is closed.String getFormalName(int index) throws DatabaseException, DatabaseBindingException
For getFormalName()
to return the parameter name, you must provide a name in the query.
For example, when you call getFormalName
, the statement "SELECT * FROM T WHERE a = :a"
will
return :a
.
When parameters such as a question mark (?
) are used as placeholders, the getFormalName()
method will not return a parameter name.
For example, getFormalName
will not return the name for the parameter in this statement:
"SELECT * FROM T WHERE a = ?"
DatabaseBindingException
- If no matching
parameter is found, or if the parameter with the given index is
an anonymous parameter.
DatabaseException
- If a statement has not been prepared or is closed.String[] getColumnNames() throws DatabaseException
DatabaseException
- If a statement has not been prepared or is closed.int getParameterCount() throws DatabaseException
The SQL parameters can be numbered arbitrarily if the ?NNN notation is used, in which case gaps might exist in the parameter list.
DatabaseException
- If a statement has not been prepared or is closed.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.