com.mongodb
Class Mongo

java.lang.Object
  com.mongodb.Mongo

public class Mongo
extends Object

A database connection with internal pooling. For most application, you should have 1 Mongo instance for the entire JVM. The following are equivalent, and all connect to the local database running on the default port:

 Mongo mongo1 = new Mongo( "127.0.0.1" );
 Mongo mongo2 = new Mongo( "127.0.0.1", 27017 );
 Mongo mongo3 = new Mongo( new DBAddress( "127.0.0.1", 27017, "test" ) );
 Mongo mongo4 = new Mongo( new ServerAddress( "127.0.0.1") );
 

Mongo instances have connection pooling built in - see the requestStart and requestDone methods for more information. http://www.mongodb.org/display/DOCS/Java+Driver+Concurrency

Connecting to a Replica Pair

You can connect to a replica pair using the Java driver by passing two DBAddresses to the Mongo constructor. For example:

 DBAddress left = new DBAddress("127.0.0.1:27017/test");
 DBAddress right = new DBAddress("127.0.0.1:27018/test");

 Mongo mongo = new Mongo(left, right);
 

If the master of a replica pair goes down, there will be a brief lag before the slave becomes master. Thus, your application should be prepared to catch the exceptions that might be thrown in such a case: IllegalArgumentException, MongoException, and MongoException.Network (depending on when the connection drops).

Once the slave becomes master, the driver will begin using that connection as the master connection and the exceptions will stop being thrown.

Connecting to a Replica Set

You can connect to a replica set using the Java driver by passing several a list if ServerAddress to the Mongo constructor. For example:

 List addrs = new ArrayList();
 addrs.add( new ServerAddress( "127.0.0.1" , 27017 ) );
 addrs.add( new ServerAddress( "127.0.0.1" , 27018 ) );
 addrs.add( new ServerAddress( "127.0.0.1" , 27019 ) );

 Mongo mongo = new Mongo( addrs );
 

By default, all read and write operations will be made on the master. But it's possible to read from the slave(s) by using slaveOk:

 mongo.slaveOk();
 

Nested Class Summary

static class

Mongo.Holder Mongo.Holder can be used as a static place to hold several instances of Mongo.

Field Summary

static int	MAJOR_VERSION
static int	MINOR_VERSION

Constructor Summary

Mongo()
Creates a Mongo instance based on a (single) mongodb node (localhost, default port)

Mongo(List<ServerAddress> replicaSetSeeds)
Creates a Mongo based on a replica set, or pair.

Mongo(List<ServerAddress> replicaSetSeeds, MongoOptions options)
Creates a Mongo based on a replica set, or pair.

Mongo(MongoURI uri)
Creates a Mongo described by a URI.

Mongo(ServerAddress addr)
Creates a Mongo instance based on a (single) mongodb node

Mongo(ServerAddress addr, MongoOptions options)
Creates a Mongo instance based on a (single) mongo node using a given ServerAddress

Mongo(ServerAddress left, ServerAddress right)
Creates a Mongo in paired mode.

Mongo(ServerAddress left, ServerAddress right, MongoOptions options)
Creates a Mongo connection in paired mode.

Mongo(String host)
Creates a Mongo instance based on a (single) mongodb node (default port)

Mongo(String host, int port)
Creates a Mongo instance based on a (single) mongodb node

Mongo(String host, MongoOptions options)
Creates a Mongo instance based on a (single) mongodb node (default port)

Method Summary

