com.mongodb

Class DB

java.lang.Object

com.mongodb.DB

Direct Known Subclasses:

DBApiLayer

public abstract class DB
extends Object

A thread-safe client view of a logical database in a MongoDB cluster. A DB instance can be achieved from a MongoClient instance using code like:

 MongoClient mongoClient = new MongoClient();
 DB db = mongoClient.getDB("<db name>");
 

See Also:

MongoClient

MongoDB documentation

Database

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	_readOnly Deprecated. See setReadOnly(Boolean)

Constructor Summary

Constructors

Constructor and Description
DB(Mongo mongo, String name) Constructs a new instance of the DB.

Method Summary

Methods

Modifier and Type	Method and Description
void	addOption(int option) Adds the given flag to the default query options.
WriteResult	addUser(String username, char[] passwd) Deprecated. Use DB.command to call either the addUser or updateUser command
WriteResult	addUser(String username, char[] passwd, boolean readOnly) Deprecated. Use DB.command to call either the addUser or updateUser command
boolean	authenticate(String username, char[] password) Deprecated. Please use MongoClient.MongoClient(java.util.List, java.util.List) to create a client, which will authenticate all connections to server
CommandResult	authenticateCommand(String username, char[] password) Deprecated. Please use MongoClient.MongoClient(java.util.List, java.util.List) to create a client, which will authenticate all connections to server
abstract void	cleanCursors(boolean force) Deprecated. Clients should ensure that DBCursor.close() is called.
boolean	collectionExists(String collectionName) Checks to see if a collection with a given name exists on a server.
CommandResult	command(DBObject cmd) Executes a database command.
CommandResult	command(DBObject cmd, DBEncoder encoder) Executes a database command.
CommandResult	command(DBObject cmd, int options) Deprecated. Use command(DBObject, ReadPreference) instead. This method will be removed in 3.0.
CommandResult	command(DBObject cmd, int options, DBEncoder encoder) Deprecated. Use command(DBObject, ReadPreference, DBEncoder) instead. This method will be removed in 3.0.
CommandResult	command(DBObject cmd, int options, ReadPreference readPreference) Deprecated. Use command(DBObject, ReadPreference) instead. This method will be removed in 3.0.
CommandResult	command(DBObject cmd, int options, ReadPreference readPreference, DBEncoder encoder) Deprecated. Use command(DBObject, ReadPreference, DBEncoder) instead. This method will be removed in 3.0.
CommandResult	command(DBObject cmd, ReadPreference readPreference) Executes the command against the database with the given read preference.
CommandResult	command(DBObject cmd, ReadPreference readPreference, DBEncoder encoder) Executes a database command with the selected readPreference, and encodes the command using the given encoder.
CommandResult	command(String cmd) Executes a database command.
CommandResult	command(String cmd, int options) Deprecated. Use command(String, ReadPreference) instead. This method will be removed in 3.0.
CommandResult	command(String cmd, ReadPreference readPreference) 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 JavaScript functions on the database server.
protected abstract DBCollection	doGetCollection(String name) Gets a collection with a given name.
void	dropDatabase() Drops this database, deleting the associated data files.
Object	eval(String code, Object... args) Calls doEval(java.lang.String, java.lang.Object[]).
void	forceError() Deprecated. The getlasterror command will not be supported in future versions of MongoDB. Use acknowledged writes instead.
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 all collections in the existing database.
CommandResult	getLastError() Deprecated. The getlasterror command will not be supported in future versions of MongoDB. Use acknowledged writes instead.
CommandResult	getLastError(int w, int wtimeout, boolean fsync) Deprecated. The getlasterror command will not be supported in future versions of MongoDB. Use acknowledged writes instead.
CommandResult	getLastError(WriteConcern concern) Deprecated. The getlasterror command will not be supported in future versions of MongoDB. Use acknowledged writes instead.
Mongo	getMongo() Gets the Mongo instance
String	getName() Returns the name of this database.
int	getOptions() Gets the default query options
CommandResult	getPreviousError() Deprecated. The getlasterror command will not be supported in future versions of MongoDB. Use acknowledged writes instead.
ReadPreference	getReadPreference() Gets the read preference for this database.
DB	getSisterDB(String name) Gets another database on same server
CommandResult	getStats() Helper method for calling a 'dbStats' command.
WriteConcern	getWriteConcern() Gets the write concern for this database.
boolean	isAuthenticated() Deprecated. Please use MongoClient.MongoClient(java.util.List, java.util.List) to create a client, which will authenticate all connections to server
WriteResult	removeUser(String username) Deprecated. Use DB.command to call the dropUser command
abstract void	requestDone() Ends the current 'consistent request'.
abstract void	requestEnsureConnection() Ensure that a connection is assigned to the current 'consistent request' (from primary pool, if connected to a replica set)
abstract void	requestStart() Starts a new 'consistent request'.
void	resetError() Deprecated. The getlasterror command will not be supported in future versions of MongoDB. Use acknowledged writes instead.
void	resetOptions() Resets the query options.
void	setOptions(int options) Sets the default query options, overwriting previous value.
void	setReadOnly(Boolean b) Deprecated. Avoid making database read-only via this method. Connect with a user credentials that has a read-only access to a server instead.
void	setReadPreference(ReadPreference preference) Sets the read preference for this database.
void	setWriteConcern(WriteConcern concern) Sets the write concern for this database.
void	slaveOk() Deprecated. Replaced with ReadPreference.secondaryPreferred()
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

