For the most recent version of the reference documentation, see our MongoDB Java Driver documentation site.
- BSON
- Documents
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));