com.mongodb

Class DB

java.lang.Object

com.mongodb.DB

@ThreadSafe
public 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 Mongo.getDB(String) for further information about the effective deprecation of this class.

See Also:

MongoClient

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[] password) Deprecated. Use DB.command to call either the createUser or updateUser command
WriteResult	addUser(String userName, char[] password, boolean readOnly) Deprecated. Use DB.command to call either the createUser or updateUser command
boolean	collectionExists(String collectionName) Checks to see if a collection with a given name exists on a server.
CommandResult	command(DBObject command) Executes a database command.
CommandResult	command(DBObject command, DBEncoder encoder) Executes a database command.
CommandResult	command(DBObject command, com.mongodb.ReadPreference readPreference) Executes the command against the database with the given read preference.
CommandResult	command(DBObject command, com.mongodb.ReadPreference readPreference, DBEncoder encoder) Executes a database command with the selected readPreference, and encodes the command using the given encoder.
CommandResult	command(String command) Executes a database command.
CommandResult	command(String command, com.mongodb.ReadPreference readPreference) Executes a database command.
DBCollection	createCollection(String collectionName, DBObject options) Creates a collection with a given name and options.
DBCollection	createView(String viewName, String viewOn, List<? extends DBObject> pipeline) Creates a view with the given name, backing collection/view name, and aggregation pipeline that defines the view.
DBCollection	createView(String viewName, String viewOn, List<? extends DBObject> pipeline, DBCreateViewOptions options) Creates a view with the given name, backing collection/view name, aggregation pipeline, and options that defines the view.
CommandResult	doEval(String code, Object... args) Evaluates JavaScript functions on the database server.
protected DBCollection	doGetCollection(String name) Gets a collection with a given name.
void	dropDatabase() Drops this database.
Object	eval(String code, Object... args) Calls doEval(java.lang.String, java.lang.Object[]).
DBCollection	getCollection(String name) Gets a collection with a given name.
DBCollection	getCollectionFromString(String collectionName) Returns a collection matching a given string.
Set<String>	getCollectionNames() Returns a set containing the names of all collections in this database.
Mongo	getMongo() Gets the Mongo instance
String	getName() Returns the name of this database.
int	getOptions() Gets the query options
com.mongodb.ReadConcern	getReadConcern() Get the read concern for this database.
com.mongodb.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.
com.mongodb.WriteConcern	getWriteConcern() Gets the write concern for this database.
WriteResult	removeUser(String userName) Deprecated. Use DB.command to call the dropUser command
void	resetOptions() Resets the query options.
void	setOptions(int options) Sets the query options, overwriting previous value.
void	setReadConcern(com.mongodb.ReadConcern readConcern) Sets the read concern for this database.
void	setReadPreference(com.mongodb.ReadPreference readPreference) Sets the read preference for this database.
void	setWriteConcern(com.mongodb.WriteConcern writeConcern) Sets the write concern for this database.
void	slaveOk() Deprecated. Replaced with ReadPreference.secondaryPreferred()
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

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 - must not be empty and cannot contain spaces

Method Detail

getMongo

public Mongo getMongo()

Gets the Mongo instance

Returns:

the mongo instance that this database was created from.

setReadPreference

public void setReadPreference(com.mongodb.ReadPreference readPreference)

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:

readPreference - ReadPreference to use

setWriteConcern

public void setWriteConcern(com.mongodb.WriteConcern writeConcern)

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:

writeConcern - WriteConcern to use

getReadPreference

public com.mongodb.ReadPreference getReadPreference()

Gets the read preference for this database.

Returns:

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

getWriteConcern

public com.mongodb.WriteConcern getWriteConcern()

Gets the write concern for this database.

Returns:

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

setReadConcern

public void setReadConcern(com.mongodb.ReadConcern readConcern)

Sets the read concern for this database.

Parameters:

readConcern - the read concern to use for this collection

Since:

3.3

getReadConcern

public com.mongodb.ReadConcern getReadConcern()

Get the read concern for this database.

Returns:

the ReadConcern

Since:

3.3

doGetCollection

protected 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

Throws:

IllegalArgumentException - if the name is invalid

See Also:

MongoNamespace.checkCollectionNameValidity(String)

getCollection

public DBCollection getCollection(String name)

Gets a collection with a given name.

Parameters:

name - the name of the collection to return

Returns:

the collection

Throws:

IllegalArgumentException - if the name is invalid

See Also:

MongoNamespace.checkCollectionNameValidity(String)

dropDatabase

public void dropDatabase()

Drops this database. Removes all data on disk. Use with caution.

Throws:

MongoException - if the operation failed

getCollectionFromString