@Deprecated
protected boolean _readOnly

Deprecated. See setReadOnly(Boolean)

Constructor Detail

DB

public DB(Mongo mongo,
  String name)

Constructs a new instance of the DB.

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 will 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' (from primary pool, if connected to a replica set)

doGetCollection

protected abstract DBCollection doGetCollection(String name)

Gets a collection with a given name. If the collection does not exist, a new collection is created.

This class is NOT part of the public API. Be prepared for non-binary compatible changes in minor releases.

Parameters:

name - the name of the collection

Returns:

the collection

getCollection

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

Possible options:

• capped (boolean) - Enables a collection cap. False by default. If enabled, you must specify a size parameter.
• size (int) - If capped is true, size specifies a maximum size in bytes for the capped collection. When capped is false, you may use size to preallocate space.
• max (int) - Optional. Specifies a maximum "cap" in number of documents for capped collections. You must also specify size when specifying max.

Note that if the options parameter is null, the creation will be deferred to when the collection is written to.

Parameters:

name - the name of the collection to return

options - options

Returns:

the collection

Throws:

MongoException

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)

Executes a database command. This method calls command(DBObject, int) } with 0 as query option.

Parameters:

cmd - DBObject representation of the command to be executed

Returns:

result of the command execution

Throws:

MongoException

MongoDB documentation

Commands

command

public CommandResult command(DBObject cmd,
                    DBEncoder encoder)

Executes a database command. This method calls command(com.mongodb.DBObject, int, com.mongodb.DBEncoder) with 0 as query option.

Parameters:

cmd - DBObject representation of the command to be executed

encoder - DBEncoder to be used for command encoding

Returns:

result of the command execution

Throws:

MongoException

MongoDB documentation

Commands

command

@Deprecated
public CommandResult command(DBObject cmd,
                               int options,
                               DBEncoder encoder)

Deprecated. Use command(DBObject, ReadPreference, DBEncoder) instead. This method will be removed in 3.0.

Executes a database command. This method calls command(com.mongodb.DBObject, int, com.mongodb.ReadPreference, com.mongodb.DBEncoder) with the database default read preference. The only option used by this method was "slave ok", therefore this method has been replaced with command(DBObject, ReadPreference, DBEncoder).

Parameters:

cmd - DBObject representation the command to be executed

options - query options to use

encoder - DBEncoder to be used for command encoding

Returns:

result of the command execution

Throws:

MongoException

MongoDB documentation

Commands

command

@Deprecated
public CommandResult command(DBObject cmd,
                               int options,
                               ReadPreference readPreference)

Deprecated. Use command(DBObject, ReadPreference) instead. This method will be removed in 3.0.

Executes a database command. This method calls command(com.mongodb.DBObject, int, com.mongodb.ReadPreference, com.mongodb.DBEncoder) with a default encoder. The only option used by this method was "slave ok", therefore this method has been replaced with command(DBObject, ReadPreference).

