Documents

The driver includes several classes and interfaces used for representing BSON documents.

BsonDocument

Although generally not needed by users of the high-level driver API, the BsonDocument class is central to the way that documents are managed internally by the driver. The BsonDocument class can represent dynamically structured documents of any complexity with a type-safe API. For instance, the document

{ 
  "a" : "MongoDB", 
  "b" : [ 1, 2 ] 
}

can be constructed as a BsonDocument as follows:

new BsonDocument().append("a", new BsonString("MongoDB"))
                  .append("b", new BsonArray(Arrays.asList(new BsonInt32(1), new BsonInt32(2))));

The type safety comes from BsonDocument implementing Map<String, BsonValue>, so even built-in types like int, String and List must be wrapped in a sub-class of BsonValue. For a complete list of BsonValue sub-types, please consult the BsonValue API documentation.

Document

Most applications will use the Document class instead. Like BsonDocument, the Document class can represent dynamically structured documents of any complexity; however, the typing is much looser, as Document implements Map<String, Object>. As a result, the same document as above can be constructed using the Document class as follows:

new Document().append("a", "MongoDB")
              .append("b", Arrays.asList(1, 2));

There is less code to write, but runtime errors are possible if you inadvertently add an instance of an unsupported value type.

The most commonly used value types are:

BSON type	Java type
Document	org.bson.Document
Array	java.util.List
Date	java.util.Date
Boolean	java.lang.Boolean
Double	java.lang.Double
Int32	java.lang.Integer
Int64	java.lang.Long
String	java.lang.String
Binary	org.bson.types.Binary
ObjectId	org.bson.types.ObjectId
Null	null

It is actually possible to change these mappings; the mechanism for doing so is covered later in this reference .

DBObject

Although not recommended for new applications, those upgrading from the 2.x driver series may continue to use the DBObject interface to represent BSON documents. DBObject is similar to Document in that it represents BSON values as Object, but it has a few shortcomings that were impossible to overcome:

• it is an interface rather than a class, so it’s API can not be extended without breaking binary compatibility
• it doesn’t actually implement Map<String, Object>
• because it is an interface, a separate concrete class called BasicDBObject which implements that interface, is required

Bson

To tie these all together, the driver contains a small but powerful interface called Bson. Any class that represents a BSON document, whether included in the driver itself or from a third party, can implement this interface and can then be used any place in the high-level API where a BSON document is required. The three classes discussed above all implement this interface and so can be used interchangeably based on the needs of a given application. For example:

collection.find(new BsonDocument("x", new BsonInt32(1)));
collection.find(new Document("x", 1));
collection.find(new BasicDBObject("x", 1));