com.mongodb
Class DB

java.lang.Object
  extended by com.mongodb.DB
Direct Known Subclasses:
DBApiLayer

public abstract class DB
extends Object

an abstract class that represents a logical database on a server


MongoDB Doc Links

Field Summary
protected  boolean _readOnly
           
 
Constructor Summary
DB(Mongo mongo, String name)
           
 
Method Summary
 void addOption(int option)
          Adds the give option
 WriteResult addUser(String username, char[] passwd)
          Adds a new user for this db
 WriteResult addUser(String username, char[] passwd, boolean readOnly)
          Adds a new user for this db
 boolean authenticate(String username, char[] passwd)
          Authenticates to db with the given name and password
 CommandResult authenticateCommand(String username, char[] passwd)
          Authenticates to db with the given name and password
abstract  void cleanCursors(boolean force)
           
 boolean collectionExists(String collectionName)
          Checks to see if a collection by name %lt;name> exists.
 CommandResult command(DBObject cmd)
          Executes a database command.
 CommandResult command(DBObject cmd, int options)
          Executes a database command.
 CommandResult command(String cmd)
          Executes a database command.
 CommandResult command(String cmd, int options)
          Executes a database command.
 DBCollection createCollection(String name, DBObject options)
          Creates a collection with a given name and options.
 CommandResult doEval(String code, Object... args)
          evaluates a function on the database.
protected abstract  DBCollection doGetCollection(String name)
          Returns the collection represented by the string <dbName>.<collectionName>.
 void dropDatabase()
          Drops this database.
 Object eval(String code, Object... args)
          calls doEval(java.lang.String, java.lang.Object[]).
 void forceError()
          For testing purposes only - this method forces an error to help test error handling
 DBCollection getCollection(String name)
          Gets a collection with a given name.
 DBCollection getCollectionFromString(String s)
          Returns a collection matching a given string.
 Set<String> getCollectionNames()
          Returns a set containing the names of all collections in this database.
 CommandResult getLastError()
          Gets the the error (if there is one) from the previous operation on this connection.
 CommandResult getLastError(int w, int wtimeout, boolean fsync)
           
 CommandResult getLastError(WriteConcern concern)
           
 Mongo getMongo()
          Gets the Mongo instance
 String getName()
          Returns the name of this database.
 int getOptions()
          Gets the query options
 CommandResult getPreviousError()
          Returns the last error that occurred since start of database or a call to resetError() The return object will look like
 DB getSisterDB(String name)
          Gets another database on same server
 CommandResult getStats()
          Returns the result of "dbstats" command
 WriteConcern getWriteConcern()
          Gets the write concern for this database.
 boolean isAuthenticated()
          Returns true if a user has been authenticated
 WriteResult removeUser(String username)
          Removes a user for this db
abstract  void requestDone()
          ends the current "consistent request"
abstract  void requestEnsureConnection()
          ensure that a connection is assigned to the current "consistent request"
abstract  void requestStart()
          starts a new "consistent request".
 void resetError()
          Resets the error memory for this database.
 void resetOptions()
          Resets the query options
 void setOptions(int options)
          Sets the query options
 void setReadOnly(Boolean b)
          Makes this database read-only.
 void setWriteConcern(WriteConcern concern)
          Sets the write concern for this database.
 void slaveOk()
          Makes it possible to execute "read" queries on a slave node
 String toString()
          Returns the name of this database.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

_readOnly

protected boolean _readOnly
Constructor Detail

DB

public DB(Mongo mongo,
          String name)
Parameters:
mongo - the mongo instance
name - the database name
Method Detail

requestStart

public abstract void requestStart()
starts a new "consistent request". Following this call and until requestDone() is called, all db operations should use the same underlying connection. This is useful to ensure that operations happen in a certain order with predictable results.


requestDone

public abstract void requestDone()
ends the current "consistent request"


requestEnsureConnection

public abstract void requestEnsureConnection()
ensure that a connection is assigned to the current "consistent request"


doGetCollection

