com.allanbank.mongodb.client.message

Class Query

java.lang.Object

com.allanbank.mongodb.client.message.AbstractMessage

com.allanbank.mongodb.client.message.Query

All Implemented Interfaces:

Message, CursorableMessage

Direct Known Subclasses:

GetLastError

public class Query
extends AbstractMessage
implements CursorableMessage

Message to query documents from the database matching a criteria. Also used to issue commands to the database.

 
 struct OP_QUERY {
     MsgHeader header;                // standard message header
     int32     flags;                  // bit vector of query options.  See below for details.
     cstring   fullCollectionName;    // "dbname.collectionname"
     int32     numberToSkip;          // number of documents to skip
     int32     numberToReturn;        // number of documents to return
                                      //  in the first OP_REPLY batch
     document  query;                 // query object.
   [ document  returnFieldSelector; ] // Optional. Selector indicating the fields
                                      //  to return.
 }
 
 

API Warning:

This class is NOT part of the drivers API. This class may be mutated in incompatible ways between any two releases of the driver.

Copyright ©:

2011-2013, Allanbank Consulting, Inc., All Rights Reserved

Field Summary

Fields

Modifier and Type	Field and Description
static int	AWAIT_DATA_FLAG_BIT Flag bit for the await data.
static int	DEFAULT_BATCH_SIZE The default batch size for a MongoDB query.
static int	EXHAUST_FLAG_BIT Flag bit for the exhaust results.
static int	NO_CURSOR_TIMEOUT_FLAG_BIT Flag bit for the no cursor timeout.
static int	OPLOG_REPLAY_FLAG_BIT Flag bit for the OPLOG_REPLAY.
static int	PARTIAL_FLAG_BIT Flag bit for the partial results.
static int	REPLICA_OK_FLAG_BIT Flag bit for the replica OK.
static int	TAILABLE_CURSOR_FLAG_BIT Flag bit for the tailable cursors.

Fields inherited from class com.allanbank.mongodb.client.message.AbstractMessage

HEADER_SIZE, myCollectionName, myDatabaseName

Constructor Summary

Constructors

Constructor and Description
Query(Header header, BsonInputStream in) Creates a new Query.
Query(String databaseName, String collectionName, Document query, Document returnFields, int batchSize, int limit, int numberToSkip, boolean tailable, ReadPreference readPreference, boolean noCursorTimeout, boolean awaitData, boolean exhaust, boolean partial) Creates a new Query.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	equals(Object object) Determines if the passed object is of this same type as this object and if so that its fields are equal.
int	getBatchSize() Returns the number of documents to be returned in each batch of results.
int	getLimit() Returns the total number of documents to be returned.
int	getNumberToReturn() Returns the number of documents to be returned.
int	getNumberToSkip() Returns the number of documents to skip before starting to return documents.
String	getOperationName() Returns a short name for the operation.
Document	getQuery() Returns the query document containing the expression to select documents from the collection.
Document	getReturnFields() Returns the optional document containing the fields to be returned.
int	hashCode() Computes a reasonable hash code.
boolean	isAwaitData() Returns true and if using a tailable cursor then the connection will block waiting for more data.
boolean	isBatchSizeSet() Returns true if the batch size is greater than zero.
boolean	isExhaust() Returns true if all results should be returned in multiple results.
boolean	isLimitSet() Returns true if the limit is greater than zero.
boolean	isNoCursorTimeout() Returns true if marking the cursor as not having a timeout.
boolean	isPartial() Returns true if return the results found and suppress shard down errors.
boolean	isTailable() Returns true if the cursor created should follow additional documents being inserted.
int	size() Returns the total size of the message on the wire.
void	validateSize(int maxDocumentSize) Validates that the documents with the message do not exceed the maximum document size specified.
void	write(int messageId, BsonOutputStream out) Writes the message from the stream.
void	write(int messageId, BufferingBsonOutputStream out) Writes the message from the stream.

Methods inherited from class com.allanbank.mongodb.client.message.AbstractMessage

finishHeader, getCollectionName, getDatabaseName, getReadPreference, getRequiredVersionRange, init, writeHeader, writeHeader

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.allanbank.mongodb.client.message.CursorableMessage

getCollectionName

Methods inherited from interface com.allanbank.mongodb.client.Message

getDatabaseName, getReadPreference, getRequiredVersionRange

Field Detail

AWAIT_DATA_FLAG_BIT

public static final int AWAIT_DATA_FLAG_BIT

Flag bit for the await data.

See Also:

Constant Field Values

DEFAULT_BATCH_SIZE

public static final int DEFAULT_BATCH_SIZE

The default batch size for a MongoDB query.

See Also:

Constant Field Values

EXHAUST_FLAG_BIT

public static final int EXHAUST_FLAG_BIT

Flag bit for the exhaust results.

See Also:

Constant Field Values

NO_CURSOR_TIMEOUT_FLAG_BIT

public static final int NO_CURSOR_TIMEOUT_FLAG_BIT

Flag bit for the no cursor timeout.

See Also:

Constant Field Values

OPLOG_REPLAY_FLAG_BIT

public static final int OPLOG_REPLAY_FLAG_BIT

Flag bit for the OPLOG_REPLAY.

See Also:

Constant Field Values

PARTIAL_FLAG_BIT

public static final int PARTIAL_FLAG_BIT

Flag bit for the partial results.

See Also:

Constant Field Values

REPLICA_OK_FLAG_BIT

public static final int REPLICA_OK_FLAG_BIT

