com.mongodb
Class Mongo

java.lang.Object
  extended by 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
 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 setWriteConcern(WriteConcern concern)
          Sets the write concern for this database.
 void slaveOk()
          makes it possible to run read queries on slave nodes
 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:foobar@127.0.0.1/

  • MongoDB Doc Links
    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:

    slaveOk

    public void slaveOk()
    makes it possible to run read queries on slave nodes


    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