protected abstract DBCollection doGetCollection(String name)
Returns the collection represented by the string <dbName>.<collectionName>.

Parameters:
name - the name of the collection
Returns:
the collection

getCollection

public final DBCollection getCollection(String name)
Gets a collection with a given name. If the collection does not exist, a new collection is created.

Parameters:
name - the name of the collection to return
Returns:
the collection

createCollection

public final DBCollection createCollection(String name,
                                           DBObject options)
Creates a collection with a given name and options. If the collection does not exist, a new collection is created. Note that if the options parameter is null, the creation will be deferred to when the collection is written to. Possible options:
capped
boolean: if the collection is capped
size
int: collection size (in bytes)
max
int: max number of documents

Parameters:
name - the name of the collection to return
options - options
Returns:
the collection

getCollectionFromString

public DBCollection getCollectionFromString(String s)
Returns a collection matching a given string.

Parameters:
s - the name of the collection
Returns:
the collection

command

public CommandResult command(DBObject cmd)
                      throws MongoException
Executes a database command. This method calls command(com.mongodb.DBObject, int) with 0 as query option.

Parameters:
cmd - dbobject representing the command to execute
Returns:
result of command from the database
Throws:
MongoException
See Also:
List of Commands
MongoDB Doc Links

command

public CommandResult command(DBObject cmd,
                             int options)
                      throws MongoException
Executes a database command.

Parameters:
cmd - dbobject representing the command to execute
options - query options to use
Returns:
result of command from the database
Throws:
MongoException
See Also:
List of Commands
MongoDB Doc Links

command

public CommandResult command(String cmd)
                      throws MongoException
Executes a database command. This method constructs a simple dbobject and calls command(com.mongodb.DBObject)

Parameters:
cmd - command to execute
Returns:
result of command from the database
Throws:
MongoException
See Also:
List of Commands

command

public CommandResult command(String cmd,
                             int options)
                      throws MongoException
Executes a database command. This method constructs a simple dbobject and calls command(com.mongodb.DBObject, int)

Parameters:
cmd - command to execute
options - query options to use
Returns:
result of command from the database
Throws:
MongoException
See Also:
List of Commands

doEval

public CommandResult doEval(String code,
                            Object... args)
                     throws MongoException
evaluates a function on the database. This is useful if you need to touch a lot of data lightly, in which case network transfer could be a bottleneck.

Parameters:
code - the function in javascript code
args - arguments to be passed to the function
Returns:
Throws:
MongoException

eval

public Object eval(String code,
                   Object... args)
            throws MongoException
calls doEval(java.lang.String, java.lang.Object[]). If the command is successful, the "retval" field is extracted and returned. Otherwise an exception is thrown.

Parameters:
code - the function in javascript code
args - arguments to be passed to the function
Returns:
Throws:
MongoException

getStats

public CommandResult getStats()
Returns the result of "dbstats" command

Returns:

getName

public String getName()
Returns the name of this database.

Returns:
the name

setReadOnly

public void setReadOnly(Boolean b)
Makes this database read-only. Important note: this is a convenience setting that is only known on the client side and not persisted.

Parameters:
b - if the database should be read-only

getCollectionNames

public Set<String> getCollectionNames()
                               throws MongoException
Returns a set containing the names of all collections in this database.

Returns:
the names of collections in this database
Throws:
MongoException

collectionExists

public boolean collectionExists(String collectionName)
Checks to see if a collection by name %lt;name> exists.

Parameters:
collectionName - The collection to test for existence
Returns:
false if no collection by that name exists, true if a match to an existing collection was found

toString

public String toString()
Returns the name of this database.

Overrides:
toString in class Object
Returns:
the name

getLastError

public CommandResult getLastError()
                           throws MongoException
Gets the the error (if there is one) from the previous operation on this connection. The result of this command will look like
 { "err" :  errorMessage  , "ok" : 1.0 }
 
