net.zer0bandwidth.android.lib.content.querybuilder

Class QueryBuilder<I extends QueryBuilder,R>

java.lang.Object

net.zer0bandwidth.android.lib.content.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 methods reusable by the descendants.

R - The return type of the execute() method, which corresponds to a method in ContentResolver.

Direct Known Subclasses:

DeletionBuilder, InsertionBuilder, SelectionBuilder, UpdateBuilder

public abstract class QueryBuilder<I extends QueryBuilder,R>
extends java.lang.Object

Builds a ContentResolver query using builder-style methods, rather than the standard methods, which use long lists of often-null parameters.

This class is supposed to do very little; the consumer should use the static methods insertInto(android.content.ContentResolver, android.net.Uri), update(), selectFrom(android.content.ContentResolver, android.net.Uri), and deleteFrom(android.content.ContentResolver, android.net.Uri) to spawn instances of the various implementation classes corresponding to query actions.

Since:

zer0bandwidth-net/android 0.1.7 (#39)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	QueryBuilder.ExecutionException Exception thrown by execute() and executeOn(android.content.ContentResolver, android.net.Uri) when the underlying ContentResolver query operation fails.
static class	QueryBuilder.UnboundException Informs a consumer of QueryBuilder that it has tried to invoke the execute() method without first binding to a data source.

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String[]	m_asExplicitWhereParams A substitute, explicit list of "where" parameters, to fit the format string stored in m_sExplicitWhereFormat.
protected android.content.ContentResolver	m_rslv The ContentResolver to which the builder is bound.
protected java.lang.String	m_sExplicitWhereFormat A substitute, explicit "where" format string, for which m_asExplicitWhereParams provides the values.
protected android.net.Uri	m_uri The Uri to be supplied to the ContentResolver.
protected android.content.ContentValues	m_valsToWrite For "insert" and "update" operations, these are the values to be written.

Constructor Summary

Constructors

Constructor and Description
QueryBuilder() The default constructor; does not bind to a particular data source.
QueryBuilder(android.content.ContentResolver rslv, android.net.Uri uri) A shared constructor which binds the builder to a specific resolver and URI.
QueryBuilder(android.content.Context ctx, android.net.Uri uri) A shared constructor which binds the builder to a the resolver found in the given context, and the specified URI.

Method Summary

Modifier and Type	Method and Description
static DeletionBuilder	delete() Kicks off construction of a deletion query.
static DeletionBuilder	deleteFrom(android.content.ContentResolver rslv, android.net.Uri uri) Kicks off construction of a deletion query.
static DeletionBuilder	deleteFrom(android.content.Context ctx, android.net.Uri uri) Kicks off construction of a deletion query.
R	execute() Executes the query that has been built by the implementation class, using the ContentResolver and Uri to which the builder has been bound, either by the constructor, or by an invocation of onDataSource(android.content.ContentResolver, android.net.Uri).
R	executeOn(android.content.ContentResolver rslv, android.net.Uri uri) Executes the query that has been built by the implementation class, using the supplied ContentResolver and Uri.
R	executeOn(android.content.Context ctx, android.net.Uri uri) Executes the query that has been built by the implementation class, using the ContentResolver provided by the specified Context, and the specified Uri.
protected abstract R	executeQuery(android.content.ContentResolver rslv, android.net.Uri uri) Consumed by execute() and executeOn(android.content.ContentResolver, android.net.Uri) to actually carry out the operation.
protected static android.content.ContentResolver	getContentResolver(android.content.Context ctx) Obtains a ContentResolver from the specified context, throwing an exception if that context is null.
protected java.lang.String	getWhereFormat() Creates the Android "where" clause format string to be passed to a ContentResolver query method.
protected java.lang.String[]	getWhereParams() Creates the array of "where" clause value substitutions to be passed to a ContentResolver query method.
static InsertionBuilder	insert() Kicks off construction of an insertion query.
static InsertionBuilder	insertInto(android.content.ContentResolver rslv, android.net.Uri uri) Kicks off construction of an insertion query.
static InsertionBuilder	insertInto(android.content.Context ctx, android.net.Uri uri) Kicks off construction of an insertion query.
I	onDataSource(android.content.ContentResolver rslv, android.net.Uri uri) Binds the builder to a specific data context, to be used by the execution methods.
I	onDataSource(android.content.Context ctx, android.net.Uri uri) Binds the builder to a specific data context, to be used by the execution methods.
static SelectionBuilder	select() Kicks off construction of a selection query.
static SelectionBuilder	selectFrom(android.content.ContentResolver rslv, android.net.Uri uri) Kicks off construction of a selection query.
static SelectionBuilder	selectFrom(android.content.Context ctx, android.net.Uri uri) Kicks off construction of a selection query.
I	setValues(android.content.ContentValues vals) Sets values to be written as part of an "insert" or "update" operation, if applicable.
static UpdateBuilder	update() Kicks off construction of an update query.
static UpdateBuilder	update(android.content.ContentResolver rslv, android.net.Uri uri) Kicks off construction of an update query.
static UpdateBuilder	update(android.content.Context ctx, android.net.Uri uri) Kicks off construction of an update query.
protected static void	validateDataContextBinding(android.content.ContentResolver rslv, android.net.Uri uri) Ensures that the specified ContentResolver and Uri are non-null and usable as a data context.
I	where(java.lang.String sWhereClause) Constructs an explicit "where" clause for a query.
I	where(java.lang.String sWhereFormat, java.util.Collection<java.lang.String> asWhereParams) Sets the "where" clause format and values for a query.
I	where(java.lang.String sWhereFormat, java.lang.String... asWhereParams) Sets the "where" clause format and values for a query.

Methods inherited from class java.lang.Object

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

Field Detail

m_rslv

protected android.content.ContentResolver m_rslv

The ContentResolver to which the builder is bound.

m_uri

protected android.net.Uri m_uri

The Uri to be supplied to the ContentResolver.

m_valsToWrite

protected android.content.ContentValues m_valsToWrite

For "insert" and "update" operations, these are the values to be written.

m_sExplicitWhereFormat

protected java.lang.String m_sExplicitWhereFormat

A substitute, explicit "where" format string, for which m_asExplicitWhereParams provides the values.

m_asExplicitWhereParams

protected java.lang.String[] m_asExplicitWhereParams

A substitute, explicit list of "where" parameters, to fit the format string stored in m_sExplicitWhereFormat.

Constructor Detail

QueryBuilder

public QueryBuilder()

The default constructor; does not bind to a particular data source.

QueryBuilder

public QueryBuilder(android.content.Context ctx,
                    android.net.Uri uri)
             throws QueryBuilder.UnboundException

A shared constructor which binds the builder to a the resolver found in the given context, and the specified URI.

Parameters:

ctx - a context which can provide a ContentResolver

uri - the URI at which the query should be executed

Throws:

QueryBuilder.UnboundException - if either parameter is unusable

QueryBuilder

public QueryBuilder(android.content.ContentResolver rslv,
                    android.net.Uri uri)
             throws QueryBuilder.UnboundException

A shared constructor which binds the builder to a specific resolver and URI.

Parameters:

rslv - the resolver through which the query should be executed

uri - the URI at which the query should be executed

Throws:

QueryBuilder.UnboundException - if either parameter is unusable

Method Detail

insert

public static InsertionBuilder insert()

Kicks off construction of an insertion query. When constructing the builder in this way, the caller must also call onDataSource(android.content.ContentResolver, android.net.Uri), or use executeOn(android.content.ContentResolver, android.net.Uri) instead of execute().

Returns:

an instance of the builder that handles insertion queries

insertInto

public static InsertionBuilder insertInto(android.content.ContentResolver rslv,
                                          android.net.Uri uri)
                                   throws QueryBuilder.UnboundException

Kicks off construction of an insertion query.

Parameters:

rslv - the resolver through which the query should be executed

uri - the URI at which the query should be executed

Returns:

an instance of the builder that handles insertion queries

Throws:

QueryBuilder.UnboundException - if the data context is unusable

insertInto

public static InsertionBuilder insertInto(android.content.Context ctx,
                                          android.net.Uri uri)
                                   throws QueryBuilder.UnboundException

Kicks off construction of an insertion query.

Parameters:

ctx - a context which can provide a ContentResolver

uri - the URI at which the query should be executed

Returns:

an instance of the builder that handles insertion queries

Throws:

QueryBuilder.UnboundException - if the data context is unusable

update

public static UpdateBuilder update()

Kicks off construction of an update query. When constructing the builder in this way, the caller must also call onDataSource(android.content.ContentResolver, android.net.Uri), or use executeOn(android.content.ContentResolver, android.net.Uri) instead of execute().

Returns:

an instance of the builder that handles update queries

update

public static UpdateBuilder update(android.content.ContentResolver rslv,
                                   android.net.Uri uri)
                            throws QueryBuilder.UnboundException

Kicks off construction of an update query.

Parameters:

rslv - the resolver through which the query should be executed

uri - the URI at which the query should be executed

Returns:

an instance of the builder that handles update queries

Throws:

QueryBuilder.UnboundException - if the data context is unusable

update

public static UpdateBuilder update(android.content.Context ctx,
                                   android.net.Uri uri)
                            throws QueryBuilder.UnboundException

Kicks off construction of an update query.

Parameters:

ctx - a context which can provide a ContentResolver

uri - the URI at which the query should be executed

Returns:

an instance of the builder that handles update queries

Throws:

QueryBuilder.UnboundException - if the data context is unusable

select

public static SelectionBuilder select()

Kicks off construction of a selection query. When constructing the builder in this way, the caller must also call onDataSource(android.content.ContentResolver, android.net.Uri), or use executeOn(android.content.ContentResolver, android.net.Uri) instead of execute().

Returns:

an instance of the builder that handles selection queries

selectFrom

public static SelectionBuilder selectFrom(android.content.ContentResolver rslv,
                                          android.net.Uri uri)
                                   throws QueryBuilder.UnboundException

Kicks off construction of a selection query.

Parameters:

rslv - the resolver through which the query should be executed

uri - the URI at which the query should be executed

Returns:

an instance of the builder that handles selection queries

Throws:

QueryBuilder.UnboundException - if the data context is unusable

selectFrom

public static SelectionBuilder selectFrom(android.content.Context ctx,
                                          android.net.Uri uri)
                                   throws QueryBuilder.UnboundException

Kicks off construction of a selection query.

Parameters:

ctx - a context which can provide a ContentResolver

uri - the URI at which the query should be executed

Returns:

an instance of the builder that handles selection queries

Throws:

QueryBuilder.UnboundException - if the data context is unusable

delete

public static DeletionBuilder delete()

Kicks off construction of a deletion query. When constructing the builder in this way, the caller must also call onDataSource(android.content.ContentResolver, android.net.Uri), or use executeOn(android.content.ContentResolver, android.net.Uri) instead of execute().

Returns:

an instance of the builder that handles deletion queries

deleteFrom

public static DeletionBuilder deleteFrom(android.content.ContentResolver rslv,
                                         android.net.Uri uri)
                                  throws QueryBuilder.UnboundException

Kicks off construction of a deletion query.

Parameters:

rslv - the resolver through which the query should be executed

uri - the URI at which the query should be executed

Returns:

an instance of the builder that handles deletion queries

Throws:

QueryBuilder.UnboundException - if the data context is unusable

deleteFrom

public static DeletionBuilder deleteFrom(android.content.Context ctx,
                                         android.net.Uri uri)
                                  throws QueryBuilder.UnboundException

Kicks off construction of a deletion query.

Parameters:

ctx - a context which can provide a ContentResolver

uri - the URI at which the query should be executed

Returns:

an instance of the builder that handles deletion queries

Throws:

QueryBuilder.UnboundException - if the data context is unusable

getContentResolver

protected static android.content.ContentResolver getContentResolver(android.content.Context ctx)
                                                             throws QueryBuilder.UnboundException

Obtains a ContentResolver from the specified context, throwing an exception if that context is null.

Parameters:

ctx - a context which can provide a content resolver.

Returns:

the content resolver for the specified context

Throws:

QueryBuilder.UnboundException - if the context is null

validateDataContextBinding

protected static void validateDataContextBinding(android.content.ContentResolver rslv,
                                                 android.net.Uri uri)
                                          throws QueryBuilder.UnboundException

Ensures that the specified ContentResolver and Uri are non-null and usable as a data context.

Throws:

QueryBuilder.ExecutionException - if any problems occur

QueryBuilder.UnboundException

onDataSource

public I onDataSource(android.content.ContentResolver rslv,
                      android.net.Uri uri)
               throws QueryBuilder.UnboundException

Binds the builder to a specific data context, to be used by the execution methods.

Parameters:

rslv - the resolver through which the query should be executed

uri - the URI at which the query should be executed

Returns:

(fluid)

Throws:

QueryBuilder.UnboundException - if either parameter is unusable

onDataSource

public I onDataSource(android.content.Context ctx,
                      android.net.Uri uri)
               throws QueryBuilder.UnboundException

Binds the builder to a specific data context, to be used by the execution methods.

Parameters:

ctx - a context which can provide a ContentResolver

uri - the URI at which the query should be executed

Returns:

(fluid)

Throws:

QueryBuilder.UnboundException - if either parameter is unusable

setValues

public I setValues(android.content.ContentValues vals)

Sets values to be written as part of an "insert" or "update" operation, if applicable.

Parameters:

vals - the values to be written

Returns:

(fluid)

where

public I where(java.lang.String sWhereClause)

Constructs an explicit "where" clause for a query.

The supplied string is used as-is in the underlying ContentResolver query function, and should contain only necessary columns with literal values (no variable substitutions). Based on this restriction, the collection of variable substitution sources will be set as null.

Parameters:

sWhereClause - the explicit "where" clause, containing only literal values

Returns:

(fluid)

where

public I where(java.lang.String sWhereFormat,
               java.lang.String... asWhereParams)

Sets the "where" clause format and values for a query.

Parameters:

sWhereFormat - the format string of the "where" clause, which must use ? for parameter substitution

asWhereParams - the parameters for the "where" clause, assigned to substitution markers in the format string

Returns:

(fluid)

See Also:

ContentUtils.QUERY_VARIABLE_MARKER

where

public I where(java.lang.String sWhereFormat,
               java.util.Collection<java.lang.String> asWhereParams)

Sets the "where" clause format and values for a query.

Parameters:

sWhereFormat - the format string of the "where" clause, which must use ? for parameter substitution

asWhereParams - the parameters for the "where" clause, assigned to substitution markers in the format string

Returns:

(fluid)

See Also:

ContentUtils.QUERY_VARIABLE_MARKER

getWhereFormat

protected java.lang.String getWhereFormat()

Creates the Android "where" clause format string to be passed to a ContentResolver query method.

Returns:

the "where" clause format string

getWhereParams

protected java.lang.String[] getWhereParams()

Creates the array of "where" clause value substitutions to be passed to a ContentResolver query method.

Returns:

the "where" clause format string's parameters

execute

public final R execute()
                throws QueryBuilder.UnboundException,
                       QueryBuilder.ExecutionException

Executes the query that has been built by the implementation class, using the ContentResolver and Uri to which the builder has been bound, either by the constructor, or by an invocation of onDataSource(android.content.ContentResolver, android.net.Uri).

Returns:

the return type appropriate to the query action

Throws:

QueryBuilder.UnboundException

QueryBuilder.ExecutionException

executeOn

public final R executeOn(android.content.ContentResolver rslv,
                         android.net.Uri uri)
                  throws QueryBuilder.UnboundException,
                         QueryBuilder.ExecutionException

Executes the query that has been built by the implementation class, using the supplied ContentResolver and Uri. Usually, this is not invoked directly, but is instead consumed by execute().

Parameters:

rslv - the resolver through which the query should be executed

uri - the URI at which the query should be executed

Returns:

the return type appropriate to the query action

Throws:

QueryBuilder.UnboundException - if the data context binding is inadequate

QueryBuilder.ExecutionException - if the underlying query fails

executeOn

public final R executeOn(android.content.Context ctx,
                         android.net.Uri uri)
                  throws QueryBuilder.UnboundException,
                         QueryBuilder.ExecutionException

Executes the query that has been built by the implementation class, using the ContentResolver provided by the specified Context, and the specified Uri.

Parameters:

ctx - a context which can provide a ContentResolver

uri - the URI at which the query should be executed

Returns:

the return type appropriate to the query action

Throws:

QueryBuilder.UnboundException - if the data context binding is inadequate

QueryBuilder.ExecutionException - if the underlying query fails

executeQuery

protected abstract R executeQuery(android.content.ContentResolver rslv,
                                  android.net.Uri uri)
                           throws java.lang.Exception

Consumed by execute() and executeOn(android.content.ContentResolver, android.net.Uri) to actually carry out the operation. In the implementation class, this method should consist solely of the ContentResolver query method call, plus any other pre-checks which might be able to short-circuit the query execution.

Parameters:

rslv - the resolver through which the query should be executed

uri - the URI at which the query should be executed

Returns:

the return type appropriate to the query action

Throws:

java.lang.Exception - if anything goes wrong