Flag bit for the replica OK.

See Also:

Constant Field Values

TAILABLE_CURSOR_FLAG_BIT

public static final int TAILABLE_CURSOR_FLAG_BIT

Flag bit for the tailable cursors.

See Also:

Constant Field Values

Constructor Detail

Query

public Query(Header header,
     BsonInputStream in)
      throws IOException

Creates a new Query.

Parameters:

header - The header for the query message.

in - The stream to read the kill_cursors message from.

Throws:

IOException - On a failure reading the kill_cursors message.

Query

public Query(String databaseName,
     String collectionName,
     Document query,
     Document returnFields,
     int batchSize,
     int limit,
     int numberToSkip,
     boolean tailable,
     ReadPreference readPreference,
     boolean noCursorTimeout,
     boolean awaitData,
     boolean exhaust,
     boolean partial)

Creates a new Query.

Parameters:

databaseName - The name of the database.

collectionName - The name of the collection.

query - The query document containing the expression to select documents from the collection.

returnFields - Optional document containing the fields to be returned.

batchSize - The number of documents to be returned in each batch.

limit - The limit on the number of documents to return.

numberToSkip - The number of documents to skip before starting to return documents.

tailable - If true, then the cursor created should follow additional documents being inserted.

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

noCursorTimeout - If true, marks the cursor as not having a timeout.

awaitData - If true and if using a tailable cursor then the connection will block waiting for more data.

exhaust - If true, all results should be returned in multiple results.

partial - If true, return the results found and suppress shard down errors.

Method Detail

equals

public boolean equals(Object object)

Determines if the passed object is of this same type as this object and if so that its fields are equal.

Overrides:

equals in class AbstractMessage

Parameters:

object - The object to compare to.

See Also:

Object.equals(java.lang.Object)

getBatchSize

public int getBatchSize()

Returns the number of documents to be returned in each batch of results.

Specified by:

getBatchSize in interface CursorableMessage

Returns:

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

getLimit

public int getLimit()

Returns the total number of documents to be returned.

Specified by:

getLimit in interface CursorableMessage

Returns:

The total number of documents to be returned.

getNumberToReturn

public int getNumberToReturn()

Returns the number of documents to be returned.

Returns:

The number of documents to be returned.

getNumberToSkip

public int getNumberToSkip()

Returns the number of documents to skip before starting to return documents.

Returns:

The number of documents to skip before starting to return documents.

getOperationName

public String getOperationName()

Returns a short name for the operation.

Overridden to return the name of the operation: "QUERY".

Specified by:

getOperationName in interface Message

Returns:

A short name for the operation.

getQuery

public Document getQuery()

Returns the query document containing the expression to select documents from the collection.

Returns:

The query document containing the expression to select documents from the collection.

getReturnFields

public Document getReturnFields()

Returns the optional document containing the fields to be returned. Optional here means this method may return null.

Returns:

The optional document containing the fields to be returned.

hashCode

public int hashCode()

Computes a reasonable hash code.

Overrides:

hashCode in class AbstractMessage

Returns:

The hash code value.

isAwaitData

public boolean isAwaitData()

Returns true and if using a tailable cursor then the connection will block waiting for more data.

Returns:

True and if using a tailable cursor then the connection will block waiting for more data.

isBatchSizeSet

public boolean isBatchSizeSet()

Returns true if the batch size is greater than zero.

Returns:

True if the batch size is greater than zero.

isExhaust

public boolean isExhaust()

Returns true if all results should be returned in multiple results.

Returns:

True if all results should be returned in multiple results.

isLimitSet

public boolean isLimitSet()

Returns true if the limit is greater than zero.

Returns:

True if the limit is greater than zero.

isNoCursorTimeout

public boolean isNoCursorTimeout()

Returns true if marking the cursor as not having a timeout.

Returns:

True if marking the cursor as not having a timeout.

isPartial

public boolean isPartial()

Returns true if return the results found and suppress shard down errors.

Returns:

True if return the results found and suppress shard down errors..

isTailable

public boolean isTailable()

Returns true if the cursor created should follow additional documents being inserted.

Returns:

True if the cursor created should follow additional documents being inserted.

size

public int size()

Returns the total size of the message on the wire.

Overridden to return the size of the Query.

Specified by:

size in interface Message

Returns:

The size of the message on the wire.

validateSize

public void validateSize(int maxDocumentSize)
                  throws DocumentToLargeException

Validates that the documents with the message do not exceed the maximum document size specified.

Overridden to ensure the inserted documents are not too large in aggregate.

Specified by:

validateSize in interface Message

Parameters:

maxDocumentSize - The maximum document size to validate against.

Throws:

DocumentToLargeException - If one of the documents in the message is too large or the documents in aggregate are too large.

write

public void write(int messageId,
         BsonOutputStream out)
           throws IOException

Writes the message from the stream. The message header is written by this method.

Overridden to write the query message.

Specified by:

write in interface Message

Parameters:

messageId - The id to be assigned to the message.

out - The sink for data written.

Throws:

IOException - On an error writing to the stream.

See Also:

Message.write(int, BsonOutputStream)

write

public void write(int messageId,
         BufferingBsonOutputStream out)
           throws IOException

Writes the message from the stream. The message header is written by this method.

Overridden to write the query message.

Specified by:

write in interface Message

Parameters:

messageId - The id to be assigned to the message.

out - The sink for data written.

Throws:

IOException - On an error writing to the stream.

See Also:

Message.write(int, BsonOutputStream)