com.mongodb
Class DBCollection

java.lang.Object
  com.mongodb.DBCollection

public abstract class DBCollection
extends java.lang.Object

This class provides a skeleton implementation of a database collection.

A typical invocation sequence is thus

     Mongo mongo = new Mongo( new DBAddress( "localhost", 127017 ) );
     DB db = mongo.getDB( "mydb" );
     DBCollection collection = db.getCollection( "test" );
 

Field Summary

protected java.lang.String	_fullName
protected java.util.List<DBObject>	_hintFields
protected java.lang.String	_name
protected java.lang.Class	_objectClass

Constructor Summary

protected

DBCollection(DB base, java.lang.String name) Initializes a new collection.

Method Summary

java.lang.Object	apply(DBObject o) Adds the "private" fields _save, _update, and _id to an object.
java.lang.Object	apply(DBObject jo, boolean ensureID) Adds the "private" fields _save, _update, and (optionally) _id to an object.
void	checkForIDIndex(DBObject key) Ensures an index on the id field, if one does not already exist.
protected boolean	checkReadOnly(boolean strict) Returns if this collection's database is read-only
void	createIndex(DBObject keys) Forces creation of an index on a set of fields, if one does not already exist.
java.util.List	distinct(java.lang.String key) find distinct values for a key
java.util.List	distinct(java.lang.String key, DBObject query) find distinct values for a key
protected abstract void	doapply(DBObject o) Adds any necessary fields to a given object before saving it to the collection.
void	drop() Drops (deletes) this collection
void	dropIndex(DBObject keys)
void	dropIndex(java.lang.String name)
void	dropIndexes() Drops all indices from this collection
void	dropIndexes(java.lang.String name)
void	ensureIDIndex() Creates an index on the id field, if one does not already exist.
void	ensureIndex(DBObject keys) Creates an index on a set of fields, if one does not already exist.
void	ensureIndex(DBObject keys, boolean force) Creates an index on a set of fields, if one does not already exist.
void	ensureIndex(DBObject keys, boolean force, boolean unique)
abstract void	ensureIndex(DBObject keys, java.lang.String name) Ensures an index on this collection (that is, the index will be created if it does not exist).
abstract void	ensureIndex(DBObject keys, java.lang.String name, boolean unique) Ensures an optionally unique index on this collection.
boolean	equals(java.lang.Object o) Checks if this collection is equal to another object.
DBCursor	find() Queries for all objects in this collection.
DBCursor	find(DBObject ref) Queries for an object in this collection.
DBCursor	find(DBObject ref, DBObject keys) Queries for an object in this collection.
abstract java.util.Iterator<DBObject>	find(DBObject ref, DBObject fields, int numToSkip, int batchSize) Finds an object.
DBObject	findOne() Returns a single object from this collection.
DBObject	findOne(DBObject o) Returns a single object from this collection matching the query.
DBObject	findOne(DBObject o, DBObject fields) Returns a single object from this collection matching the query.
DBObject	findOne(java.lang.Object obj) Finds an object by its id.
DBObject	findOne(java.lang.Object obj, DBObject fields) Finds an object by its id.
static java.lang.String	genIndexName(DBObject keys) Generate an index name from the set of fields it is over.
DBCollection	getCollection(java.lang.String n) Find a collection that is prefixed with this collection's name.
long	getCount() Returns the number of documents in the collection
long	getCount(DBObject query) Returns the number of documents in the collection that match the specified query
long	getCount(DBObject query, DBObject fields) Returns the number of documents in the collection that match the specified query
DB	getDB() Returns the database this collection is a member of.
java.lang.String	getFullName() Returns the full name of this collection, with the database name as a prefix.
java.util.List<DBObject>	getIndexInfo() Return a list of the indexes for this collection.
protected java.lang.Class	getInternalClass(java.lang.String path)
java.lang.String	getName() Returns the name of this collection.
java.lang.Class	getObjectClass() Gets the default class for objects in the collection
DB.WriteConcern	getWriteConcern()
DBObject	group(DBObject key, DBObject cond, DBObject initial, java.lang.String reduce)
int	hashCode() Calculates the hash code for this collection.
abstract void	insert(DBObject doc) Saves an document to the database.
abstract void	insert(DBObject[] arr) Saves an array of documents to the database.
abstract void	insert(java.util.List<DBObject> list) Saves an array of documents to the database.
MapReduceOutput	mapReduce(DBObject command)
MapReduceOutput	mapReduce(java.lang.String map, java.lang.String reduce, java.lang.String outputCollection, DBObject query) performs a map reduce operation
abstract void	remove(DBObject o) Removes objects from the database collection.
void	rename(java.lang.String newName) does a rename of this collection to newName
void	resetIndexCache() Clears all indices that have not yet been applied to this collection.
void	save(DBObject jo) Saves an object to this collection.
void	setHintFields(java.util.List<DBObject> lst) Set hint fields for this collection.
void	setInternalClass(java.lang.String path, java.lang.Class c)
void	setObjectClass(java.lang.Class c) Set a default class for objects in this collection
void	setWriteConcern(DB.WriteConcern concern)
java.lang.String	toString() Returns name of the collection.
void	update(DBObject q, DBObject o)
abstract void	update(DBObject q, DBObject o, boolean upsert, boolean multi) Performs an update operation.
void	updateMulti(DBObject q, DBObject o)

