0
# MongoDB BSON Java
1

2
MongoDB BSON is a comprehensive Java library that provides high-performance binary serialization for MongoDB documents. It offers a complete BSON (Binary JSON) implementation with both modern type-safe APIs and legacy compatibility, supporting all BSON types, efficient I/O operations, and flexible object mapping through a sophisticated codec system.
3

4
## Package Information
5

6
- **Package Name**: org.mongodb:bson
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>org.mongodb</groupId>
13
    <artifactId>bson</artifactId>
14
    <version>5.5.1</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import org.bson.BsonDocument;
22
import org.bson.BsonValue;
23
import org.bson.Document;
24
import org.bson.codecs.Codec;
25
import org.bson.codecs.CodecRegistry;
26
import org.bson.types.ObjectId;
27
```
28

29
## Basic Usage
30

31
```java
32
import org.bson.BsonDocument;
33
import org.bson.BsonString;
34
import org.bson.BsonInt32;
35
import org.bson.Document;
36
import org.bson.types.ObjectId;
37

38
// Modern type-safe API
39
BsonDocument bsonDoc = new BsonDocument();
40
bsonDoc.put("name", new BsonString("John Doe"));
41
bsonDoc.put("age", new BsonInt32(30));
42
bsonDoc.put("_id", new BsonObjectId(new ObjectId()));
43

44
// Legacy Document API
45
Document doc = new Document("name", "John Doe")
46
    .append("age", 30)
47
    .append("_id", new ObjectId());
48

49
// Convert between formats
50
BsonDocument converted = doc.toBsonDocument();
51
Document backToDoc = new Document(converted);
52
```
53

54
## Architecture
55

56
MongoDB BSON is built around several key components:
57

58
- **Type System**: Complete hierarchy of BSON value types (BsonDocument, BsonArray, primitives)
59
- **Codec Framework**: Flexible serialization system with automatic POJO mapping and custom codec support
60
- **I/O Abstractions**: Binary readers/writers with buffering and streaming support
61
- **JSON Integration**: Multiple JSON format support (Strict, Extended, Relaxed, Shell)
62
- **Legacy Compatibility**: Full support for original MongoDB Java driver APIs
63
- **Vector Support**: Binary vector types for AI/ML applications
64

65
## Capabilities
66

67
### Core BSON Types
68

69
Complete type-safe BSON value hierarchy with document and array collections. Essential for all BSON operations and provides the foundation for MongoDB document manipulation.
70

71
```java { .api }
72
public abstract class BsonValue implements Cloneable {
73
    public abstract BsonType getBsonType();
74
    public boolean isDocument();
75
    public boolean isArray();
76
    public BsonDocument asDocument();
77
    public BsonArray asArray();
78
}
79

80
public final class BsonDocument extends BsonValue implements Map<String, BsonValue> {
81
    public BsonDocument();
82
    public BsonDocument(String key, BsonValue value);
83
    public BsonValue get(Object key);
84
    public BsonValue put(String key, BsonValue value);
85
    public BsonDocument append(String key, BsonValue value);
86
}
87
```
88

89
[Core BSON Types](./core-types.md)
90

91
### Codec System
92

93
Sophisticated serialization framework for converting between Java objects and BSON. Includes built-in codecs for all Java types and supports custom POJO mapping with annotations.
94

95
```java { .api }
96
public interface Codec<T> extends Encoder<T>, Decoder<T> {
97
    // Inherits encode() from Encoder<T>
98
    // Inherits decode() from Decoder<T>
99
    // Inherits getEncoderClass() from Encoder<T>
100
}
101

102
public interface CodecRegistry {
103
    <T> Codec<T> get(Class<T> clazz);
104
    <T> Codec<T> get(Class<T> clazz, CodecRegistry registry);
105
}
106
```
107

108
[Codec System](./codecs.md)
109

110
### Binary I/O Operations
111

112
High-performance binary readers and writers for BSON data with buffering, streaming, and mark/reset capabilities. Essential for database operations and file I/O.
113

114
```java { .api }
115
public interface BsonReader extends Closeable {
116
    BsonType readBsonType();
117
    String readName();
118
    void readStartDocument();
119
    void readEndDocument();
120
    void readStartArray();
121
    void readEndArray();
122
    String readString();
123
    int readInt32();
124
    long readInt64();
125
}
126
```
127

128
[Binary I/O Operations](./io.md)
129

130
### JSON Conversion
131

132
Comprehensive JSON support with multiple output formats including MongoDB Extended JSON, strict JSON, and shell format. Enables easy integration with web APIs and configuration files.
133

134
```java { .api }
135
public class JsonReader extends AbstractBsonReader {
136
    public JsonReader(String json);
137
    public JsonReader(Reader reader);
138
    public JsonReader(String json, JsonReaderSettings settings);
139
}
140

141
public class JsonWriter extends AbstractBsonWriter {
142
    public JsonWriter(Writer writer);
143
    public JsonWriter(Writer writer, JsonWriterSettings settings);
144
}
145
```
146

147
[JSON Conversion](./json.md)
148

149
### Specialized Data Types
150

151
MongoDB-specific and specialized BSON types including ObjectId, Decimal128, Binary data, timestamps, and geographic types. Essential for MongoDB operations and advanced data modeling.
152

153
```java { .api }
154
public final class ObjectId implements Comparable<ObjectId>, Serializable {
155
    public ObjectId();
156
    public ObjectId(byte[] bytes);
157
    public ObjectId(String hexString);
158
    public String toHexString();
159
    public byte[] toByteArray();
160
    public Date getDate();
161
}
162
```
163

164
[Specialized Data Types](./types.md)
165

166
### Legacy BSON API
167

168
Original MongoDB Java driver API maintained for backward compatibility. Provides familiar interface for existing applications while supporting all modern BSON features.
169

170
```java { .api }
171
public interface BSONObject {
172
    Object put(String key, Object v);
173
    Object get(String key);
174
    Map toMap();
175
    boolean containsField(String s);
176
}
177

178
public class BasicBSONObject implements BSONObject {
179
    public BasicBSONObject();
180
    public BasicBSONObject(String key, Object value);
181
    public BasicBSONObject(Map m);
182
}
183
```
184

185
[Legacy BSON API](./legacy-api.md)
186

187
## Types
188

189
```java { .api }
190
public enum BsonType {
191
    END_OF_DOCUMENT(0x00),
192
    DOUBLE(0x01),
193
    STRING(0x02),
194
    DOCUMENT(0x03),
195
    ARRAY(0x04),
196
    BINARY(0x05),
197
    UNDEFINED(0x06),
198
    OBJECT_ID(0x07),
199
    BOOLEAN(0x08),
200
    DATE_TIME(0x09),
201
    NULL(0x0A),
202
    REGULAR_EXPRESSION(0x0B),
203
    DB_POINTER(0x0C),
204
    JAVASCRIPT(0x0D),
205
    SYMBOL(0x0E),
206
    JAVASCRIPT_WITH_SCOPE(0x0F),
207
    INT32(0x10),
208
    TIMESTAMP(0x11),
209
    INT64(0x12),
210
    DECIMAL128(0x13),
211
    MIN_KEY(0xFF),
212
    MAX_KEY(0x7F)
213
}
214

215
public interface EncoderContext {
216
    boolean isEncodingCollectibleDocument();
217
    EncoderContext getChildContext();
218
}
219

220
public interface DecoderContext {
221
    DecoderContext getChildContext();
222
}
223
```