MongoDB的java版本驱动(译文)

原文地址为 http://docs.mongodb.org/ecosystem/tutorial/getting-started-with-java-driver/#getting-started-with-java-driver

一：下载驱动

从 http://central.maven.org/maven2/org/mongodb/mongo-java-driver/ 选择一个版本进行下载，这里选择的是2.11.4版本，具体下载以下jar包：

mongo-java-driver-2.11.4.jar

mongo-java-driver-2.11.4-javadoc.jar

mongo-java-driver-2.11.4-sources.jar

二：驱动入门

1.前言

这部分是对mongodb的java驱动的概述。

点击 http://api.mongodb.org/java/current/index.html 了解更多java驱动的API信息 

2.一个简单示例

使用java驱动非常简单。首先将mongo.jar（这里是mongo-java-driver-2.11.4.jar）加入到classpath路径下。

下面的代码片段来自于驱动中的examples/QuickTour.java

（1）建立连接

建立一个mongodb的连接，至少应该知道数据库实例的名称（不一定存在。如果不存在，会创建一个新的）

此外，可以指定mongodb服务器的ip和端口，下面的代码展现了三种不同的连接方式连接到mydb的数据库实例上

import com.mongodb.MongoClient;
import com.mongodb.MongoException;
import com.mongodb.WriteConcern;
import com.mongodb.DB;
import com.mongodb.DBCollection;
import com.mongodb.BasicDBObject;
import com.mongodb.DBObject;
import com.mongodb.DBCursor;
import com.mongodb.ServerAddress;

import java.util.Arrays;

// 方式一：直接连接单一mongodb服务器（注意这种方式不会自动发现mongodb集群中的主服务器）
MongoClient mongoClient = new MongoClient();
// 方式二（指定ip）：
MongoClient mongoClient = new MongoClient( "localhost" );
// 方式二（指定ip、端口）：
MongoClient mongoClient = new MongoClient( "localhost" , 27017 );
// 方式三：连接到mongodb服务器集群（会自动发现主服务器）
MongoClient mongoClient = new MongoClient(Arrays.asList(new ServerAddress("localhost", 27017),
                                      new ServerAddress("localhost", 27018),
                                      new ServerAddress("localhost", 27019)));

DB db = mongoClient.getDB( "mydb" );

在上面的代码中，db代表了连接mongodb中的mydb数据库实例的连接。通过它，可以进行进一步的操作。

注：MongoClient的实例代表数据库连接池，客户端在多线程环境下也只需要一个实例，请访问http://docs.mongodb.org/ecosystem/drivers/java-concurrency/#java-driver-concurrency获取更多信息

MongoClient被设计成线程安全、可以被多线程共享的。通常访问数据库集群的应用只需要一个实例。如果出于某些原因，你决定使用多个实例，请注意：

所有资源使用限制（最大连接数等等）对每个MongoClient都适用

销毁一个实例时，请确认调用MongoClient.close()方法来清理资源

MongoClient类最早从2.10.0版本引入，先前的版本请使用Mongo类

注：mongodb安装、启动可以参考 http://www.cnblogs.com/huangxincheng/archive/2012/02/18/2356595.html

(2)认证（可选）

MongoDB可以运行在安全模式上。当运行在这个模式下时，任何客户端应用在执行任何操作前必须提供用户名、密码。java客户端示例代码如下：

MongoClient mongoClient = new MongoClient();
DB db = mongoClient.getDB("test");
boolean auth = db.authenticate(myUserName, myPassword);

在上面的代码中，如果用户名密码通过校验，auth==true，否则auth=false。也可以查询mongodb的日志。

(3)获取所有集合（集合类似于mysql中的表）

每个数据库实例有0个或者多个集合，通过db可以获取到。

Set colls = db.getCollectionNames();

for (String s : colls) {
    System.out.println(s);
}

如果数据库中存在name、address两个集合，会有如下输出：

name
address

(4)获取单一集合

调用db的getCollection（String collectionName）方法获得单一集合

DBCollection coll = db.getCollection("testCollection");

获取到集合对象后，就可以进行添加、查询数据等操作。

(5)设置 write concern

2.10.0及以后版本，默认的write concern是WriteConcern.ACKNOWLEDGED。可以改变默认模式：

mongoClient.setWriteConcern(WriteConcern.JOURNALED);

write concern有很多选项。另外，默认模式可以在数据库级别、集合级别甚至是单一操作级别进行更改。具体信息请查阅API文档 http://api.mongodb.org/java/current/index.html

2.10.0以前的版本，默认值是WriteConcern.NORMAL。一般情况，客户端会改变这个值来保证写入数据库如果有问题可以被通知到。

(6)增加文档（类似向数据库中增加一条记录）

一旦获取集合对象coll，就可以插入一条文档了。例如：插入下面json格式的文档

{
   "name" : "MongoDB",
   "type" : "database",
   "count" : 1,
   "info" : {
               x : 203,
               y : 102
             }
}

注意上面存在嵌入的文档。我们可以使用BasicDBObject类创建一个文档（包括嵌入的文档）。然后调用集合coll的插入方法