void	addOption(int option) adds a default query option
void	close() closes the underlying connector, which in turn closes all open connections.
static DB	connect(DBAddress addr) returns a database object
String	debugString() returns a string representing the hosts used in this Mongo instance
void	dropDatabase(String dbName) Drops the database if it exists.
CommandResult	fsync(boolean async) Forces the master server to fsync the RAM data to disk This is done automatically by the server at intervals, but can be forced for better reliability.
CommandResult	fsyncAndLock() Forces the master server to fsync the RAM data to disk, then lock all writes.
ServerAddress	getAddress() Gets the address of the current master
List<ServerAddress>	getAllAddress() Gets a list of all server addresses used when this Mongo was created
DBTCPConnector	getConnector() Gets the underlying TCP connector
String	getConnectPoint() Gets the current master's hostname
List<String>	getDatabaseNames() gets a list of all database names present on the server
DB	getDB(String dbname) gets a database object
int	getMaxBsonObjectSize() Gets the maximum size for a BSON object supported by the current master server.
MongoOptions	getMongoOptions() Returns the mongo options.
int	getOptions() gets the default query options
ReadPreference	getReadPreference() Gets the default read preference
ReplicaSetStatus	getReplicaSetStatus() Gets the replica set status object
List<ServerAddress>	getServerAddressList() Gets the list of server addresses currently seen by the connector.
Collection<DB>	getUsedDatabases() gets a collection of DBs used by the driver since this Mongo instance was created.
String	getVersion() gets this driver version
WriteConcern	getWriteConcern() Gets the default write concern
boolean	isLocked() Returns true if the database is locked (read-only), false otherwise.
void	resetOptions() reset the default query options
void	setOptions(int options) sets the default query options
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.SECONDARY
String	toString()
DBObject	unlock() Unlocks the database, allowing the write operations to go through.

Methods inherited from class java.lang.Object

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

Field Detail

MAJOR_VERSION

public static final int MAJOR_VERSION

See Also:

Constant Field Values

MINOR_VERSION

public static final int MINOR_VERSION

See Also:

Constant Field Values

Constructor Detail

Mongo

public Mongo()
      throws UnknownHostException,
             MongoException

Creates a Mongo instance based on a (single) mongodb node (localhost, default port)

Throws:

UnknownHostException

MongoException

Mongo

public Mongo(String host)
      throws UnknownHostException,
             MongoException

Creates a Mongo instance based on a (single) mongodb node (default port)

Parameters:

host - server to connect to

Throws:

UnknownHostException - if the database host cannot be resolved

MongoException

Mongo

public Mongo(String host,
             MongoOptions options)
      throws UnknownHostException,
             MongoException

Creates a Mongo instance based on a (single) mongodb node (default port)

Parameters:

host - server to connect to

options - default query options

Throws:

UnknownHostException - if the database host cannot be resolved

MongoException

Mongo

public Mongo(String host,
             int port)
      throws UnknownHostException,
             MongoException

Creates a Mongo instance based on a (single) mongodb node

Parameters:

host - the database's host address

port - the port on which the database is running

Throws:

UnknownHostException - if the database host cannot be resolved

MongoException

Mongo

public Mongo(ServerAddress addr)
      throws MongoException

Creates a Mongo instance based on a (single) mongodb node

Parameters:

addr - the database address

Throws:

MongoException

See Also:

ServerAddress

Mongo

public Mongo(ServerAddress addr,
             MongoOptions options)
      throws MongoException

Creates a Mongo instance based on a (single) mongo node using a given ServerAddress

Parameters:

addr - the database address

options - default query options

Throws:

MongoException

See Also:

ServerAddress

Mongo

public Mongo(ServerAddress left,
             ServerAddress right)
      throws MongoException

Creates a Mongo in paired mode.
This will also work for a replica set and will find all members (the master will be used by default).

Parameters:

left - left side of the pair

right - right side of the pair

Throws:

MongoException

See Also:

ServerAddress

Mongo

public Mongo(ServerAddress left,
             ServerAddress right,
             MongoOptions options)
      throws MongoException

Creates a Mongo connection in paired mode.
This will also work for a replica set and will find all members (the master will be used by default).

Parameters:

left - left side of the pair

right - right side of the pair

options -

Throws:

MongoException

See Also:

ServerAddress

Mongo

public Mongo(List<ServerAddress> replicaSetSeeds)
      throws MongoException

Creates a Mongo based on a replica set, or pair. It will find all members (the master will be used by default).

Parameters:

replicaSetSeeds - Put as many servers as you can in the list and the system will figure out the rest.

Throws:

MongoException

See Also:

ServerAddress

Mongo

public Mongo(List<ServerAddress> replicaSetSeeds,
             MongoOptions options)
      throws MongoException

Creates a Mongo based on a replica set, or pair. It will find all members (the master will be used by default).

Parameters:

replicaSetSeeds - put as many servers as you can in the list. the system will figure the rest out

options - default query options

Throws:

MongoException

See Also:

ServerAddress

Mongo