public DBCollection getCollectionFromString(String collectionName)

Returns a collection matching a given string.

Parameters:

collectionName - the name of the collection

Returns:

the collection

getName

public String getName()

Returns the name of this database.

Returns:

the name

getCollectionNames

public Set<String> getCollectionNames()

Returns a set containing the names of all collections in this database.

Returns:

the names of collections in this database

Throws:

MongoException - if the operation failed

createCollection

public DBCollection createCollection(String collectionName,
                            DBObject options)

Creates a collection with a given name and options. If the collection already exists, this throws a CommandFailureException.

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:

collectionName - the name of the collection to return

options - options

Returns:

the collection

Throws:

MongoCommandException - if the server is unable to create the collection

WriteConcernException - if the WriteConcern specified on this DB could not be satisfied

MongoException - for all other failures

createView

public DBCollection createView(String viewName,
                      String viewOn,
                      List<? extends DBObject> pipeline)

Creates a view with the given name, backing collection/view name, and aggregation pipeline that defines the view.

Parameters:

viewName - the name of the view to create

viewOn - the backing collection/view for the view

pipeline - the pipeline that defines the view

Returns:

the view as a DBCollection

Throws:

MongoCommandException - if the server is unable to create the collection

WriteConcernException - if the WriteConcern specified on this DB could not be satisfied

MongoException - for all other failures

Since:

3.4

createView

public DBCollection createView(String viewName,
                      String viewOn,
                      List<? extends DBObject> pipeline,
                      DBCreateViewOptions options)

Creates a view with the given name, backing collection/view name, aggregation pipeline, and options that defines the view.

Parameters:

viewName - the name of the view to create

viewOn - the backing collection/view for the view

pipeline - the pipeline that defines the view

options - the options for creating the view

Returns:

the view as a DBCollection

Throws:

MongoCommandException - if the server is unable to create the collection

WriteConcernException - if the WriteConcern specified on this DB could not be satisfied

MongoException - for all other failures

Since:

3.4

command

public CommandResult command(String command)

Executes a database command. This method constructs a simple DBObject using command as the field name and true as its value, and calls command(DBObject, ReadPreference) with the default read preference for the database.

Parameters:

command - command to execute

Returns:

result of command from the database

Throws:

MongoException - if the command failed

command

public CommandResult command(DBObject command)

Executes a database command. This method calls command(DBObject, ReadPreference) with the default read preference for the database.

Parameters:

command - DBObject representation of the command to be executed

Returns:

result of the command execution

Throws:

MongoException - if the command failed

command

public CommandResult command(DBObject command,
                    DBEncoder encoder)

Executes a database command. This method calls command(DBObject, ReadPreference, DBEncoder) with the default read preference for the database.

Parameters:

command - DBObject representation of the command to be executed

encoder - DBEncoder to be used for command encoding

Returns:

result of the command execution

Throws:

MongoException - if the command failed

command

public CommandResult command(DBObject command,
                    com.mongodb.ReadPreference readPreference,
                    DBEncoder encoder)

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

Parameters:

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

Returns:

The result of executing the command, success or failure

Since:

2.12

command

public CommandResult command(DBObject command,
                    com.mongodb.ReadPreference readPreference)

Executes the command against the database with the given read preference.

Parameters:

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

command

public CommandResult command(String command,
                    com.mongodb.ReadPreference readPreference)

Executes a database command. This method constructs a simple DBObject and calls command(DBObject, ReadPreference).

Parameters:

command - 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 - if the command failed

Since:

2.12

getSisterDB

public DB getSisterDB(String name)

Gets another database on same server

Parameters:

name - name of the database

Returns:

the DB for the given name

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 - if the operation failed

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 - String representation of JavaScript function

args - arguments to pass to the JavaScript function

Returns:

result of the command execution

Throws:

MongoException - if the operation failed

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 - String representation of JavaScript function

args - arguments to pass to the JavaScript function

Returns:

result of the execution

Throws:

MongoException - if the operation failed

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 - if the operation failed

addUser

@Deprecated
public WriteResult addUser(String userName,
                             char[] password)

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

Adds or updates a user for this database

Parameters:

userName - the user name

password - the password

Returns:

the result of executing this operation

Throws:

MongoException - if the operation failed

addUser

@Deprecated
public WriteResult addUser(String userName,
                             char[] password,
                             boolean readOnly)

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

Adds or updates a user for this database

Parameters:

userName - the user name

password - the password

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

Returns:

the result of executing this operation

Throws:

MongoException - if the operation failed

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 - if the operation failed

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 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 query options

Returns:

bit vector of query options

toString

public String toString()

Overrides:

toString in class Object