com.allanbank.mongodb.builder

Class Find.Builder

java.lang.Object

com.allanbank.mongodb.builder.Find.Builder

Enclosing class:

Find

public static class Find.Builder
extends Object

Helper for creating immutable Find queries.

API Notice:

This class is part of the driver's API. Public and protected members will be deprecated for at least 1 non-bugfix release (version numbers are <major>.<minor>.<bugfix>) before being removed or modified.

Copyright ©:

2012, Allanbank Consulting, Inc., All Rights Reserved

Field Summary

Fields

Modifier and Type	Field and Description
protected int	myBatchSize The number of documents to be returned in each batch of results.
protected Document	myHint The hint for which index to use.
protected String	myHintName The hint for which index to use.
protected int	myLimit The total number of documents to be returned.
protected int	myNumberToSkip The number of documents to skip before returning the first document.
protected boolean	myPartialOk If true then an error in the query should return any partial results.
protected Document	myQuery The query document.
protected ReadPreference	myReadPreference The preference for which servers to use to retrieve the results.
protected Document	myReturnFields The fields to be returned from the matching documents.
protected boolean	mySnapshot If set to true then use snapshot mode to ensure document are only returned once.
protected Document	mySort The fields to order the document on.
protected boolean	myTailable If set to true the cursur returned from the query will be tailable.

Constructor Summary

Constructors

Constructor and Description
Find.Builder() Creates a new Builder.
Find.Builder(DocumentAssignable query) Creates a new Builder.

Method Summary

Methods

Modifier and Type	Method and Description
Find	build() Constructs a new Find object from the state of the builder.
Find.Builder	partialOk() Sets that if there is an error then the query should return any partial results.
Find.Builder	reset() Resets the builder back to its initial state for reuse.
Find.Builder	setBatchSize(int batchSize) Sets the value of the number of documents to be returned in each batch.
Find.Builder	setHint(DocumentAssignable indexFields) Sets the value of hint as to which index should be used to execute the query.
Find.Builder	setHint(IntegerElement... indexFields) Sets the value of hint as to which index should be used to execute the query.
Find.Builder	setHint(String indexName) Sets the value of hint as to which index should be used to execute the query.
Find.Builder	setLimit(int limit) Sets the value of the total number of documents to be returned.
Find.Builder	setNumberToSkip(int numberToSkip) Sets the value of the number of documents to skip before returning the first document to the new value.
Find.Builder	setPartialOk(boolean partialOk) Sets the value of partial okay to the new value.
Find.Builder	setQuery(DocumentAssignable query) Sets the value of the query document to the new value.
Find.Builder	setReadPreference(ReadPreference readPreference) Sets the preference for the set of servers to retrieve the results from.
Find.Builder	setReturnFields(DocumentAssignable returnFields) Sets the value of the fields to be returned from the matching documents to the new value.
Find.Builder	setSnapshot(boolean snapshot) Sets the value of snapshot to the new value.
Find.Builder	setSort(DocumentAssignable sortFields) Sets the value of the fields to to sort matching documents by.
Find.Builder	setSort(IntegerElement... sortFields) Sets the value of the fields to to sort matching documents by.
Find.Builder	setTailable(boolean tailable) If set to true the cursur returned from the query will be tailable.
Find.Builder	snapshot() Sets that the query should ensure that documents are only returned once.
Find.Builder	tailable() Sets the the cursur returned from the query to be tailable.

Methods inherited from class java.lang.Object

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

Field Detail

myBatchSize

protected int myBatchSize

The number of documents to be returned in each batch of results.

myHint

protected Document myHint

The hint for which index to use.

myHintName

protected String myHintName

The hint for which index to use.

myLimit

protected int myLimit

The total number of documents to be returned.

myNumberToSkip

protected int myNumberToSkip

The number of documents to skip before returning the first document.

myPartialOk

protected boolean myPartialOk

If true then an error in the query should return any partial results.

myQuery

protected Document myQuery

The query document.

myReadPreference

protected ReadPreference myReadPreference

The preference for which servers to use to retrieve the results.

myReturnFields

protected Document myReturnFields

The fields to be returned from the matching documents.

mySnapshot

protected boolean mySnapshot

If set to true then use snapshot mode to ensure document are only returned once.

mySort

protected Document mySort

The fields to order the document on.

myTailable

protected boolean myTailable

If set to true the cursur returned from the query will be tailable.

Constructor Detail

Find.Builder

public Find.Builder()

Creates a new Builder.

Find.Builder

public Find.Builder(DocumentAssignable query)

Creates a new Builder.

Parameters:

query - The query document.

Method Detail

build

public Find build()

Constructs a new Find object from the state of the builder.

Returns:

The new Find object.

partialOk

public Find.Builder partialOk()

Sets that if there is an error then the query should return any partial results.

Returns:

This builder for chaining method calls.

reset

public Find.Builder reset()

Resets the builder back to its initial state for reuse.

