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:
MongoDB documentation
document

  • Constructor Details

    • 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,?> map)
      Creates a Document instance initialized with the given map.
      Parameters:
      map - initial map

  • Method Details

    • 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:
      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:
      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

      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