QueryBuilder

java.lang.Object
- net.zer0bandwidth.android.lib.database.querybuilder.QueryBuilder<I,R>

Type Parameters:

I - The implementation class which extends QueryBuilder. This is set explicitly in the declaration of the implementation class, and allows the superclass to provide concrete implementations of shared methods.

R - The return type of the underlying SQLiteDatabase function. This is set explicitly in the declaration of the implementation class, and will be the return type of execute() and executeOn(android.database.sqlite.SQLiteDatabase).

Direct Known Subclasses:

DeletionBuilder, InsertionBuilder, SelectionBuilder, UpdateBuilder
```
public abstract class QueryBuilder<I extends QueryBuilder,R>
extends java.lang.Object
```
Builds a SQLite query using methods, rather than the methods from the SQLiteDatabase methods that use long lists of parameters.
This class is supposed to do very little; the consumer should use the static methods insertInto(java.lang.String), update(java.lang.String), selectFrom(java.lang.String), and deleteFrom(java.lang.String) to spawn instances of the various implementation classes corresponding to database actions (INSERT, UPDATE, SELECT, and DELETE).

In its initial implementation, the class provides methods to set an explicit format string and parameter list for the WHERE clause, similar to the syntax used by the various Android functions in SQLiteDatabase. In the future, the API of this class will be extended to provide a grammar for constructing the conditional statement through builder methods.

The class builds on the foundation of SQLitePortal and derives several of its static constants and design decisions from features of that class.

Since:

