com.mongodb
Class DBCollection

java.lang.Object
  com.mongodb.DBCollection

public abstract class DBCollection
extends 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" );
 

MongoDB Doc Links

• collections

Field Summary

protected String	_fullName
protected List<DBObject>	_hintFields
protected String	_name
protected Class	_objectClass

Constructor Summary

protected

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

Method Summary

Object	apply(DBObject o) Adds the "private" fields _id to an object.
Object	apply(DBObject jo, boolean ensureID) Adds the "private" fields _id to an object.
protected boolean	checkReadOnly(boolean strict) Returns if this collection's database is read-only
long	count()
long	count(DBObject query)
void	createIndex(DBObject keys) Forces creation of an index on a set of fields, if one does not already exist.
protected abstract void	createIndex(DBObject keys, DBObject options)
List	distinct(String key) find distinct values for a key
List	distinct(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(String name)
void	dropIndexes() Drops all indices from this collection
void	dropIndexes(String name)
void	ensureIndex(DBObject keys) Creates an index on a set of fields, if one does not already exist.
void	ensureIndex(DBObject keys, DBObject optionsIN)
void	ensureIndex(DBObject keys, String name) Ensures an index on this collection (that is, the index will be created if it does not exist).
void	ensureIndex(DBObject keys, String name, boolean unique) Ensures an optionally unique index on this collection.
void	ensureIndex(String name)
boolean	equals(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.
DBCursor	find(DBObject ref, DBObject fields, int numToSkip, int batchSize) Finds an object.
DBCursor	find(DBObject ref, DBObject fields, int numToSkip, int batchSize, int options) 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(Object obj) Finds an object by its id.
DBObject	findOne(Object obj, DBObject fields) Finds an object by its id.
static String	genIndexName(DBObject keys) Generate an index name from the set of fields it is over.
DBCollection	getCollection(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.
String	getFullName() Returns the full name of this collection, with the database name as a prefix.
List<DBObject>	getIndexInfo() Return a list of the indexes for this collection.
protected Class	getInternalClass(String path)
String	getName() Returns the name of this collection.
Class	getObjectClass() Gets the default class for objects in the collection
DB.WriteConcern	getWriteConcern() Get the write concern for this collection.
DBObject	group(DBObject key, DBObject cond, DBObject initial, 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(List<DBObject> list) Saves an array of documents to the database.
MapReduceOutput	mapReduce(DBObject command)
MapReduceOutput	mapReduce(String map, String reduce, String outputCollection, DBObject query) performs a map reduce operation
abstract void	remove(DBObject o) Removes objects from the database collection.
DBCollection	rename(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(List<DBObject> lst) Set hint fields for this collection.
void	setInternalClass(String path, Class c)
void	setObjectClass(Class c) Set a default class for objects in this collection
void	setWriteConcern(DB.WriteConcern concern) Set the write concern for this collection.
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 String _name

_fullName

protected final String _fullName

_hintFields

protected List<DBObject> _hintFields

_objectClass

protected Class _objectClass

Constructor Detail

DBCollection

protected DBCollection(DB base,
                       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. if doc doesn't have an _id, one will be added you can get the _id that was added from doc after the insert

Parameters:

doc - object to save

Throws:

MongoException

MongoDB Doc Links

• insert

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

MongoDB Doc Links

• insert

insert

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

Saves an array of documents to the database.

Parameters:

list - list of documents to save

Throws:

MongoException

MongoDB Doc Links

• insert

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

MongoDB Doc Links

• update

update

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

Throws:

MongoException

MongoDB Doc Links

• update

updateMulti

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

Throws:

MongoException

MongoDB Doc Links

• update

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

MongoDB Doc Links

• remove

find

public final DBCursor find(DBObject ref,
                           DBObject fields,
                           int numToSkip,
                           int batchSize,
                           int options)
                    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

options - - see Bytes QUERYOPTION_*

Returns:

the objects, if found

Throws:

MongoException

MongoDB Doc Links

• find

find

public final DBCursor find(DBObject ref,
                           DBObject fields,
                           int numToSkip,
                           int batchSize)

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

MongoDB Doc Links

• find

createIndex

protected abstract void createIndex(DBObject keys,
                                    DBObject options)
                             throws MongoException

Throws:

MongoException

findOne

public final DBObject findOne(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(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

MongoDB Doc Links

• find

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(String name)

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

ensureIndex

public void ensureIndex(DBObject keys,
                        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

MongoDB Doc Links

• indexes

ensureIndex

public void ensureIndex(DBObject keys,
                        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

ensureIndex

public final void ensureIndex(DBObject keys,
                              DBObject optionsIN)
                       throws MongoException

Throws:

MongoException

resetIndexCache

public void resetIndexCache()

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

genIndexName

public static 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(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

MongoDB Doc Links

• find

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 fields are always returned.

An example that returns the "x" and "_id" 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

MongoDB Doc Links

• find

find

public final DBCursor find()

Queries for all objects in this collection.

Returns:

a cursor which will iterate over every object

MongoDB Doc Links

• find

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

MongoDB Doc Links

• find

apply

public final Object apply(DBObject o)

Adds the "private" fields _id to an object.

Parameters:

o - DBObject to which to add fields

Returns:

the modified parameter object

apply

public final Object apply(DBObject jo,
                          boolean ensureID)

Adds the "private" fields _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(String name)
                 throws MongoException

Throws:

MongoException

drop

public void drop()
          throws MongoException

Drops (deletes) this collection

Throws:

MongoException

count

public long count()
           throws MongoException

Throws:

MongoException

count

public long count(DBObject query)
           throws MongoException

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 DBCollection rename(String newName)
                    throws MongoException

does a rename of this collection to newName

Parameters:

newName - new collection name (not a full namespace)

Returns:

the new collection

Throws:

MongoException

group

public DBObject group(DBObject key,
                      DBObject cond,
                      DBObject initial,
                      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 List distinct(String key)

find distinct values for a key

distinct

public List distinct(String key,
                     DBObject query)

find distinct values for a key

Parameters:

query - query to apply on collection

mapReduce

public MapReduceOutput mapReduce(String map,
                                 String reduce,
                                 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

MongoDB Doc Links

• mapreduce

mapReduce

public MapReduceOutput mapReduce(DBObject command)
                          throws MongoException

Throws:

MongoException

getIndexInfo

public 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(String name)
               throws MongoException

Throws:

MongoException

getCollection

public DBCollection getCollection(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 String getName()

Returns the name of this collection.

Returns:

the name of this collection

getFullName

public 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:

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 Object

Returns:

the hash code

equals

public boolean equals(Object o)

Checks if this collection is equal to another object.

Overrides:

equals in class Object

Parameters:

o - object with which to compare this collection

Returns:

if the two collections are the same object

toString

public String toString()

Returns name of the collection.

Overrides:

toString in class Object

Returns:

name of the collection.

setObjectClass

public void setObjectClass(Class c)

Set a default class for objects in this collection

Parameters:

c - the class

Throws:

IllegalArgumentException - if c is not a DBObject

getObjectClass

public Class getObjectClass()

Gets the default class for objects in the collection

Returns:

the class

setInternalClass

public void setInternalClass(String path,
                             Class c)

getInternalClass

protected Class getInternalClass(String path)

setWriteConcern

public void setWriteConcern(DB.WriteConcern concern)

Set the write concern for this collection. Will be used for writes to this collection. Overrides any setting of write concern at the DB level. See the documentation for DB.WriteConcern for more information.

Parameters:

concern - write concern to use

getWriteConcern

public DB.WriteConcern getWriteConcern()

Get the write concern for this collection.