Parameters:

cmd - A DBObject representation the command to be executed

options - The query options to use

readPreference - The ReadPreference for this command (nodes selection is the biggest part of this)

Returns:

result of the command execution

Throws:

MongoException

MongoDB documentation

Commands

command

@Deprecated
public CommandResult command(DBObject cmd,
                               int options,
                               ReadPreference readPreference,
                               DBEncoder encoder)

Deprecated. Use command(DBObject, ReadPreference, DBEncoder) instead. This method will be removed in 3.0.

Executes a database command. The only option used by this method was "slave ok", therefore this method has been replaced with command(DBObject, ReadPreference, DBEncoder).

Parameters:

cmd - A DBObject representation the command to be executed

options - The query options to use

readPreference - The ReadPreference for this command (nodes selection is the biggest part of this)

encoder - A DBEncoder to be used for command encoding

Returns:

result of the command execution

Throws:

MongoException

MongoDB documentation

Commands

command

public CommandResult command(DBObject cmd,
                    ReadPreference readPreference,
                    DBEncoder encoder)

Executes a database command with the selected readPreference, and encodes the command using the given encoder.

Parameters:

cmd - The DBObject representation the command to be executed

readPreference - Where to execute the command - this will only be applied for a subset of commands

encoder - The DBEncoder that knows how to serialise the cmd

Returns:

The result of executing the command, success or failure

Since:

2.12

MongoDB documentation

Commands

command

@Deprecated
public CommandResult command(DBObject cmd,
                               int options)

Deprecated. Use command(DBObject, ReadPreference) instead. This method will be removed in 3.0.

Executes a database command with the given query options. The only option used by this method was "slave ok", therefore this method has been replaced with command(DBObject, ReadPreference).

Parameters:

cmd - The DBObject representation the command to be executed

options - The query options to use

Returns:

The result of the command execution

Throws:

MongoException

MongoDB documentation

Commands

command

public CommandResult command(DBObject cmd,
                    ReadPreference readPreference)

Executes the command against the database with the given read preference. This method is the preferred way of setting read preference, use this instead of command(com.mongodb.DBObject, int)

Parameters:

cmd - The DBObject representation the command to be executed

readPreference - Where to execute the command - this will only be applied for a subset of commands

Returns:

The result of executing the command, success or failure

Since:

2.12

MongoDB documentation

Commands

command

public CommandResult command(String cmd)

Executes a database command. This method constructs a simple dbobject and calls command(com.mongodb.DBObject)

Parameters:

cmd - name of the command to be executed

Returns:

result of the command execution

Throws:

MongoException

MongoDB documentation

Commands

command

@Deprecated
public CommandResult command(String cmd,
                               int options)

Deprecated. Use command(String, ReadPreference) instead. This method will be removed in 3.0.

Executes a database command. This method constructs a simple dbobject and calls command(com.mongodb.DBObject, int)

Parameters:

cmd - name of the command to be executed

options - query options to use

Returns:

result of the command execution

Throws:

MongoException

MongoDB documentation

Commands

command

public CommandResult command(String cmd,
                    ReadPreference readPreference)

Executes a database command. This method constructs a simple dbobject and calls command(com.mongodb.DBObject, int, com.mongodb.ReadPreference). The only option used by this method was "slave ok", therefore this method has been replaced with command(DBObject, ReadPreference).

Parameters:

cmd - The name of the command to be executed

readPreference - Where to execute the command - this will only be applied for a subset of commands

Returns:

The result of the command execution

Throws:

MongoException

Since:

2.12

MongoDB documentation

Commands

doEval

public CommandResult doEval(String code,
                   Object... args)

Evaluates JavaScript functions on the database server. This is useful if you need to touch a lot of data lightly, in which case network transfer could be a bottleneck.

Parameters:

code - @{code String} representation of JavaScript function

args - arguments to pass to the JavaScript function

Returns:

result of the command execution

Throws:

MongoException

eval

public Object eval(String code,
          Object... args)

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 - @{code String} representation of JavaScript function

args - arguments to pass to the JavaScript function

Returns:

result of the execution

Throws:

MongoException

getStats

public CommandResult getStats()