Methods inherited from class java.lang.Object

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

Field Detail

_name

protected final java.lang.String _name

_fullName

protected final java.lang.String _fullName

_hintFields

protected java.util.List<DBObject> _hintFields

_objectClass

protected java.lang.Class _objectClass

Constructor Detail

DBCollection

protected DBCollection(DB base,
                       java.lang.String name)

Initializes a new collection.

Parameters:

base - database in which to create the collection

name - the name of the collection

Method Detail

insert

public abstract void insert(DBObject doc)
                     throws MongoException

Saves an document to the database.

Parameters:

doc - object to save

Throws:

MongoException

insert

public abstract void insert(DBObject[] arr)
                     throws MongoException

Saves an array of documents to the database.

Parameters:

arr - array of documents to save

Throws:

MongoException

insert

public abstract void insert(java.util.List<DBObject> list)
                     throws MongoException

Saves an array of documents to the database.

Parameters:

list - list of documents to save

Throws:

MongoException

update

public abstract void update(DBObject q,
                            DBObject o,
                            boolean upsert,
                            boolean multi)
                     throws MongoException

Performs an update operation.

Parameters:

q - search query for old object to update

o - object with which to update q

upsert - if the database should create the element if it does not exist

multi - if the update should be applied to all objects matching (db version 1.1.3 and above) See http://www.mongodb.org/display/DOCS/Atomic+Operations

Throws:

MongoException

update

public void update(DBObject q,
                   DBObject o)
            throws MongoException

Throws:

MongoException

updateMulti

public void updateMulti(DBObject q,
                        DBObject o)
                 throws MongoException

Throws:

MongoException

doapply

protected abstract void doapply(DBObject o)

Adds any necessary fields to a given object before saving it to the collection.

Parameters:

o - object to which to add the fields

remove

public abstract void remove(DBObject o)
                     throws MongoException

Removes objects from the database collection.

Parameters:

o - the object that documents to be removed must match

Throws:

MongoException

find

public abstract java.util.Iterator<DBObject> find(DBObject ref,
                                                  DBObject fields,
                                                  int numToSkip,
                                                  int batchSize)
                                           throws MongoException

Finds an object.

Parameters:

ref - query used to search

fields - the fields of matching objects to return

numToSkip - will not return the first numToSkip matches

batchSize - if positive, is the # of objects per batch sent back from the db. all objects that match will be returned. if batchSize < 0, its a hard limit, and only 1 batch will either batchSize or the # that fit in a batch

Returns:

the objects, if found

Throws:

MongoException

ensureIndex

public abstract void ensureIndex(DBObject keys,
                                 java.lang.String name)
                          throws MongoException

Ensures an index on this collection (that is, the index will be created if it does not exist). ensureIndex is optimized and is inexpensive if the index already exists.

Parameters:

keys - fields to use for index

name - an identifier for the index

Throws:

MongoException

ensureIndex

public abstract void ensureIndex(DBObject keys,
                                 java.lang.String name,
                                 boolean unique)
                          throws MongoException

Ensures an optionally unique index on this collection.

Parameters:

keys - fields to use for index

name - an identifier for the index

unique - if the index should be unique

Throws:

MongoException

findOne

public final DBObject findOne(java.lang.Object obj)
                       throws MongoException

Finds an object by its id. This compares the passed in value to the _id field of the document

Parameters:

obj - any valid object

