Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

net.rim.device.api.database
Interface Statement

public interface Statement

The representation of a SQL statement. Here is the lifecycle of a statement:

  1. Creation: via Database.createStatement(String)
  2. Preparation: via Statement.prepare()
  3. Binding: of any formal parameters in the statement to actuals via Statement.bind(int, int) and associated methods, starting from 1 for the first formal.
  4. Query execution: via Statement.getCursor(), which returns a Cursor; or update execution: via Statement.execute().

Using SQL parameters and bind

SQL parameters allow the same statement to be re-used with different literal values in each execution. Using 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 = ?"

Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

Method Summary
Category: Signed  void bind(int index, boolean value)
          Binds a Boolean parameter in the statement.
Category: Signed  void bind(int index, byte value)
          Binds a byte parameter in the statement.
Category: Signed  void bind(int index, byte[] value)
          Binds a byte[] parameter in the statement.
Category: Signed  void bind(int index, byte[] value, int offset)
          Binds a byte[] parameter in the statement.
Category: Signed  void bind(int index, byte[] value, int offset, int length)
          Binds a byte[] parameter in the statement.
Category: Signed  void bind(int index, double value)
          Binds a double parameter in the statement.
Category: Signed  void bind(int index, float value)
          Binds a float parameter in the statement.
Category: Signed  void bind(int index, int value)
          Binds an integer parameter in the statement.
Category: Signed  void bind(int index, String value)
          Binds a String parameter in the statement.
Category: Signed  void bind(int index, long value)
          Binds a long parameter in the statement.
Category: Signed  void bind(int index, short value)
          Binds a short parameter in the statement.
Category: Signed  void close()
          Closes the current statement and releases all resources.
Category: Signed  void execute()
          Executes an UPDATE statement.
Category: Signed  String[] getColumnNames()
          Gets the names of the columns of this statement.
Category: Signed  Cursor getCursor()
          Executes a query statement and returns a cursor with selected rows.
Category: Signed  int getFormalIndex(String paramName)
          Converts the named SQL parameter into a parameter index that can be used in bind() calls.
Category: Signed  String getFormalName(int index)
          Converts a parameter index to a SQL parameter name.
Category: Signed  int getParameterCount()
          Returns the largest index of all SQL parameters in a statement, or 0 if there are no SQL parameters.
Category: Signed  String getTail()
          Gets the unparsed portion of a prepared statement (the "tail"); this method is applicable for multiple statements separated by semicolons (;).
Category: Signed  void prepare()
          Prepares a statement for execution.
Category: Signed  void reset()
          Resets a Statement to its state just after Statement.prepare().
Category: Signed  void rewind()
           Rewinds a Statement to its state just after Statement.prepare().
 



Method Detail

prepare

void prepare()
             throws DatabaseException
Prepares a statement for execution.

Throws:
DatabaseException - Database is closed or a SQL statement has already been prepared.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

getTail

String getTail()
               throws DatabaseException
Gets the unparsed portion of a prepared statement (the "tail"); this method is applicable for multiple statements separated by semicolons (;).

Throws:
DatabaseException - If the database is closed or the statement has not been prepared.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

execute

void execute()
             throws DatabaseException
Executes an UPDATE statement.

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.

Throws:
DatabaseException
See Also:
Statement.getCursor()
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

getCursor

Cursor getCursor()
                 throws DatabaseException
Executes a query statement and returns a cursor with selected rows.

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.

Returns:
A Cursor to iterate over results from execution.
Throws:
DatabaseException
See Also:
Statement.execute()
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

bind

void bind(int index,
          int value)
          throws DatabaseException,
                 DatabaseBindingException
Binds an integer parameter in the statement.

Parameters:
index - Index of the parameter.
value - The value to bind.
Throws:
DatabaseBindingException - If binding failed.
DatabaseException - If a statement has not been prepared or is closed, or if the database is closed.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

bind

void bind(int index,
          long value)
          throws DatabaseException,
                 DatabaseBindingException
Binds a long parameter in the statement.

Parameters:
index - Index of the parameter.
value - The value to bind.
Throws:
DatabaseBindingException - If binding failed.
DatabaseException - If a statement has not been prepared or is closed, or if the database is closed.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

bind

void bind(int index,
          float value)
          throws DatabaseException,
                 DatabaseBindingException
Binds a float parameter in the statement.

Parameters:
index - Index of the parameter.
value - The value to bind.
Throws:
DatabaseBindingException - If binding failed.
DatabaseException - If a statement has not been prepared or is closed, or if the database is closed.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

bind

void bind(int index,
          double value)
          throws DatabaseException,
                 DatabaseBindingException