Helper method for calling a 'dbStats' command. It returns storage statistics for a given database.

Returns:

result of the execution

Throws:

MongoException

getName

public String getName()

Returns the name of this database.

Returns:

the name

setReadOnly

@Deprecated
public void setReadOnly(Boolean b)

Deprecated. Avoid making database read-only via this method. Connect with a user credentials that has a read-only access to a server instead.

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

Returns a set containing all collections in the existing database.

Returns:

an set of names

Throws:

MongoException

collectionExists

public boolean collectionExists(String collectionName)

Checks to see if a collection with a given name exists on a server.

Parameters:

collectionName - a name of 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

Throws:

MongoException

toString

public String toString()

Returns the name of this database.

Overrides:

toString in class Object

Returns:

the name

getLastError

@Deprecated
public CommandResult getLastError()

Deprecated. The getlasterror command will not be supported in future versions of MongoDB. Use acknowledged writes instead.

Returns the error status of the last operation on the current 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() It is better not to call this method directly but instead use WriteConcern

Returns:

DBObject with error and status information

Throws:

MongoException

See Also:

WriteConcern.ACKNOWLEDGED

getLastError

@Deprecated
public CommandResult getLastError(WriteConcern concern)

Deprecated. The getlasterror command will not be supported in future versions of MongoDB. Use acknowledged writes instead.

Returns the error status of the last operation on the current connection.

Parameters:

concern - a WriteConcern to be used while checking for the error status.

Returns:

DBObject with error and status information

Throws:

MongoException

See Also:

WriteConcern.ACKNOWLEDGED

getLastError

@Deprecated
public CommandResult getLastError(int w,
                                    int wtimeout,
                                    boolean fsync)

Deprecated. The getlasterror command will not be supported in future versions of MongoDB. Use acknowledged writes instead.

Returns the error status of the last operation on the current connection.

Parameters:

w - when running with replication, this is the number of servers to replicate to before returning. A w value of 1 indicates the primary only. A w value of 2 includes the primary and at least one secondary, etc. In place of a number, you may also set w to majority to indicate that the command should wait until the latest write propagates to a majority of replica set members. If using w, you should also use wtimeout. Specifying a value for w without also providing a wtimeout may cause getLastError to block indefinitely.

wtimeout - a value in milliseconds that controls how long to wait for write propagation to complete. If replication does not complete in the given timeframe, the getLastError command will return with an error status.

fsync - if true, wait for mongod to write this data to disk before returning. Defaults to false.

Returns:

DBObject with error and status information

Throws:

MongoException

See Also:

WriteConcern.ACKNOWLEDGED

setWriteConcern

public void setWriteConcern(WriteConcern concern)

Sets the write concern for this database. It will be used for write operations to any collection in this database. See the documentation for WriteConcern for more information.

Parameters:

concern - WriteConcern to use

getWriteConcern

public WriteConcern getWriteConcern()

Gets the write concern for this database.

Returns:

WriteConcern to be used for write operations, if not specified explicitly

setReadPreference

public void setReadPreference(ReadPreference preference)

Sets the read preference for this database. Will be used as default for read operations from any collection in this database. See the documentation for ReadPreference for more information.

Parameters:

preference - ReadPreference to use

getReadPreference

public ReadPreference getReadPreference()

Gets the read preference for this database.

Returns:

ReadPreference to be used for read operations, if not specified explicitly

dropDatabase

public void dropDatabase()

Drops this database, deleting the associated data files. Use with caution.

Throws:

MongoException

isAuthenticated

@Deprecated
public boolean isAuthenticated()

Deprecated. Please use MongoClient.MongoClient(java.util.List, java.util.List) to create a client, which will authenticate all connections to server

Returns true if a user has been authenticated on this database.

Returns:

true if authenticated, false otherwise

MongoDB documentation

authenticate

authenticate

@Deprecated
public boolean authenticate(String username,
                              char[] password)

Deprecated. Please use MongoClient.MongoClient(java.util.List, java.util.List) to create a client, which will authenticate all connections to server

Authenticates to db with the given credentials. If this method (or authenticateCommand) has already been called with the same credentials and the authentication test succeeded, this method will return true. If this method has already been called with different credentials and the authentication test succeeded, this method will throw an IllegalStateException. If this method has already been called with any credentials and the authentication test failed, this method will re-try the authentication test with the given credentials.

