net.rim.device.api.database
Interface Statement


public interface Statement

The representation of a SQL statement. The lifecycle of a statement:

  1. Creation: via Database.createStatement(String)
  2. Preparation: via Statement.prepare()
  3. Bind: 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
  5. Update Execution: via Statement.execute()()
Notes on SQL parameters and bind(): Here's an example of a statement using parameters.
 // Create a selection statement with the bounds left as sequentially assigned parameters  
 Statement s = "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 may be used with explicitly numbered values as well:
 Statement s = "SELECT * FROM T WHERE a < ?5 AND a > ?12";
 
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.
 
 When parameters are used such as '?' to be a placeholder, the getFormalName() method will not return a parameter name.
 For example: "SELECT * FROM T WHERE a = ?" will not return the parameter name for "a".
 
 It is necessary to provide a name in the query for getFormalName to return the parameter name.
 For example: "SELECT * FROM T WHERE a = :a" will return ":a" when calling getFormalName(1);

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, releases all resources.
Category: Signed  void execute()
          Executes an update statement.
Category: Signed  String[] getColumnNames()
          Get the names of the columns of this statement.
Category: Signed  Cursor getCursor()
          Executes query statement and returns cursor with selected rows.
Category: Signed  int getFormalIndex(String paramName)
          Convert the named sql parameter into a parameter index that can be used in bind() calls.
Category: Signed  String getFormalName(int index)
          Convert a parameter index to a sql parameter name.
Category: Signed  int getParameterCount()
          Return the largest index of all sql parameters in a statement or 0 if no SQL parameters.
Category: Signed  String getTail()
          Get unparsed portion of a prepared statement -- the "tail".
Category: Signed  void prepare()
          Prepare a statement for execution
Category: Signed  void reset()
          Resets Statement to its state just after prepare().
Category: Signed  void rewind()
           Rewind Statement to its state just after prepare().
 



Method Detail

prepare

void prepare()
             throws DatabaseException
Prepare a statement for execution

Throws:
DatabaseException - - database is closed/null 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
Get unparsed portion of a prepared statement -- the "tail". Applicable for multiple statements separated by ";"

Throws:
DatabaseException - - database is closed/null 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 'update' type statements that do not return result set. These include INSERT, UPDATE, DELETE and similar sql statements.

Only the first call to this method performs data updates. Subsequent calls will be 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 query statement and returns cursor with selected rows.

This method should be called only with SELECT type statements that return row set.

The first call to getCursor() creates a Cursor. Each subsequent call to getCursor() 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 returned cursor is positioned before the first row and any attempts to get current row would 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 - - thrown when binding failed
DatabaseException - - thrown if an statement is unprepared (or closed), or the database is null (or 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 - - thrown when binding failed
DatabaseException - - thrown if an statement is unprepared (or closed), or the database is null (or 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 - - thrown when binding failed
DatabaseException - - thrown if an statement is unprepared (or closed), or the database is null (or 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 - - thrown when binding failed
DatabaseException - - thrown if an statement is unprepared (or closed), or the database is null (or 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 - - thrown when binding failed
DatabaseException - - thrown if an statement is unprepared (or closed), or the database is null (or 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 - - thrown when binding failed
DatabaseException - - thrown if an statement is unprepared (or closed), or the database is null (or 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 as 0.

Parameters:
index - Index of the parameter.
value - The value to bind.
Throws:
DatabaseBindingException - - thrown when binding failed
DatabaseException - - thrown if an statement is unprepared (or closed), or the database is null (or 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 - - thrown when binding failed
DatabaseException - - thrown if an statement is unprepared (or closed), or the database is null (or 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 - - thrown when binding failed
DatabaseException - - thrown if an statement is unprepared (or closed), or the database is null (or 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 - - thrown when binding failed
DatabaseException - - thrown if an statement is unprepared (or closed), or the database is null (or 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 - - thrown when binding failed
DatabaseException - - thrown if an statement is unprepared (or closed), or the database is null (or 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 Statement to its state just after 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
Rewind Statement to its state just after 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, releases all resources. Any cursors based on this statement will fail after a call to Statement.close().

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
Convert the named sql parameter into a parameter index that can be used in bind() calls.

Throws:
DatabaseBindingException - - thrown when no matching parameter is found
DatabaseException - - thrown if an statement is unprepared or 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
Convert a parameter index to a sql parameter name.

Throws:
DatabaseBindingException - - thrown when no matching parameter is found, or if the parameter with the given index is an anonymous parameter.
DatabaseException - - thrown if an statement is unprepared or 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
Get the names of the columns of this statement. This method returns column names of SELECT statements.

Throws:
DatabaseException - - thrown if an statement is unprepared or 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
Return the largest index of all sql parameters in a statement or 0 if no SQL parameters.

Note that 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 - - thrown if an statement is unprepared or 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





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.