Package com.couchbase.lite

Class Select

java.lang.Object

com.couchbase.lite.Select

All Implemented Interfaces:

com.couchbase.lite.internal.Listenable<QueryChange,QueryChangeListener>, Query

public final class Select
extends java.lang.Object

Select represents the SELECT clause of the query for specifying the properties in each query result row.

Method Summary

Modifier and Type	Method	Description
ListenerToken	addChangeListener(QueryChangeListener listener)	Adds a query change listener.
ListenerToken	addChangeListener(java.util.concurrent.Executor executor, QueryChangeListener listener)	Adds a query change listener with the dispatch queue on which changes will be posted.
ResultSet	execute()	Executes the query returning a result set that enumerates result rows one at a time.
java.lang.String	explain()	Returns a string describing the implementation of the compiled query.
From	from(DataSource dataSource)	Create and chain a FROM component for specifying the query's data source.
Parameters	getParameters()	Returns a copy of the current parameters.
void	removeChangeListener(ListenerToken token)	Deprecated. use ListenerToken.remove()
void	setParameters(Parameters parameters)	Set query parameters.
java.lang.String	toString()

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

from

@NonNull
public From from(@NonNull
                 DataSource dataSource)

Create and chain a FROM component for specifying the query's data source.

Parameters:

dataSource - the data source.

Returns:

the From component.

toString

@NonNull
public java.lang.String toString()

Overrides:

toString in class java.lang.Object

getParameters

@Nullable
public Parameters getParameters()

Returns a copy of the current parameters.

Specified by:

getParameters in interface Query

setParameters

public void setParameters(@Nullable
                          Parameters parameters)

Set query parameters. Setting new parameters will re-execute a query if there is at least one listener listening for changes.

Specified by:

setParameters in interface Query

Throws:

java.lang.IllegalStateException - on failure to create the query (e.g., database closed)

java.lang.IllegalArgumentException - on failure to encode the parameters (e.g., parameter value not supported)

execute

@NonNull
public ResultSet execute()
                  throws CouchbaseLiteException

Executes the query returning a result set that enumerates result rows one at a time. You can run the query any number of times and you can even have multiple ResultSet active at once.

The results come from a snapshot of the database taken at the moment the run() method is called, so they will not reflect any changes made to the database afterwards.

Specified by:

execute in interface Query

Returns:

the ResultSet for the query result.

Throws:

CouchbaseLiteException - if there is an error when running the query.

explain

@NonNull
public java.lang.String explain()
                         throws CouchbaseLiteException

Returns a string describing the implementation of the compiled query. This is intended to be read by a developer for purposes of optimizing the query, especially to add database indexes. It's not machine-readable and its format may change. As currently implemented, the result is two or more lines separated by newline characters:

• The first line is the SQLite SELECT statement.
• The subsequent lines are the output of SQLite's "EXPLAIN QUERY PLAN" command applied to that statement.

For help interpreting this, see: eqp. The most important thing to know is that if you see "SCAN TABLE", it means that SQLite is doing a slow linear scan of the documents instead of using an index.

Specified by:

explain in interface Query

Returns:

a string describing the implementation of the compiled query.

Throws:

CouchbaseLiteException - if an error occurs

addChangeListener

@NonNull
public ListenerToken addChangeListener(@NonNull
                                       QueryChangeListener listener)

Adds a query change listener. Changes will be posted on the main queue.

Specified by:

addChangeListener in interface com.couchbase.lite.internal.Listenable<QueryChange,QueryChangeListener>

Specified by:

addChangeListener in interface Query

Parameters:

listener - The listener to post changes.

Returns:

An opaque listener token object for removing the listener.

addChangeListener

@NonNull
public ListenerToken addChangeListener(@Nullable
                                       java.util.concurrent.Executor executor,
                                       @NonNull
                                       QueryChangeListener listener)

Adds a query change listener with the dispatch queue on which changes will be posted. If the dispatch queue is not specified, the changes will be posted on the main queue.

Specified by:

addChangeListener in interface com.couchbase.lite.internal.Listenable<QueryChange,QueryChangeListener>

Specified by:

addChangeListener in interface Query

Parameters:

executor - The executor object that calls listener. If null, use default executor.

listener - The listener to post changes.

Returns:

An opaque listener token object for removing the listener.

Throws:

java.lang.IllegalStateException - on failure to create the query (e.g., database closed)

removeChangeListener

@Deprecated
public void removeChangeListener(@NonNull
                                 ListenerToken token)

Deprecated.

use ListenerToken.remove()

Removes a change listener wih the given listener token.

Specified by:

removeChangeListener in interface Query

Parameters:

token - The listener token.