BasicDBObject doc = new BasicDBObject("name", "MongoDB").
                              append("type", "database").
                              append("count", 1).
                              append("info", new BasicDBObject("x", 203).append("y", 102));

coll.insert(doc);

(7)findOne()方法：查找集合中的第一个文档

通过调用findOne()方法可以获得上一步中我们插入的文档。方法的返回值返回一个单一的文档（与DBCurse的find()方法不同）。当只存在唯一文档或者只关心第一个文档时非常有用。

DBObject myDoc = coll.findOne();
System.out.println(myDoc);

控制台输出如下：

{ "_id" : "49902cde5162504500b45c2c" ,
  "name" : "MongoDB" ,
  "type" : "database" ,
  "count" : 1 ,
  "info" : { "x" : 203 , "y" : 102}}

注意：_id元素是mongodb自动添加的。请牢记：_"/“$是mongodb的保留字，请勿使用。

(8)添加多条文档

为了方便以后的查询操作，现在向集合中增加多条文档

这些文档的格式为：

{
   "i" : value
}

通过一个循环添加文档，具体如下：

for (int i=0; i < 100; i++) {
    coll.insert(new BasicDBObject("i", i));
}

注意我们可以向一个集合插入不同格式的文档。这就是mongodb模式自由的特性

(8)查询集合中文档总个数

目前，已经向集合中插入101条文档（100条是通过循环添加的，1条是单独添加的）。可以调用getCount()方法查询总个数

System.out.println(coll.getCount());

控制台应该输出101

(9)使用游标查询所有文档

可以使用find()方法查询集合中的所有文档。方法返回一个DBCursor。这个对象可以遍历查询出的文档集合。下面是查询所有文档并且输出到控制台的代码片段

DBCursor cursor = coll.find();
try {
   while(cursor.hasNext()) {
       System.out.println(cursor.next());
   }
} finally {
   cursor.close();
}

控制台应该输出101行文档信息。

(10)查询单一文档

通过向find()方法传递参数可以查询到集合的一部分文档集合。例如：查找i==71的文档的代码片段如下：

BasicDBObject query = new BasicDBObject("i", 71);

cursor = coll.find(query);

try {
   while(cursor.hasNext()) {
       System.out.println(cursor.next());
   }
} finally {
   cursor.close();
}

控制台应该只输出一行：

{ "_id" : "49903677516250c1008d624e" , "i" : 71 }

也许你在mongodb的文档和示例代码中看到过$操作符，例如：

db.things.find({j: {$ne: 3}, k: {$gt: 10} });

Java版本的客户端将无区别的对待他们

BasicDBObject query = new BasicDBObject("j", new BasicDBObject("$ne", 3)).
                                      append("k", new BasicDBObject("$gt", 10));

cursor = coll.find(query);

try {
   while(cursor.hasNext()) {
       System.out.println(cursor.next());
   }
} finally {
   cursor.close();
}

(11)查询多个文档

通过查询可以获取集合中的多个文档。例如：查询i>50的文档：

query = new BasicDBObject("i", new BasicDBObject("$gt", 50));  // e.g. find all where i > 50

cursor = coll.find(query);

try {
   while(cursor.hasNext()) {
       System.out.println(cursor.next());
   }
} finally {
   cursor.close();
}

控制台应该打印出i>50的所有文档

查询20

query = new BasicDBObject("i", new BasicDBObject("$gt", 20).
                                               append("$lte", 30));  // i.e.   20 < i <= 30
cursor = coll.find(query);

try {
   while(cursor.hasNext()) {
       System.out.println(cursor.next());
   }
} finally {
   cursor.close();
}

一些管理相关的功能如下：

(12)创建索引

mongodb支持索引并且添加到集合中也非常方便。创建一个索引，需要指定被索引的字段以及索引方向（1代表升序、2代表降序）。

为字段i添加索引：

coll.createIndex(new BasicDBObject("i", 1));  // create index on "i", 升序

(13)查询集合上的索引

示例代码：

List list = coll.getIndexInfo();

for (DBObject o : list) {
   System.out.println(o);
}

控制台应该输出：

{ "name" : "i_1" , "ns" : "mydb.testCollection" , "key" : { "i" : 1} }

(14)查询所有数据库实例名称

示例代码如下：

MongoClient mongoClient = new MongoClient();

for (String s : mongoClient.getDatabaseNames()) {
   System.out.println(s);
}

(15)删除数据库实例

示例代码如下：

MongoClient mongoClient = new MongoClient();
mongoClient.dropDatabase("myDatabase");

三：API文档

请访问 http://api.mongodb.org/java/index.html

四：版本

请访问 https://github.com/mongodb/mongo-java-driver/wiki/Release-Notes

五：主题外

http://download.csdn.net/detail/u012227177/7013227资源中的代码供参考。

如果运行的话必须启动mongodb（请参考 http://www.cnblogs.com/huangxincheng/archive/2012/02/18/2356595.html）。

欢迎指出错误，谢谢。