com.mongodb
Class DBCollection

java.lang.Object
  extended by 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

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 findAndModify(DBObject query, DBObject update)
          Finds the first document in the query and updates it.
 DBObject findAndModify(DBObject query, DBObject sort, DBObject update)
          Finds the first document in the query (sorted) and updates it.
 DBObject findAndModify(DBObject query, DBObject fields, DBObject sort, boolean remove, DBObject update, boolean returnNew, boolean upsert)
          Finds the first document in the query (sorted) and updates it.
 DBObject findAndRemove(DBObject query)
          Finds the first document in the query and removes it.
 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
 long getCount(DBObject query, DBObject fields, long limit, long skip)
          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
 CommandResult getStats()
           
 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.
 WriteResult insert(DBObject... arr)
          Saves document(s) to the database.
abstract  WriteResult insert(DBObject[] arr, WriteConcern concern)
          Saves document(s) to the database.
 WriteResult insert(DBObject o, WriteConcern concern)
          Inserts a document into the database.
 WriteResult insert(List<DBObject> list)
          Saves document(s) to the database.
 boolean isCapped()
           
 MapReduceOutput mapReduce(DBObject command)
           
 MapReduceOutput mapReduce(String map, String reduce, String outputCollection, DBObject query)
          performs a map reduce operation
 WriteResult remove(DBObject o)
          Removes objects from the database collection.
abstract  WriteResult remove(DBObject o, WriteConcern concern)
          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.
 WriteResult save(DBObject jo)
          Saves an object to this collection.
 WriteResult save(DBObject jo, WriteConcern concern)
          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(WriteConcern concern)
          Set the write concern for this collection.
 String toString()
          Returns name of the collection.
 WriteResult update(DBObject q, DBObject o)
           
 WriteResult update(DBObject q, DBObject o, boolean upsert, boolean multi)
          Performs an update operation.
abstract  WriteResult update(DBObject q, DBObject o, boolean upsert, boolean multi, WriteConcern concern)
          Performs an update operation.
 WriteResult 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 WriteResult insert(DBObject[] arr,
                                   WriteConcern concern)
                            throws MongoException
Saves document(s) 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:
arr - array of documents to save
Throws:
MongoException
MongoDB Doc Links

insert

public WriteResult insert(DBObject o,
                          WriteConcern concern)
                   throws MongoException
Inserts a document into 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:
arr - array of documents to save
Throws:
MongoException
MongoDB Doc Links

insert

public WriteResult insert(DBObject... arr)
                   throws MongoException
Saves document(s) 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:
arr - array of documents to save
Throws:
MongoException
MongoDB Doc Links

insert

public WriteResult insert(List<DBObject> list)
                   throws MongoException
Saves document(s) 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:
list - list of documents to save
Throws:
MongoException
MongoDB Doc Links

update

public abstract WriteResult update(DBObject q,
                                   DBObject o,
                                   boolean upsert,
                                   boolean multi,
                                   WriteConcern concern)
                            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
concern - WriteConcern for this operation
Throws:
MongoException
MongoDB Doc Links

update

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

public WriteResult update(DBObject q,
                          DBObject o)
                   throws MongoException
Throws:
MongoException
MongoDB Doc Links

updateMulti

public WriteResult updateMulti(DBObject q,
                               DBObject o)
                        throws MongoException
Throws:
MongoException
MongoDB Doc Links

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 WriteResult remove(DBObject o,
                                   WriteConcern concern)
                            throws MongoException
Removes objects from the database collection.

Parameters:
o - the object that documents to be removed must match
concern - WriteConcern for this operation
Throws:
MongoException
MongoDB Doc Links

remove

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

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

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

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

findAndModify

public DBObject findAndModify(DBObject query,
                              DBObject fields,
                              DBObject sort,
                              boolean remove,
                              DBObject update,
                              boolean returnNew,
                              boolean upsert)
Finds the first document in the query (sorted) and updates it. If remove is specified it will be removed. If new is specified then the updated document will be returned, otherwise the old document is returned (or it would be lost forever). You can also specify the fields to return in the document, optionally.

Returns:
the found document (before, or after the update)

findAndModify

public DBObject findAndModify(DBObject query,
                              DBObject sort,
                              DBObject update)
Finds the first document in the query (sorted) and updates it.

Returns:
the old document

findAndModify

public DBObject findAndModify(DBObject query,
                              DBObject update)
Finds the first document in the query and updates it.

Returns:
the old document

findAndRemove

public DBObject findAndRemove(DBObject query)
Finds the first document in the query and removes it.

Returns:
the removed document

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

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

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

public final DBCursor find()
Queries for all objects in this collection.

Returns:
a cursor which will iterate over every object
MongoDB Doc Links

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

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 WriteResult save(DBObject jo)
Saves an object to this collection.

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

save

public final WriteResult save(DBObject jo,
                              WriteConcern concern)
                       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

getCount

public long getCount(DBObject query,
                     DBObject fields,
                     long limit,
                     long skip)
              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

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

getStats

public CommandResult getStats()

isCapped

public boolean isCapped()

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(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 WriteConcern for more information.

Parameters:
concern - write concern to use

getWriteConcern

public WriteConcern getWriteConcern()
Get the write concern for this collection.