zer0bandwidth-net/android 0.1.1 (#20)

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`QueryBuilder.UnboundException` Informs a consumer that the builder's `execute()` method was invoked while the builder was not bound to a target database instance.

Field Summary

Fields
Modifier and Type	Field and Description
`protected java.lang.String[]`	`m_asExplicitWhereParams` A substitute, explicit list of parameters for the `WHERE` clause format specified in `m_sExplicitWhereFormat`.
`protected android.database.sqlite.SQLiteDatabase`	`m_dbTarget` A persistent binding to a specific database, used by `execute()`.
`protected java.lang.String`	`m_sExplicitWhereFormat` A substitute, explicit format string for a `WHERE` clause, for which `m_asExplicitWhereParams` provides the values.
`protected java.lang.String`	`m_sTableName` The name of the table on which the query will operate.
`protected android.content.ContentValues`	`m_valsToWrite` For `INSERT` and `DELETE` operations, these are the values to be written.

Constructor Summary

Constructors
Constructor and Description

QueryBuilder(java.lang.String sTableName)
Superclass's constructor, which initializes the shared member fields.

Constructors
Constructor and Description
`QueryBuilder(java.lang.String sTableName)` Superclass's constructor, which initializes the shared member fields.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`static DeletionBuilder`	`deleteFrom(android.database.sqlite.SQLiteDatabase db, java.lang.String sTableName)` Kicks off construction of a `DELETE` query, bound to a specific database instance.
`static DeletionBuilder`	`deleteFrom(java.lang.String sTableName)` Kicks off construction of a `DELETE` query.
`R`	`execute()` Executes the query that has been built by the implementation class, on the database instance to which the builder has been bound, either by a constructor, or by `onDatabase(android.database.sqlite.SQLiteDatabase)`.
`abstract R`	`executeOn(android.database.sqlite.SQLiteDatabase db)` Executes the query that has been built by the implementation class.
`protected java.lang.String`	`getWhereClause()` Creates a raw SQLite `WHERE` clause based on the format and params created for the instance.
`protected java.lang.String`	`getWhereFormat()` Creates the Android `WHERE` clause template to be passed to a `SQLiteDatabase` function.
`protected java.lang.String[]`	`getWhereParams()` Creates the array of `WHERE` clause value substitutions to be passed to a `SQLiteDatabase` function.
`static InsertionBuilder`	`insertInto(android.database.sqlite.SQLiteDatabase db, java.lang.String sTableName)` Kicks off construction of an `INSERT` query, bound to a specific database instance.
`static InsertionBuilder`	`insertInto(java.lang.String sTableName)` Kicks off construction of an `INSERT` query.
`I`	`onDatabase(android.database.sqlite.SQLiteDatabase db)` Binds the builder to a specific database instance, to be used by `execute()`.
`static SelectionBuilder`	`selectFrom(android.database.sqlite.SQLiteDatabase db, java.lang.String sTableName)` Kicks off construction of a `SELECT` query, bound to a specific database instance.
`static SelectionBuilder`	`selectFrom(java.lang.String sTableName)` Kicks off construction of a `SELECT` query.
`protected I`	`setTableName(java.lang.String sTableName)` Sets the table name in which the query will be executed.
`I`	`setValues(android.content.ContentValues vals)` Sets values to be written as part of an `INSERT` or `UPDATE` query.
`static java.lang.String`	`toSQLInputParams(android.content.ContentValues vals)` Renders the key/value pairs in a set of `ContentValues` as a list of input parameters to an SQL `INSERT` or `UPDATE` query's `SET` clause.
`static UpdateBuilder`	`update(android.database.sqlite.SQLiteDatabase db, java.lang.String sTableName)` Kicks off construction of an `UPDATE` query, bound to a specific database instance.
`static UpdateBuilder`	`update(java.lang.String sTableName)` Kicks off construction of an `UPDATE` query.
`I`	`where(java.lang.String sWhereClause)` Constructs an explicit `WHERE` clause for the query.
`I`	`where(java.lang.String sWhereFormat, java.util.Collection<java.lang.String> asWhereParams)` Constructs an explicit `WHERE` clause for the query.
`I`	`where(java.lang.String sWhereFormat, java.lang.String... asWhereParams)` Constructs an explicit `WHERE` clause for the query.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - m_sTableName
```
protected java.lang.String m_sTableName
```
    The name of the table on which the query will operate.
  - m_valsToWrite
```
protected android.content.ContentValues m_valsToWrite
```
    For INSERT and DELETE operations, these are the values to be written.
  - m_sExplicitWhereFormat
```
protected java.lang.String m_sExplicitWhereFormat
```
    A substitute, explicit format string for a WHERE clause, for which m_asExplicitWhereParams provides the values.
  - m_asExplicitWhereParams
```
protected java.lang.String[] m_asExplicitWhereParams
```
    A substitute, explicit list of parameters for the WHERE clause format specified in m_sExplicitWhereFormat.
  - m_dbTarget
```
protected android.database.sqlite.SQLiteDatabase m_dbTarget
```
    A persistent binding to a specific database, used by execute().
    
    Since:
    
    zer0bandwidth-net/android 0.1.4 (#37)
- Constructor Detail
  - QueryBuilder
```
public QueryBuilder(java.lang.String sTableName)
```
    Superclass's constructor, which initializes the shared member fields.
    
    Parameters:
    
    sTableName - the name of the table on which the query will be performed
- Method Detail
  - insertInto
```
public static InsertionBuilder insertInto(java.lang.String sTableName)
```
    Kicks off construction of an INSERT query.
    
    Parameters:
    
    sTableName - the name of the table into which rows will be inserted
    
    Returns:
    
    an instance of a builder that can handle insertion queries
  - insertInto
```
public static InsertionBuilder insertInto(android.database.sqlite.SQLiteDatabase db,
                                          java.lang.String sTableName)
```
    Kicks off construction of an INSERT query, bound to a specific database instance.
    
    Parameters:
    
    db - the database on which the query should be executed
    
    sTableName - the name of the table into which rows will be inserted
    
    Returns:
    
    an instance of a builder that can handle insertion queries
    
    Since:
    
    zer0bandwidth-net/android 0.1.4 (#37)
  - update
```
public static UpdateBuilder update(java.lang.String sTableName)
```
    Kicks off construction of an UPDATE query.
    
    Parameters:
    
    sTableName - the name of the table in which rows will be updated
    
    Returns:
    
    an instance of a builder that can handle update queries
  - update
```
public static UpdateBuilder update(android.database.sqlite.SQLiteDatabase db,
                                   java.lang.String sTableName)
```
    Kicks off construction of an UPDATE query, bound to a specific database instance.
    
    Parameters:
    
    db - the database on which the query should be executed
    
    sTableName - the name of the table in which rows will be updated
    
    Returns:
    
    an instance of a builder that can handle update queries
    
    Since:
    
    zer0bandwidth-net/android 0.1.4 (#37)
  - selectFrom
```
public static SelectionBuilder selectFrom(java.lang.String sTableName)
```
    Kicks off construction of a SELECT query.
    
    Parameters:
    
    sTableName - the name of the table from which rows will be selected
    
    Returns:
    
    an instance of a builder that can handle selection queries
  - selectFrom
```
public static SelectionBuilder selectFrom(android.database.sqlite.SQLiteDatabase db,
                                          java.lang.String sTableName)
```
    Kicks off construction of a SELECT query, bound to a specific database instance.
    
    Parameters:
    
    db - the database on which the query should be executed
    
    sTableName - the name of the table from which rows will be selected
    
    Returns:
    
    an instance of a builder that can handle selection queries
    
    Since:
    
    zer0bandwidth-net/android 0.1.4 (#37)
  - deleteFrom
```
public static DeletionBuilder deleteFrom(java.lang.String sTableName)
```
    Kicks off construction of a DELETE query.
    
    Parameters:
    
    sTableName - the name of the table from which rows will be deleted
    
    Returns:
    
    an instance of a builder that can handle deletion queries
  - deleteFrom
```
public static DeletionBuilder deleteFrom(android.database.sqlite.SQLiteDatabase db,
                                         java.lang.String sTableName)
```
    Kicks off construction of a DELETE query, bound to a specific database instance.
    
    Parameters:
    
    db - the database on which the query should be executed
    
    sTableName - the name of the table from which rows will be deleted
    
    Returns:
    
    an instance of a builder that can handle deletion queries
    
    Since:
    
    zer0bandwidth-net/android 0.1.4 (#37)
  - toSQLInputParams
```
public static java.lang.String toSQLInputParams(android.content.ContentValues vals)
```
    Renders the key/value pairs in a set of ContentValues as a list of input parameters to an SQL INSERT or UPDATE query's SET clause. So that the fields always appear in consistent order (rather than by hash code), the method will sort lexically by key before rendering the output string.
    
    Parameters:
    
    vals - the key/value pairs to be rendered
    
    Returns:
    
    an SQL SET clause body
  - onDatabase
```
public I onDatabase(android.database.sqlite.SQLiteDatabase db)
```
    Binds the builder to a specific database instance, to be used by execute().
    
    Parameters:
    
    db - the database instance on which the query should be executed
    
    Returns:
    
    (fluid)
    
    Since:
    
    zer0bandwidth-net/android 0.1.4 (#37)
  - setTableName
```
protected I setTableName(java.lang.String sTableName)
```
    Sets the table name in which the query will be executed.
    
    Parameters:
    
    sTableName - the name of the table
    
    Returns:
    
    (fluid)
  - setValues
```
public I setValues(android.content.ContentValues vals)
```
    Sets values to be written as part of an INSERT or UPDATE query.
    
    Parameters:
    
    vals - the values to be written
    
    Returns:
    
    (fluid)
  - where
```
public I where(java.lang.String sWhereClause)
```
    Constructs an explicit WHERE clause for the query. The supplied string is used as a format string for the WHERE clause and should contain no variable substitutions. The collection of variable values will be set to null by this method, based on this assumption.
    
    Parameters:
    
    sWhereClause - the explicit WHERE clause, containing no variable substitution placeholders
    
    Returns:
    
    (fluid)
  - where
```
public I where(java.lang.String sWhereFormat,
               java.lang.String... asWhereParams)
```
    Constructs an explicit WHERE clause for the query.
    
    Parameters:
    
    sWhereFormat - the format string for the WHERE clause; uses ? for parameter substitution
    
    asWhereParams - the parameters for the WHERE clause
    
    Returns:
    
    (fluid)
  - where
```
public I where(java.lang.String sWhereFormat,
               java.util.Collection<java.lang.String> asWhereParams)
```
    Constructs an explicit WHERE clause for the query.
    
    Parameters:
    
    sWhereFormat - the format string for the WHERE clause; uses ? for parameter substitution
    
    asWhereParams - the parameters for the WHERE clause
    
    Returns:
    
    (fluid)
  - getWhereFormat
```
protected java.lang.String getWhereFormat()
```
    Creates the Android WHERE clause template to be passed to a SQLiteDatabase function.
    
    Returns:
    
    the WHERE clause template
  - getWhereParams
```
protected java.lang.String[] getWhereParams()
```
    Creates the array of WHERE clause value substitutions to be passed to a SQLiteDatabase function.
    
    Returns:
    
    the WHERE clause template parameters
  - getWhereClause
```
protected java.lang.String getWhereClause()
```
    Creates a raw SQLite WHERE clause based on the format and params created for the instance.
    
    Returns:
    
    a raw WHERE clause
  - executeOn
```
public abstract R executeOn(android.database.sqlite.SQLiteDatabase db)
```
    Executes the query that has been built by the implementation class.
    
    Parameters:
    
    db - the database instance on which the query should be executed.
    
    Returns:
    
    the usual return value of the underlying method
  - execute
```
public final R execute()
                throws QueryBuilder.UnboundException
```
    Executes the query that has been built by the implementation class, on the database instance to which the builder has been bound, either by a constructor, or by onDatabase(android.database.sqlite.SQLiteDatabase).
    
    Returns:
    
    the usual return value of the underlying method
    
    Throws:
    
    QueryBuilder.UnboundException - if the builder is not yet bound to a database instance
    
    Since:
    
    zer0bandwidth-net/android 0.1.4 (#37)

Class QueryBuilder<I extends QueryBuilder,R>

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

m_sTableName

m_valsToWrite

m_sExplicitWhereFormat

m_asExplicitWhereParams

m_dbTarget

Constructor Detail

QueryBuilder

Method Detail

insertInto

insertInto

update

update

selectFrom

selectFrom

deleteFrom

deleteFrom

toSQLInputParams

onDatabase

setTableName

setValues

where

where

where

getWhereFormat

getWhereParams

getWhereClause

executeOn

execute