public Mongo(MongoURI uri)
      throws MongoException,
             UnknownHostException

Creates a Mongo described by a URI. If only one address is used it will only connect to that node, otherwise it will discover all nodes.

Parameters:

uri -

Throws:

MongoException

UnknownHostException

See Also:

examples:

mongodb://127.0.0.1

mongodb://fred:[email protected]/

MongoDB Doc Links

• connections

Method Detail

connect

public static DB connect(DBAddress addr)

returns a database object

Parameters:

addr - the database address

Returns:

getDB

public DB getDB(String dbname)

gets a database object

Parameters:

dbname - the database name

Returns:

getUsedDatabases

public Collection<DB> getUsedDatabases()

gets a collection of DBs used by the driver since this Mongo instance was created. This may include DBs that exist in the client but not yet on the server.

Returns:

getDatabaseNames

public List<String> getDatabaseNames()
                              throws MongoException

gets a list of all database names present on the server

Returns:

Throws:

MongoException

dropDatabase

public void dropDatabase(String dbName)
                  throws MongoException

Drops the database if it exists.

Parameters:

dbName - name of database to drop

Throws:

MongoException

getVersion

public String getVersion()

gets this driver version

Returns:

debugString

public String debugString()

returns a string representing the hosts used in this Mongo instance

Returns:

getConnectPoint

public String getConnectPoint()

Gets the current master's hostname

Returns:

getConnector

public DBTCPConnector getConnector()

Gets the underlying TCP connector

Returns:

getReplicaSetStatus

public ReplicaSetStatus getReplicaSetStatus()

Gets the replica set status object

Returns:

getAddress

public ServerAddress getAddress()

Gets the address of the current master

Returns:

the address

getAllAddress

public List<ServerAddress> getAllAddress()

Gets a list of all server addresses used when this Mongo was created

Returns:

getServerAddressList

public List<ServerAddress> getServerAddressList()

Gets the list of server addresses currently seen by the connector. This includes addresses auto-discovered from a replica set.

Returns:

close

public void close()

closes the underlying connector, which in turn closes all open connections. Once called, this Mongo instance can no longer be used.

setWriteConcern

public void setWriteConcern(WriteConcern concern)

Sets the write concern for this database. Will be used as default for writes to any collection in any database. See the documentation for WriteConcern for more information.

Parameters:

concern - write concern to use

getWriteConcern

public WriteConcern getWriteConcern()

Gets the default write concern

Returns:

setReadPreference

public void setReadPreference(ReadPreference preference)

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

Parameters:

preference - Read Preference to use

getReadPreference

public ReadPreference getReadPreference()

Gets the default read preference

Returns:

slaveOk

@Deprecated
public void slaveOk()

Deprecated. Replaced with ReadPreference.SECONDARY

makes it possible to run read queries on slave nodes

See Also:

com.mongodb.ReadPreference.SECONDARY

addOption

public void addOption(int option)

adds a default query option

Parameters:

option -

setOptions

public void setOptions(int options)

sets the default query options

Parameters:

options -

resetOptions

public void resetOptions()

reset the default query options

getOptions

public int getOptions()

gets the default query options

Returns:

getMongoOptions

public MongoOptions getMongoOptions()

Returns the mongo options.

getMaxBsonObjectSize

public int getMaxBsonObjectSize()

Gets the maximum size for a BSON object supported by the current master server. Note that this value may change over time depending on which server is master. If the size is not known yet, a request may be sent to the master server

Returns:

the maximum size

fsync

public CommandResult fsync(boolean async)

Forces the master server to fsync the RAM data to disk This is done automatically by the server at intervals, but can be forced for better reliability.

Parameters:

async - if true, the fsync will be done asynchronously on the server.

Returns:

fsyncAndLock

public CommandResult fsyncAndLock()

Forces the master server to fsync the RAM data to disk, then lock all writes. The database will be read-only after this command returns.

Returns:

unlock

public DBObject unlock()

Unlocks the database, allowing the write operations to go through. This command may be asynchronous on the server, which means there may be a small delay before the database becomes writable.

Returns:

isLocked

public boolean isLocked()

Returns true if the database is locked (read-only), false otherwise.

Returns:

toString

public String toString()

Overrides:

toString in class Object