Returns:

This builder for chaining method calls.

setBatchSize

public Find.Builder setBatchSize(int batchSize)

Sets the value of the number of documents to be returned in each batch.

Parameters:

batchSize - The new value for the number of documents to be returned in each batch.

Returns:

This builder for chaining method calls.

setHint

public Find.Builder setHint(DocumentAssignable indexFields)

Sets the value of hint as to which index should be used to execute the query.

Parameters:

indexFields - The new value for the fields of the index to use to execute the query.

Returns:

This builder for chaining method calls.

setHint

public Find.Builder setHint(IntegerElement... indexFields)

Sets the value of hint as to which index should be used to execute the query.

This method is intended to be used with the Sort class's static methods:

 
 import static com.allanbank.mongodb.builder.Sort.asc;
 import static com.allanbank.mongodb.builder.Sort.desc;
 
 Find.Builder builder = new Find.Builder();
 
 builder.setHint( asc("f"), desc("g") );
 ...
 
 

Parameters:

indexFields - The new value for the fields of the index to use to execute the query.

Returns:

This builder for chaining method calls.

setHint

public Find.Builder setHint(String indexName)

Sets the value of hint as to which index should be used to execute the query.

Parameters:

indexName - The new value for the name of the index to use to execute the query.

Returns:

This builder for chaining method calls.

setLimit

public Find.Builder setLimit(int limit)

Sets the value of the total number of documents to be returned.

Parameters:

limit - The new value for the total number of documents to be returned.

Returns:

This builder for chaining method calls.

setNumberToSkip

public Find.Builder setNumberToSkip(int numberToSkip)

Sets the value of the number of documents to skip before returning the first document to the new value.

Parameters:

numberToSkip - The new value for the number of documents to skip before returning the first document.

Returns:

This builder for chaining method calls.

setPartialOk

public Find.Builder setPartialOk(boolean partialOk)

Sets the value of partial okay to the new value. If true then an error in the query should return any partial results.

Parameters:

partialOk - The new value for the partial okay.

Returns:

This builder for chaining method calls.

setQuery

public Find.Builder setQuery(DocumentAssignable query)

Sets the value of the query document to the new value.

Parameters:

query - The new value for the query document.

Returns:

This builder for chaining method calls.

setReadPreference

public Find.Builder setReadPreference(ReadPreference readPreference)

Sets the preference for the set of servers to retrieve the results from.

Parameters:

readPreference - The new value for the preference of which server to return the results from.

Returns:

This builder for chaining method calls.

setReturnFields

public Find.Builder setReturnFields(DocumentAssignable returnFields)

Sets the value of the fields to be returned from the matching documents to the new value.

Parameters:

returnFields - The new value for the fields to be returned from the matching documents.

Returns:

This builder for chaining method calls.

setSnapshot

public Find.Builder setSnapshot(boolean snapshot)

Sets the value of snapshot to the new value. If set to true then use snapshot mode to ensure document are only returned once.

Parameters:

snapshot - The new value for the partial okay.

Returns:

This builder for chaining method calls.

setSort

public Find.Builder setSort(DocumentAssignable sortFields)

Sets the value of the fields to to sort matching documents by.

Parameters:

sortFields - The new value for the fields to sort matching documents by.

Returns:

This builder for chaining method calls.

setSort

public Find.Builder setSort(IntegerElement... sortFields)

Sets the value of the fields to to sort matching documents by.

This method is intended to be used with the Sort class's static methods:

 
 import static com.allanbank.mongodb.builder.Sort.asc;
 import static com.allanbank.mongodb.builder.Sort.desc;
 
 Find.Builder builder = new Find.Builder();
 
 builder.setSort( asc("f"), desc("g") );
 ...
 
 

Parameters:

sortFields - The new value for the fields to sort matching documents by.

Returns:

This builder for chaining method calls.

setTailable

public Find.Builder setTailable(boolean tailable)

If set to true the cursur returned from the query will be tailable.

Testing has shown that a tailable cursor on an empty collection will not setup a cursor on the MongoDB server and will immediately return false from Iterator.hasNext().

When using a tailable cursor that has exhausted the available data will cause the Iterator.hasNext() calls to block until more data is available. The connection that is used to request more documents will also be blocked for short intervals (measured to be ~2.25 seconds with 2.0.7). Any requests submitted behind the cursors request will also be blocked.

It is highly recommended that the number of connections within the MongoClientConfiguration be at least 1 more than the maximum number of active tailable cursors.

Parameters:

tailable - The new value for if the cursur returned from the query will be tailable.

Returns:

This builder for chaining method calls.

snapshot

public Find.Builder snapshot()

Sets that the query should ensure that documents are only returned once.

Returns:

This builder for chaining method calls.

tailable

public Find.Builder tailable()

Sets the the cursur returned from the query to be tailable.

Returns:

This builder for chaining method calls.

See Also:

setTailable(boolean) for important usage information.