1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
|
+++
date = "2015-03-19T14:27:51-04:00"
title = "Documents"
[menu.main]
parent = "BSON"
weight = 20
pre = "<i class='fa'></i>"
+++
## 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`]({{< apiref "org/bson/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
```javascript
{
"a" : "MongoDB",
"b" : [ 1, 2 ]
}
```
can be constructed as a BsonDocument as follows:
```java
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`]({{< apiref "org/bson/BsonValue" >}}) API documentation.
### Document
Most applications will use the [`Document`]({{< apiref "org/bson/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:
```java
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]({{< relref "codecs.md" >}}) in this
reference .
### DBObject
Although not recommended for new applications, those upgrading from the 2.x driver series may continue to use the
[`DBObject`]({{< apiref "com/mongodb/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`]({{< apiref "com/mongodb/BasicDBObject" >}}) which
implements that interface, is required
### Bson
To tie these all together, the driver contains a small but powerful interface called [`Bson`]({{< apiref "org/bson/conversions/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:
```java
collection.find(new BsonDocument("x", new BsonInt32(1)));
collection.find(new Document("x", 1));
collection.find(new BasicDBObject("x", 1));
```
|
