or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

codecs.mdcore-types.mdindex.mdio.mdjson.mdlegacy-api.mdtypes.md
tile.json

tessl/maven-org-mongodb--bson

The BSON library for MongoDB Java Driver - A high-performance binary serialization format and library for MongoDB documents

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.mongodb/bson@5.5.x

To install, run

npx @tessl/cli install tessl/maven-org-mongodb--bson@5.5.0

index.mddocs/

MongoDB BSON Java

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.

Package Information

  • Package Name: org.mongodb:bson
  • Package Type: Maven
  • Language: Java
  • Installation: 
    <dependency>
  <groupId>org.mongodb</groupId>
  <artifactId>bson</artifactId>
  <version>5.5.1</version>
</dependency>

Core Imports

import org.bson.BsonDocument;
import org.bson.BsonValue;
import org.bson.Document;
import org.bson.codecs.Codec;
import org.bson.codecs.CodecRegistry;
import org.bson.types.ObjectId;

Basic Usage

import org.bson.BsonDocument;
import org.bson.BsonString;
import org.bson.BsonInt32;
import org.bson.Document;
import org.bson.types.ObjectId;

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

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

// Convert between formats
BsonDocument converted = doc.toBsonDocument();
Document backToDoc = new Document(converted);

Architecture

MongoDB BSON is built around several key components:

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

Capabilities

Core BSON Types

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

public abstract class BsonValue implements Cloneable {
    public abstract BsonType getBsonType();
    public boolean isDocument();
    public boolean isArray();
    public BsonDocument asDocument();
    public BsonArray asArray();
}

public final class BsonDocument extends BsonValue implements Map<String, BsonValue> {
    public BsonDocument();
    public BsonDocument(String key, BsonValue value);
    public BsonValue get(Object key);
    public BsonValue put(String key, BsonValue value);
    public BsonDocument append(String key, BsonValue value);
}

Core BSON Types

Codec System

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.

public interface Codec<T> extends Encoder<T>, Decoder<T> {
    // Inherits encode() from Encoder<T>
    // Inherits decode() from Decoder<T>
    // Inherits getEncoderClass() from Encoder<T>
}

public interface CodecRegistry {
    <T> Codec<T> get(Class<T> clazz);
    <T> Codec<T> get(Class<T> clazz, CodecRegistry registry);
}

Codec System

Binary I/O Operations

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

public interface BsonReader extends Closeable {
    BsonType readBsonType();
    String readName();
    void readStartDocument();
    void readEndDocument();
    void readStartArray();
    void readEndArray();
    String readString();
    int readInt32();
    long readInt64();
}

Binary I/O Operations

JSON Conversion

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.

public class JsonReader extends AbstractBsonReader {
    public JsonReader(String json);
    public JsonReader(Reader reader);
    public JsonReader(String json, JsonReaderSettings settings);
}

public class JsonWriter extends AbstractBsonWriter {
    public JsonWriter(Writer writer);
    public JsonWriter(Writer writer, JsonWriterSettings settings);
}

JSON Conversion

Specialized Data Types

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

public final class ObjectId implements Comparable<ObjectId>, Serializable {
    public ObjectId();
    public ObjectId(byte[] bytes);
    public ObjectId(String hexString);
    public String toHexString();
    public byte[] toByteArray();
    public Date getDate();
}

Specialized Data Types

Legacy BSON API

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

public interface BSONObject {
    Object put(String key, Object v);
    Object get(String key);
    Map toMap();
    boolean containsField(String s);
}

public class BasicBSONObject implements BSONObject {
    public BasicBSONObject();
    public BasicBSONObject(String key, Object value);
    public BasicBSONObject(Map m);
}

Legacy BSON API

Types

public enum BsonType {
    END_OF_DOCUMENT(0x00),
    DOUBLE(0x01),
    STRING(0x02),
    DOCUMENT(0x03),
    ARRAY(0x04),
    BINARY(0x05),
    UNDEFINED(0x06),
    OBJECT_ID(0x07),
    BOOLEAN(0x08),
    DATE_TIME(0x09),
    NULL(0x0A),
    REGULAR_EXPRESSION(0x0B),
    DB_POINTER(0x0C),
    JAVASCRIPT(0x0D),
    SYMBOL(0x0E),
    JAVASCRIPT_WITH_SCOPE(0x0F),
    INT32(0x10),
    TIMESTAMP(0x11),
    INT64(0x12),
    DECIMAL128(0x13),
    MIN_KEY(0xFF),
    MAX_KEY(0x7F)
}

public interface EncoderContext {
    boolean isEncodingCollectibleDocument();
    EncoderContext getChildContext();
}

public interface DecoderContext {
    DecoderContext getChildContext();
}