Which Doc class is finest to make use of in Java to learn MongoDB paperwork?

TL;DR: the reply is within the title, use Doc.

BSON is a serialization format, much like protobuf, designed for environment friendly doc storage on disk and switch over the community as a byte stream. As an alternative of scanning and rewriting the whole byte sequence to entry its contents (fields, arrays, subdocuments), you’re employed with an in-memory object that exposes strategies to learn and write fields effectively. On MongoDB’s server facet, that is the mutable BSON object. On the consumer facet, the drivers present an analogous API. Listed below are the 5 object varieties that implement the BSON interface in Java

• Doc is the advice for many functions. It supplies the most effective steadiness of flexibility, ease of use, and performance.

Solely think about the opposite lessons when you could have particular necessities:

• BsonDocument: Once you want strict BSON kind security somewhat than utility varieties.

• RawBsonDocument: When it is advisable to entry the uncooked bytes of the doc somewhat than subject values.

• JsonObject: When working solely with JSON strings, as plain textual content.

• BasicDBObject: Just for legacy code migration.

RawBsonDocument is used internally—for instance, for client-side encryption and alter streams—whereas the opposite lessons can all be used straight in MongoDB driver operations. Your alternative primarily impacts the way you assemble, manipulate, and entry doc knowledge in your utility code. They’re documented:

mongodb.com

I reviewed the documentation and code to raised perceive their variations. Particularly when evaluating with different databases which have totally different design and API. On this submit I present an in depth description of these lessons, what they’re, how they’re applied, what they supply, and when to make use of them

Detailed description

Here is an in depth comparability of the 5 doc lessons accessible within the MongoDB Java Driver and when to make use of every:

Doc (org.bson)

Doc is a versatile illustration of a BSON doc that implements Map. It makes use of a LinkedHashMap internally to keep up insertion order.

Key traits:

• Loosely-typed: Values are saved as Object, permitting you to make use of customary Java varieties (String, Integer, Date, and so on.)
• Versatile: Straightforward to work with dynamically structured paperwork
• Map interface: Offers all customary Map operations

Doc is the beneficial default alternative for many functions. Use it if you desire a versatile and concise knowledge illustration that is simple to work with.

BsonDocument (org.bson)

BsonDocument is a type-safe container for BSON paperwork that implements Map. It additionally makes use of a LinkedHashMap, however shops BsonValue varieties.

Key traits:

• Sort-safe: All values should be wrapped in BSON library varieties (BsonString, BsonInt32, BsonDocument, and so on.)
• Stricter API: Offers compile-time kind security however requires extra verbose code
• Map interface: Implements Map

Use BsonDocument if you want a type-safe API and wish express management over BSON varieties. That is significantly helpful when it is advisable to guarantee exact kind dealing with or when working with APIs that require BsonDocument.

RawBsonDocument (org.bson)

RawBsonDocument is an immutable BSON doc represented utilizing solely uncooked bytes. It shops the BSON doc as a byte array with out parsing it.

Key traits:

• Immutable: All mutation operations throw UnsupportedOperationException
• Lazy parsing: Information is barely parsed when accessed, making it very environment friendly for pass-through situations, when not for accessing every particular person subject
• Reminiscence environment friendly: Shops uncooked bytes, avoiding object allocation overhead
• Can decode to different varieties: Offers decode() technique to transform to different doc varieties when wanted

Use RawBsonDocument if you want most efficiency and reminiscence effectivity for whole-document operations. It’s significantly helpful when studying paperwork from MongoDB and passing them to a different system unchanged, when working with massive paperwork that you simply don’t must parse, when constructing high-performance knowledge pipelines the place parsing overhead issues, and if you want an immutable doc illustration.

JsonObject (org.bson.json)

JsonObject is a wrapper class that holds a JSON object string. It merely shops the JSON as a String.

Key traits:

• Doesn’t implement Map: It is only a string wrapper with validation
• No parsing required: Avoids conversion to Map construction for those who’re simply working with JSON
• JSON-focused: Designed for functions that primarily work with JSON strings
• Helps Prolonged JSON: Works with MongoDB Prolonged JSON format

Use JsonObject if you need to work straight with JSON strings and keep away from the overhead of changing to and from Map objects. That is best for REST APIs that devour and produce JSON, for logging or persisting paperwork as JSON strings, and for functions that primarily deal with JSON and don’t require programmatic field-level entry.

