Package org.bson

Class Document

java.lang.Object

org.bson.Document

All Implemented Interfaces:

Serializable, Map<String,Object>, Bson

public class Document
extends Object
implements Map<String,Object>, Serializable, Bson

A representation of a document as a Map. All iterators will traverse the elements in insertion order, as with LinkedHashMap.

Since:

3.0.0

See Also:

Serialized Form

MongoDB documentation

document

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K extends Object,V extends Object>

Field Summary

Fields inherited from interface org.bson.conversions.Bson

DEFAULT_CODEC_REGISTRY

Constructor Summary

Constructors

Constructor	Description
Document()	Creates an empty Document instance.
Document(String key, Object value)	Create a Document instance initialized with the given key/value pair.
Document(Map<String,Object> map)	Creates a Document instance initialized with the given map.

Method Summary

Modifier and Type	Method	Description
Document	append(String key, Object value)	Put the given key/value pair into this Document and return this.
void	clear()
boolean	containsKey(Object key)
boolean	containsValue(Object value)
Set<Map.Entry<String,Object>>	entrySet()
boolean	equals(Object o)
Object	get(Object key)
<T> T	get(Object key, Class<T> clazz)	Gets the value of the given key, casting it to the given Class<T>.
<T> T	get(Object key, T defaultValue)	Gets the value of the given key, casting it to Class<T> or returning the default value if null.
Boolean	getBoolean(Object key)	Gets the value of the given key as a Boolean.
boolean	getBoolean(Object key, boolean defaultValue)	Gets the value of the given key as a primitive boolean.
Date	getDate(Object key)	Gets the value of the given key as a Date.
Double	getDouble(Object key)	Gets the value of the given key as a Double.
<T> T	getEmbedded(List<?> keys, Class<T> clazz)	Gets the value in an embedded document, casting it to the given Class<T>.
<T> T	getEmbedded(List<?> keys, T defaultValue)	Gets the value in an embedded document, casting it to the given Class<T> or returning the default value if null.
Integer	getInteger(Object key)	Gets the value of the given key as an Integer.
int	getInteger(Object key, int defaultValue)	Gets the value of the given key as a primitive int.
<T> List<T>	getList(Object key, Class<T> clazz)	Gets the list value of the given key, casting the list elements to the given Class<T>.
<T> List<T>	getList(Object key, Class<T> clazz, List<T> defaultValue)	Gets the list value of the given key, casting the list elements to Class<T> or returning the default list value if null.
Long	getLong(Object key)	Gets the value of the given key as a Long.
ObjectId	getObjectId(Object key)	Gets the value of the given key as an ObjectId.
String	getString(Object key)	Gets the value of the given key as a String.
int	hashCode()
boolean	isEmpty()
Set<String>	keySet()
static Document	parse(String json)	Parses a string in MongoDB Extended JSON format to a Document
static Document	parse(String json, Decoder<Document> decoder)	Parses a string in MongoDB Extended JSON format to a Document
Object	put(String key, Object value)
void	putAll(Map<? extends String,?> map)
Object	remove(Object key)
int	size()
<C> BsonDocument	toBsonDocument(Class<C> documentClass, CodecRegistry codecRegistry)	Render into a BsonDocument.
String	toJson()	Gets a JSON representation of this document using the JsonMode.RELAXED output mode, and otherwise the default settings of JsonWriterSettings.Builder and DocumentCodec.
String	toJson(Encoder<Document> encoder)	Gets a JSON representation of this document
String	toJson(JsonWriterSettings writerSettings)	Gets a JSON representation of this document
String	toJson(JsonWriterSettings writerSettings, Encoder<Document> encoder)	Gets a JSON representation of this document
String	toString()
Collection<Object>	values()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.bson.conversions.Bson

toBsonDocument

Methods inherited from interface java.util.Map

compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, remove, replace, replace, replaceAll

Constructor Detail

Document

public Document()

Creates an empty Document instance.

Document

public Document(String key,
                Object value)

Create a Document instance initialized with the given key/value pair.

Parameters:

key - key

value - value

Document

public Document(Map<String,Object> map)

Creates a Document instance initialized with the given map.

Parameters:

map - initial map

Method Detail

parse

public static Document parse(String json)

Parses a string in MongoDB Extended JSON format to a Document

Parameters:

json - the JSON string

Returns:

a corresponding Document object

See Also:

JsonReader

MongoDB documentation

MongoDB Extended JSON

parse

public static Document parse(String json,
                             Decoder<Document> decoder)

Parses a string in MongoDB Extended JSON format to a Document

Parameters:

json - the JSON string

decoder - the Decoder to use to parse the JSON string into a Document

Returns:

a corresponding Document object

See Also:

JsonReader