Binds a double parameter in the statement.

Parameters:
index - Index of the parameter.
value - The value to bind.
Throws:
DatabaseBindingException - If binding failed.
DatabaseException - If a statement has not been prepared or is closed, or if the database is closed.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

bind

void bind(int index,
          short value)
          throws DatabaseException,
                 DatabaseBindingException
Binds a short parameter in the statement.

Parameters:
index - Index of the parameter.
value - The value to bind.
Throws:
DatabaseBindingException - If binding failed.
DatabaseException - If a statement has not been prepared or is closed, or if the database is closed.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

bind

void bind(int index,
          byte value)
          throws DatabaseException,
                 DatabaseBindingException
Binds a byte parameter in the statement.

Parameters:
index - Index of the parameter.
value - The value to bind.
Throws:
DatabaseBindingException - If binding failed.
DatabaseException - If a statement has not been prepared or is closed, or if the database is closed.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

bind

void bind(int index,
          boolean value)
          throws DatabaseException,
                 DatabaseBindingException
Binds a Boolean parameter in the statement. true is bound as 1, and false is bound as 0.

Parameters:
index - Index of the parameter.
value - The value to bind.
Throws:
DatabaseBindingException - If binding failed.
DatabaseException - If a statement has not been prepared or is closed, or if the database is closed.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

bind

void bind(int index,
          String value)
          throws DatabaseException,
                 DatabaseBindingException
Binds a String parameter in the statement.

Parameters:
index - Index of the parameter.
value - The value to bind (null is also allowed).
Throws:
DatabaseBindingException - If binding failed.
DatabaseException - If a statement has not been prepared or is closed, or if the database is closed.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

bind

void bind(int index,
          byte[] value)
          throws DatabaseException,
                 DatabaseBindingException
Binds a byte[] parameter in the statement.

Parameters:
index - Index of the parameter.
value - The value to bind. NULL can also be bound.
Throws:
DatabaseBindingException - If binding failed.
DatabaseException - If a statement has not been prepared or is closed, or if the database is closed.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

bind

void bind(int index,
          byte[] value,
          int offset)
          throws DatabaseException,
                 DatabaseBindingException
Binds a byte[] parameter in the statement.

Parameters:
index - Index of the parameter.
value - The value to bind. NULL can also be bound.
offset - The offset from which to bind value[].
Throws:
DatabaseBindingException - If binding failed
DatabaseException - If a statement has not been prepared or is closed, or if the database is closed.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

bind

void bind(int index,
          byte[] value,
          int offset,
          int length)
          throws DatabaseException,
                 DatabaseBindingException
Binds a byte[] parameter in the statement.

Parameters:
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[].
Throws:
DatabaseBindingException - If binding failed.
DatabaseException - If a statement has not been prepared or is closed, or if the database is closed.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

reset

void reset()
           throws DatabaseException
Resets a Statement to its state just after Statement.prepare(). Also clears all bindings. After a reset, Statement.getCursor() must be called to get a new Cursor.

Throws:
DatabaseException
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

rewind

void rewind()
            throws DatabaseException
Rewinds a Statement to its state just after Statement.prepare(). Does not clear any bindings.

Throws:
DatabaseException - After a rewind, Statement.getCursor() must be called to get a new Cursor.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

close

void close()
           throws DatabaseException
Closes the current statement and releases all resources. After a call to close(), any cursors based on this statement will fail.

Throws:
DatabaseException
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

getFormalIndex

int getFormalIndex(String paramName)
                   throws DatabaseException,
                          DatabaseBindingException
Converts the named SQL parameter into a parameter index that can be used in bind() calls.

Throws:
DatabaseBindingException - If no matching parameter is found.
DatabaseException - If a statement has not been prepared or is closed.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

getFormalName

String getFormalName(int index)
                     throws DatabaseException,
                            DatabaseBindingException
Converts a parameter index to a SQL parameter name.

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 = ?"

Throws:
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.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

getColumnNames

String[] getColumnNames()
                        throws DatabaseException
Gets the names of the columns of this statement. This method returns column names of SELECT statements.

Throws:
DatabaseException - If a statement has not been prepared or is closed.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

getParameterCount

int getParameterCount()
                      throws DatabaseException
Returns the largest index of all SQL parameters in a statement, or 0 if there are no SQL parameters.

The SQL parameters can be numbered arbitrarily if the ?NNN notation is used, in which case gaps might exist in the parameter list.

Throws:
DatabaseException - If a statement has not been prepared or is closed.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0



Overview  Package   Class  Tree  Deprecated  Index  Help 
 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.