Returns:

the object, if found, otherwise null

Throws:

MongoException

findOne

public final DBObject findOne(java.lang.Object obj,
                              DBObject fields)

Finds an object by its id. This compares the passed in value to the _id field of the document

Parameters:

obj - any valid object

fields - fields to return

Returns:

the object, if found, otherwise null

checkForIDIndex

public void checkForIDIndex(DBObject key)
                     throws MongoException

Ensures an index on the id field, if one does not already exist.

Parameters:

key - an object with an _id field.

Throws:

MongoException

ensureIDIndex

public void ensureIDIndex()
                   throws MongoException

Creates an index on the id field, if one does not already exist.

Throws:

MongoException

ensureIndex

public final void ensureIndex(DBObject keys)
                       throws MongoException

Creates an index on a set of fields, if one does not already exist.

Parameters:

keys - an object with a key set of the fields desired for the index

Throws:

MongoException

createIndex

public final void createIndex(DBObject keys)
                       throws MongoException

Forces creation of an index on a set of fields, if one does not already exist.

Parameters:

keys - an object with a key set of the fields desired for the index

Throws:

MongoException

ensureIndex

public final void ensureIndex(DBObject keys,
                              boolean force)
                       throws MongoException

Creates an index on a set of fields, if one does not already exist.

Parameters:

keys - an object with a key set of the fields desired for the index

force - if index creation should be forced, even if it is unnecessary

Throws:

MongoException

ensureIndex

public final void ensureIndex(DBObject keys,
                              boolean force,
                              boolean unique)
                       throws MongoException

Throws:

MongoException

resetIndexCache

public void resetIndexCache()

Clears all indices that have not yet been applied to this collection.

genIndexName

public static java.lang.String genIndexName(DBObject keys)

Generate an index name from the set of fields it is over.

Parameters:

keys - the names of the fields used in this index

Returns:

a string representation of this index's fields

setHintFields

public void setHintFields(java.util.List<DBObject> lst)

Set hint fields for this collection.

Parameters:

lst - a list of DBObjects to be used as hints

find

public final DBCursor find(DBObject ref)

Queries for an object in this collection.

Parameters:

ref - object for which to search

Returns:

an iterator over the results

find

public final DBCursor find(DBObject ref,
                           DBObject keys)

Queries for an object in this collection.

An empty DBObject will match every document in the collection. Regardless of fields specified, the _id and _ns fields are always returned.

An example that returns the "x", "_id", and "_ns" fields for every document in the collection that has an "x" field:

 BasicDBObject keys = new BasicDBObject();
 keys.put("x", 1);

 DBCursor cursor = collection.find(new BasicDBObject(), keys); 
 

Parameters:

ref - object for which to search

keys - fields to return

Returns:

a cursor to iterate over results

find

public final DBCursor find()

Queries for all objects in this collection.

Returns:

a cursor which will iterate over every object

findOne

public final DBObject findOne()
                       throws MongoException

Returns a single object from this collection.

Returns:

the object found, or null if the collection is empty

Throws:

MongoException

findOne

public final DBObject findOne(DBObject o)
                       throws MongoException

Returns a single object from this collection matching the query.

Parameters:

o - the query object

Returns:

the object found, or null if no such object exists

Throws:

MongoException

findOne

public final DBObject findOne(DBObject o,
                              DBObject fields)

Returns a single object from this collection matching the query.

Parameters:

o - the query object

fields - fields to return

Returns:

the object found, or null if no such object exists

apply

public final java.lang.Object apply(DBObject o)

Adds the "private" fields _save, _update, and _id to an object.

Parameters:

o - DBObject to which to add fields

Returns:

the modified parameter object

apply

public final java.lang.Object apply(DBObject jo,
                                    boolean ensureID)

Adds the "private" fields _save, _update, and (optionally) _id to an object.

Parameters:

jo - object to which to add fields

ensureID - whether to add an _id field or not

Returns:

the modified object o

save

public final void save(DBObject jo)
                throws MongoException

Saves an object to this collection.

Parameters:

jo - the DBObject to save will add _id field to jo if needed

Throws:

MongoException

dropIndexes

public void dropIndexes()
                 throws MongoException

Drops all indices from this collection

Throws:

MongoException

dropIndexes

public void dropIndexes(java.lang.String name)
                 throws MongoException

Throws:

MongoException

drop