MongoDB documentation

MongoDB Extended JSON

toBsonDocument

public <C> BsonDocument toBsonDocument(Class<C> documentClass,
                                       CodecRegistry codecRegistry)

Description copied from interface: Bson

Render into a BsonDocument.

Specified by:

toBsonDocument in interface Bson

Type Parameters:

C - the type of the document class

Parameters:

documentClass - the document class in scope for the collection. This parameter may be ignored, but it may be used to alter the structure of the returned BsonDocument based on some knowledge of the document class.

codecRegistry - the codec registry. This parameter may be ignored, but it may be used to look up Codec instances for the document class or any other related class.

Returns:

the BsonDocument

append

public Document append(String key,
                       Object value)

Put the given key/value pair into this Document and return this. Useful for chaining puts in a single expression, e.g.

 doc.append("a", 1).append("b", 2)}
 

Parameters:

key - key

value - value

Returns:

this

get

public <T> T get(Object key,
                 Class<T> clazz)

Gets the value of the given key, casting it to the given Class<T>. This is useful to avoid having casts in client code, though the effect is the same. So to get the value of a key that is of type String, you would write String name = doc.get("name", String.class) instead of String name = (String) doc.get("x") .

Type Parameters:

T - the type of the class

Parameters:

key - the key

clazz - the non-null class to cast the value to

Returns:

the value of the given key, or null if the instance does not contain this key.

Throws:

ClassCastException - if the value of the given key is not of type T

get

public <T> T get(Object key,
                 T defaultValue)

Gets the value of the given key, casting it to Class<T> or returning the default value if null. This is useful to avoid having casts in client code, though the effect is the same.

Type Parameters:

T - the type of the class

Parameters:

key - the key

defaultValue - what to return if the value is null

Returns:

the value of the given key, or null if the instance does not contain this key.

Throws:

ClassCastException - if the value of the given key is not of type T

Since:

3.5

getEmbedded

public <T> T getEmbedded(List<?> keys,
                         Class<T> clazz)

Gets the value in an embedded document, casting it to the given Class<T>. The list of keys represents a path to the embedded value, drilling down into an embedded document for each key. This is useful to avoid having casts in client code, though the effect is the same. The generic type of the keys list is ? to be consistent with the corresponding get methods, but in practice the actual type of the argument should be List<String>. So to get the embedded value of a key list that is of type String, you would write String name = doc.getEmbedded(List.of("employee", "manager", "name"), String.class) instead of String name = (String) doc.get("employee", Document.class).get("manager", Document.class).get("name") .

Type Parameters:

T - the type of the class

Parameters:

keys - the list of keys

clazz - the non-null class to cast the value to

Returns:

the value of the given embedded key, or null if the instance does not contain this embedded key.

Throws:

ClassCastException - if the value of the given embedded key is not of type T

Since:

3.10

getEmbedded

public <T> T getEmbedded(List<?> keys,
                         T defaultValue)

Gets the value in an embedded document, casting it to the given Class<T> or returning the default value if null. The list of keys represents a path to the embedded value, drilling down into an embedded document for each key. This is useful to avoid having casts in client code, though the effect is the same. The generic type of the keys list is ? to be consistent with the corresponding get methods, but in practice the actual type of the argument should be List<String>. So to get the embedded value of a key list that is of type String, you would write String name = doc.getEmbedded(List.of("employee", "manager", "name"), "John Smith") instead of String name = doc.get("employee", Document.class).get("manager", Document.class).get("name", "John Smith") .

Type Parameters:

T - the type of the class

Parameters:

keys - the list of keys

defaultValue - what to return if the value is null

Returns:

the value of the given key, or null if the instance does not contain this key.

Throws:

ClassCastException - if the value of the given key is not of type T

Since:

3.10

getInteger

public Integer getInteger(Object key)

Gets the value of the given key as an Integer.

Parameters:

key - the key

Returns:

the value as an integer, which may be null

Throws:

ClassCastException - if the value is not an integer

getInteger

public int getInteger(Object key,
                      int defaultValue)

Gets the value of the given key as a primitive int.

Parameters:

key - the key

defaultValue - what to return if the value is null

Returns:

the value as an integer, which may be null

Throws:

ClassCastException - if the value is not an integer

getLong

public Long getLong(Object key)

Gets the value of the given key as a Long.

Parameters:

key - the key

Returns:

the value as a long, which may be null

Throws:

ClassCastException - if the value is not an long

getDouble

public Double getDouble(Object key)

Gets the value of the given key as a Double.

Parameters:

key - the key

Returns:

the value as a double, which may be null

Throws:

ClassCastException - if the value is not an double

getString

public String getString(Object key)

Gets the value of the given key as a String.

Parameters:

key - the key

Returns:

the value as a String, which may be null

Throws:

ClassCastException - if the value is not a String

getBoolean

public Boolean getBoolean(Object key)

Gets the value of the given key as a Boolean.

Parameters:

key - the key

Returns:

the value as a Boolean, which may be null

Throws:

ClassCastException - if the value is not an boolean

getBoolean

public boolean getBoolean(Object key,
                          boolean defaultValue)

Gets the value of the given key as a primitive boolean.

Parameters:

key - the key

defaultValue - what to return if the value is null

Returns:

the value as a primitive boolean

Throws:

ClassCastException - if the value is not a boolean

getObjectId

public ObjectId getObjectId(Object key)

Gets the value of the given key as an ObjectId.

Parameters:

key - the key

Returns:

the value as an ObjectId, which may be null

Throws:

ClassCastException - if the value is not an ObjectId

getDate

public Date getDate(Object key)

Gets the value of the given key as a Date.

Parameters:

key - the key

Returns:

the value as a Date, which may be null

Throws:

ClassCastException - if the value is not a Date

getList

public <T> List<T> getList(Object key,
                           Class<T> clazz)

Gets the list value of the given key, casting the list elements to the given Class<T>. This is useful to avoid having casts in client code, though the effect is the same.

Type Parameters:

T - the type of the class

Parameters:

key - the key

clazz - the non-null class to cast the list value to

Returns:

the list value of the given key, or null if the instance does not contain this key.

Throws:

ClassCastException - if the elements in the list value of the given key is not of type T or the value is not a list

Since:

3.10

getList

public <T> List<T> getList(Object key,
                           Class<T> clazz,
                           List<T> defaultValue)

Gets the list value of the given key, casting the list elements to Class<T> or returning the default list value if null. This is useful to avoid having casts in client code, though the effect is the same.

Type Parameters:

T - the type of the class

Parameters:

key - the key

clazz - the non-null class to cast the list value to

defaultValue - what to return if the value is null

Returns:

the list value of the given key, or the default list value if the instance does not contain this key.

Throws:

ClassCastException - if the value of the given key is not of type T

Since:

3.10

toJson

public String toJson()

Gets a JSON representation of this document using the JsonMode.RELAXED output mode, and otherwise the default settings of JsonWriterSettings.Builder and DocumentCodec.

Returns:

a JSON representation of this document

Throws:

CodecConfigurationException - if the document contains types not in the default registry

See Also:

toJson(JsonWriterSettings), JsonWriterSettings

toJson

public String toJson(JsonWriterSettings writerSettings)

Gets a JSON representation of this document

With the default DocumentCodec.

Parameters:

writerSettings - the json writer settings to use when encoding

Returns:

a JSON representation of this document

Throws:

CodecConfigurationException - if the document contains types not in the default registry

toJson

public String toJson(Encoder<Document> encoder)

Gets a JSON representation of this document

With the default JsonWriterSettings.

Parameters:

encoder - the document codec instance to use to encode the document

Returns:

a JSON representation of this document

Throws:

CodecConfigurationException - if the registry does not contain a codec for the document values.

toJson

public String toJson(JsonWriterSettings writerSettings,
                     Encoder<Document> encoder)

Gets a JSON representation of this document

Parameters:

writerSettings - the json writer settings to use when encoding

encoder - the document codec instance to use to encode the document

Returns:

a JSON representation of this document

Throws:

CodecConfigurationException - if the registry does not contain a codec for the document values.

size

public int size()

Specified by:

size in interface Map<String,Object>

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface Map<String,Object>

containsValue

public boolean containsValue(Object value)

Specified by:

containsValue in interface Map<String,Object>

containsKey

public boolean containsKey(Object key)

Specified by:

containsKey in interface Map<String,Object>

get

public Object get(Object key)

Specified by:

get in interface Map<String,Object>

put

public Object put(String key,
                  Object value)

Specified by:

put in interface Map<String,Object>

remove

public Object remove(Object key)

Specified by:

remove in interface Map<String,Object>

putAll

public void putAll(Map<? extends String,?> map)

Specified by:

putAll in interface Map<String,Object>

clear

public void clear()

Specified by:

clear in interface Map<String,Object>

keySet

public Set<String> keySet()

Specified by:

keySet in interface Map<String,Object>

values

public Collection<Object> values()

Specified by:

values in interface Map<String,Object>

entrySet

public Set<Map.Entry<String,Object>> entrySet()

Specified by:

entrySet in interface Map<String,Object>

equals

public boolean equals(Object o)

Specified by:

equals in interface Map<String,Object>

Overrides:

equals in class Object

hashCode

public int hashCode()

Specified by:

hashCode in interface Map<String,Object>

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object