Parameters:

username - name of user for this database

password - password of user for this database

Returns:

true if authenticated, false otherwise

Throws:

MongoException - if authentication failed due to invalid user/pass, or other exceptions like I/O

IllegalStateException - if authentication test has already succeeded with different credentials

See Also:

authenticateCommand(String, char[])

MongoDB documentation

authenticate

authenticateCommand

@Deprecated
public CommandResult authenticateCommand(String username,
                                           char[] password)

Deprecated. Please use MongoClient.MongoClient(java.util.List, java.util.List) to create a client, which will authenticate all connections to server

Authenticates to db with the given credentials. If this method (or authenticate) has already been called with the same credentials and the authentication test succeeded, this method will return true. If this method has already been called with different credentials and the authentication test succeeded, this method will throw an IllegalStateException. If this method has already been called with any credentials and the authentication test failed, this method will re-try the authentication test with the given credentials.

Parameters:

username - name of user for this database

password - 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

IllegalStateException - if authentication test has already succeeded with different credentials

See Also:

authenticate(String, char[])

MongoDB documentation

authenticate

addUser

@Deprecated
public WriteResult addUser(String username,
                             char[] passwd)

Deprecated. Use DB.command to call either the addUser or updateUser command

Adds or updates a user for this database

Parameters:

username - the user name

passwd - the password

Returns:

the result of executing this operation

Throws:

MongoException

MongoDB documentation

Access Control

addUser

@Deprecated
public WriteResult addUser(String username,
                             char[] passwd,
                             boolean readOnly)

Deprecated. Use DB.command to call either the addUser or updateUser command

Adds or updates a user for this database

Parameters:

username - the user name

passwd - the password

readOnly - if true, user will only be able to read

Returns:

the result of executing this operation

Throws:

MongoException

MongoDB documentation

Access Control

removeUser

@Deprecated
public WriteResult removeUser(String username)

Deprecated. Use DB.command to call the dropUser command

Removes the specified user from the database.

Parameters:

username - user to be removed

Returns:

the result of executing this operation

Throws:

MongoException

MongoDB documentation

Access Control

getPreviousError

@Deprecated
public CommandResult getPreviousError()

Deprecated. The getlasterror command will not be supported in future versions of MongoDB. Use acknowledged writes instead.

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

See Also:

WriteConcern.ACKNOWLEDGED

resetError

@Deprecated
public void resetError()

Deprecated. The getlasterror command will not be supported in future versions of MongoDB. Use acknowledged writes instead.

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

Throws:

MongoException

See Also:

WriteConcern.ACKNOWLEDGED

forceError

@Deprecated
public void forceError()

Deprecated. The getlasterror command will not be supported in future versions of MongoDB. Use acknowledged writes instead.

For testing purposes only - this method forces an error to help test error handling

Throws:

MongoException

See Also:

WriteConcern.ACKNOWLEDGED

getMongo

public Mongo getMongo()

Gets the Mongo instance

Returns:

the instance of Mongo this database belongs to

getSisterDB

public DB getSisterDB(String name)

Gets another database on same server

Parameters:

name - name of the database

Returns:

the database

slaveOk

@Deprecated
public void slaveOk()

Deprecated. Replaced with ReadPreference.secondaryPreferred()

Makes it possible to execute "read" queries on a slave node

See Also:

ReadPreference.secondaryPreferred()

addOption

public void addOption(int option)

Adds the given flag to the default query options.

Parameters:

option - value to be added

setOptions

public void setOptions(int options)

Sets the default query options, overwriting previous value.

Parameters:

options - bit vector of query options

resetOptions

public void resetOptions()

Resets the query options.

getOptions

public int getOptions()

Gets the default query options

Returns:

bit vector of query options

cleanCursors

@Deprecated
public abstract void cleanCursors(boolean force)

Deprecated. Clients should ensure that DBCursor.close() is called.

Forcefully kills any cursors leaked by neglecting to call DBCursor.close

Parameters:

force - true if should clean regardless of number of dead cursors

See Also:

DBCursor.close()