The value for errorMessage will be null if no error occurred, or a description otherwise. Important note: when calling this method directly, it is undefined which connection "getLastError" is called on. You may need to explicitly use a "consistent Request", see requestStart() For most purposes it is better not to call this method directly but instead use WriteConcern

Returns:
DBObject with error and status information
Throws:
MongoException

getLastError

public CommandResult getLastError(WriteConcern concern)
                           throws MongoException
Parameters:
concern - the concern associated with "getLastError" call
Returns:
Throws:
MongoException
See Also:
DB#getLastError()}

getLastError

public CommandResult getLastError(int w,
                                  int wtimeout,
                                  boolean fsync)
                           throws MongoException
Parameters:
w -
wtimeout -
fsync -
Returns:
Throws:
MongoException
See Also:
DB#getLastError(com.mongodb.WriteConcern) }

setWriteConcern

public void setWriteConcern(WriteConcern concern)
Sets the write concern for this database. It Will be used for writes to any collection in this database. See the documentation for WriteConcern for more information.

Parameters:
concern - write concern to use

getWriteConcern

public WriteConcern getWriteConcern()
Gets the write concern for this database.

Returns:

dropDatabase

public void dropDatabase()
                  throws MongoException
Drops this database. Removes all data on disk. Use with caution.

Throws:
MongoException

isAuthenticated

public boolean isAuthenticated()
Returns true if a user has been authenticated

Returns:
true if authenticated, false otherwise
MongoDB Doc Links

authenticate

public boolean authenticate(String username,
                            char[] passwd)
                     throws MongoException
Authenticates to db with the given name and password

Parameters:
username - name of user for this database
passwd - password of user for this database
Returns:
true if authenticated, false otherwise
Throws:
MongoException
MongoDB Doc Links

authenticateCommand

public CommandResult authenticateCommand(String username,
                                         char[] passwd)
                                  throws MongoException
Authenticates to db with the given name and password

Parameters:
username - name of user for this database
passwd - password of user for this database
Returns:
the CommandResult from authenticate command
Throws:
MongoException - if authentication failed due to invalid user/pass, or other exceptions like I/O
MongoDB Doc Links

addUser

public WriteResult addUser(String username,
                           char[] passwd)
Adds a new user for this db

Parameters:
username -
passwd -

addUser

public WriteResult addUser(String username,
                           char[] passwd,
                           boolean readOnly)
Adds a new user for this db

Parameters:
username -
passwd -
readOnly - if true, user will only be able to read

removeUser

public WriteResult removeUser(String username)
Removes a user for this db

Parameters:
username -

getPreviousError

public CommandResult getPreviousError()
                               throws MongoException
Returns the last error that occurred since start of database or a call to resetError() The return object will look like
 { err : errorMessage, nPrev : countOpsBack, ok : 1 }
  
The value for errorMessage will be null of no error has occurred, otherwise the error message. The value of countOpsBack will be the number of operations since the error occurred. Care must be taken to ensure that calls to getPreviousError go to the same connection as that of the previous operation. See requestStart() for more information.

Returns:
DBObject with error and status information
Throws:
MongoException

resetError

public void resetError()
                throws MongoException
Resets the error memory for this database. Used to clear all errors such that getPreviousError() will return no error.

Throws:
MongoException

forceError

public void forceError()
                throws MongoException
For testing purposes only - this method forces an error to help test error handling

Throws:
MongoException

getMongo

public Mongo getMongo()
Gets the Mongo instance

Returns:

getSisterDB

public DB getSisterDB(String name)
Gets another database on same server

Parameters:
name - name of the database
Returns:

slaveOk

public void slaveOk()
Makes it possible to execute "read" queries on a slave node


addOption

public void addOption(int option)
Adds the give option

Parameters:
option -

setOptions

public void setOptions(int options)
Sets the query options

Parameters:
options -

resetOptions

public void resetOptions()
Resets the query options


getOptions

public int getOptions()
Gets the query options

Returns:

cleanCursors

public abstract void cleanCursors(boolean force)
                           throws MongoException
Throws:
MongoException