public void drop()
          throws MongoException

Drops (deletes) this collection

Throws:

MongoException

getCount

public long getCount()
              throws MongoException

Returns the number of documents in the collection

Returns:

number of documents that match query

Throws:

MongoException

getCount

public long getCount(DBObject query)
              throws MongoException

Returns the number of documents in the collection that match the specified query

Parameters:

query - query to select documents to count

Returns:

number of documents that match query

Throws:

MongoException

getCount

public long getCount(DBObject query,
                     DBObject fields)
              throws MongoException

Returns the number of documents in the collection that match the specified query

Parameters:

query - query to select documents to count

fields - fields to return

Returns:

number of documents that match query and fields

Throws:

MongoException

rename

public void rename(java.lang.String newName)
            throws MongoException

does a rename of this collection to newName

Parameters:

newName - new collection name (not a full namespace)

Throws:

MongoException

group

public DBObject group(DBObject key,
                      DBObject cond,
                      DBObject initial,
                      java.lang.String reduce)
               throws MongoException

Parameters:

key - - { a : true }

cond - - optional condition on query

reduce - javascript reduce function

initial - initial value for first match on a key

Throws:

MongoException

distinct

public java.util.List distinct(java.lang.String key)

find distinct values for a key

distinct

public java.util.List distinct(java.lang.String key,
                               DBObject query)

find distinct values for a key

Parameters:

query - query to apply on collection

mapReduce

public MapReduceOutput mapReduce(java.lang.String map,
                                 java.lang.String reduce,
                                 java.lang.String outputCollection,
                                 DBObject query)
                          throws MongoException

performs a map reduce operation

Parameters:

outputCollection - optional - leave null if want to use temp collection

query - optional - leave null if you want all objects

Throws:

MongoException

mapReduce

public MapReduceOutput mapReduce(DBObject command)
                          throws MongoException

Throws:

MongoException

getIndexInfo

public java.util.List<DBObject> getIndexInfo()

Return a list of the indexes for this collection. Each object in the list is the "info document" from MongoDB

Returns:

list of index documents

dropIndex

public void dropIndex(DBObject keys)
               throws MongoException

Throws:

MongoException

dropIndex

public void dropIndex(java.lang.String name)
               throws MongoException

Throws:

MongoException

getCollection

public DBCollection getCollection(java.lang.String n)

Find a collection that is prefixed with this collection's name. A typical use of this might be

    DBCollection users = mongo.getCollection( "wiki" ).getCollection( "users" );
 

Which is equilalent to

   DBCollection users = mongo.getCollection( "wiki.users" );
 

Parameters:

n - the name of the collection to find

Returns:

the matching collection

getName

public java.lang.String getName()

Returns the name of this collection.

Returns:

the name of this collection

getFullName

public java.lang.String getFullName()

Returns the full name of this collection, with the database name as a prefix.

Returns:

the name of this collection

getDB

public DB getDB()

Returns the database this collection is a member of.

Returns:

this collection's database

checkReadOnly

protected boolean checkReadOnly(boolean strict)

Returns if this collection's database is read-only

Parameters:

strict - if an exception should be thrown if the database is read-only

Returns:

if this collection's database is read-only

Throws:

java.lang.RuntimeException - if the database is read-only and strict is set

hashCode

public int hashCode()

Calculates the hash code for this collection.

Overrides:

hashCode in class java.lang.Object

Returns:

the hash code

equals

public boolean equals(java.lang.Object o)

Checks if this collection is equal to another object.

Overrides:

equals in class java.lang.Object

Parameters:

o - object with which to compare this collection

Returns:

if the two collections are the same object

toString

public java.lang.String toString()

Returns name of the collection.

Overrides:

toString in class java.lang.Object

Returns:

name of the collection.

setObjectClass

public void setObjectClass(java.lang.Class c)

Set a default class for objects in this collection

Parameters:

c - the class

Throws:

java.lang.IllegalArgumentException - if c is not a DBObject

getObjectClass

public java.lang.Class getObjectClass()

Gets the default class for objects in the collection

Returns:

the class

setInternalClass

public void setInternalClass(java.lang.String path,
                             java.lang.Class c)

getInternalClass

protected java.lang.Class getInternalClass(java.lang.String path)

setWriteConcern

public void setWriteConcern(DB.WriteConcern concern)

getWriteConcern

public DB.WriteConcern getWriteConcern()