BasicDBObject (com.mongodb)

BasicDBObject is a legacy BSON object implementation that extends BasicBSONObject and implements the DBObject interface.

Key traits:

• Legacy class: Exists for backward compatibility with older driver variations
• Doesn’t implement Map: Solely implements the DBObject interface, missing fashionable Map comfort strategies
• Binary compatibility issues: Implements an interface somewhat than extending a category, which might trigger compatibility points

Solely use BasicDBObject when migrating from a legacy driver model (pre-3.0). The documentation explicitly recommends avoiding this class for brand new growth on account of its limitations.

Conversion Between Varieties

All of those lessons implement the Bson interface, which permits them for use interchangeably in MongoDB operations (however with out the identical efficiency). You may also convert between varieties:

• BsonDocument.parse(json) to create from JSON
• RawBsonDocument.decode(codec) to transform RawBsonDocument to a different kind
• Doc might be transformed to BsonDocument by way of codec operations
• JsonObject.getJson() to extract the JSON string

Evaluating RawBsonDocument and Doc

RawBsonDocument shops BSON as a uncooked byte array and doesn’t deserialize it upfront. Once you entry a subject, it creates a BsonBinaryReader and scans the doc sequentially, studying every subject’s kind and title till it finds the requested key. Solely the matching subject is decoded utilizing RawBsonValueHelper.decode, whereas all different fields are skipped with out parsing. For nested paperwork and arrays, it reads solely their sizes and wraps the corresponding byte ranges in new RawBsonDocument or RawBsonArray situations, holding their contents as uncooked bytes. This strategy supplies quick entry for a single subject lookup, whereas being memory-efficient and holding the doc immutable, which is good for giant paperwork the place only some fields are wanted or for paperwork which might be principally handed by way of with out inspection.

In distinction, Doc makes use of a totally deserialized LinkedHashMap. When a Doc is created, all fields are eagerly parsed into Java objects. Discipline entry and containsKey operations are easy HashMap lookups, and the doc is totally mutable, supporting customary map operations resembling put, take away, and clear. This design consumes extra reminiscence however is healthier suited to small or medium-sized paperwork, situations the place many fields are accessed, or circumstances the place the doc must be modified ceaselessly.

Lastly, Doc does not use RawBsonDocument for parsing or accessing fields since doing so could be inefficient, and the 2 serve totally different functions.

Comparability with Oracle (OSON) and PostgreSQL (JSONB)

Neither Oracle nor PostgreSQL supplies BSON as they use OSON and JSONB, so there is no BsonDocument or RawBsonDocument equal.

In Oracle’s JDBC driver, the closest equal to a Doc is OracleJsonObject, one of many OracleJsonValue varieties, which might be uncovered straight as a javax.json.JsonObject or mapped area object. This API works straight on the underlying OSON bytes with out totally parsing the whole doc into an intermediate knowledge construction. OSON is greater than a uncooked serialization: it carries its personal native dictionary of distinct subject names, a sorted array of hash codes for these names, and compact subject ID arrays and worth offsets, enabling the driving force to find a subject in place by binary‑looking the sector ID array, and leaping to the correct offset.

If JSON textual content is required as a substitute of the article mannequin, the equal is just to make use of ResultSet.getString(), which can convert the OSON picture to JSON textual content on the consumer.

PostgreSQL’s JDBC driver, against this, gives no native Java JSON object API for both json or jsonb columns: values are at all times returned as textual content, so the appliance should parse the string into its personal doc mannequin utilizing a separate JSON library. Even when utilizing PostgreSQL’s binary JSONB storage, not one of the binary effectivity crosses the wire (See JSONB vs. BSON: Tracing PostgreSQL and MongoDB Wire Protocols), and consumer code nonetheless performs a full parse earlier than accessing particular person fields.

Conclusion

MongoDB’s important benefit for contemporary functions—regardless of the knowledge varieties or workloads—is the power to work with knowledge straight by way of your area objects, with out an intermediate object-relational mapping layer or view. Use the Doc class as your doc object mannequin (DOM). It gives flexibility, map-style entry, and a pure Java interface, whereas the driving force transparently converts BSON from the community into objects your utility can use instantly.