com.allanbank.mongodb.bson.element

Class DocumentElement

java.lang.Object

com.allanbank.mongodb.bson.element.AbstractElement

com.allanbank.mongodb.bson.element.DocumentElement

All Implemented Interfaces:

Document, DocumentAssignable, Element, ElementAssignable, Serializable, Comparable<Element>, Iterable<Element>

public class DocumentElement
extends AbstractElement
implements Document

Wraps a single BSON document that may contain nested documents.

See Also:

Serialized Form

API Notice:

This class is part of the driver's API. Public and protected members will be deprecated for at least 1 non-bugfix release (version numbers are <major>.<minor>.<bugfix>) before being removed or modified.

Copyright ©:

2011-2013, Allanbank Consulting, Inc., All Rights Reserved

Field Summary

Fields

Modifier and Type	Field and Description
static List<Element>	EMPTY_ELEMENTS The empty list of elements.
static ElementType	TYPE The BSON type for a document.

Fields inherited from class com.allanbank.mongodb.bson.element.AbstractElement

ELEMENT_TYPE

Constructor Summary

Constructors

Constructor and Description
DocumentElement(String name, Collection<Element> elements) Constructs a new DocumentElement.
DocumentElement(String name, Document value) Constructs a new DocumentElement.
DocumentElement(String name, DocumentElement value) Constructs a new DocumentElement with a single sub-document element.
DocumentElement(String name, Element... elements) Constructs a new DocumentElement.
DocumentElement(String name, List<Element> elements) Constructs a new DocumentElement.
DocumentElement(String name, List<Element> elements, boolean takeOwnership) Constructs a new DocumentElement.
DocumentElement(String name, List<Element> elements, boolean takeOwnership, long size) Constructs a new DocumentElement.

Method Summary

Methods

Modifier and Type	Method and Description
void	accept(Visitor visitor) Accepts the visitor and calls the Visitor.visitDocument(java.lang.String, java.util.List<com.allanbank.mongodb.bson.Element>) method.
Document	asDocument() Converts the object into a document.
DocumentReference	asDocumentReference() Returns this sub-document as a DocumentReference if it conforms to the MongoDB DBRef convention.
int	compareTo(Element otherElement)
boolean	contains(String name) Returns true if the document contains an element with the specified name.
boolean	equals(Object object) Determines if the passed object is of this same type as this object and if so that its fields are equal.
<E extends Element> List<E>	find(Class<E> clazz, String... nameRegexs) Returns the elements matching the path of regular expressions.
<E extends Element> E	findFirst(Class<E> clazz, String... nameRegexs) Returns the first element matching the path of regular expressions.
<E extends Element> E	get(Class<E> clazz, String name) Returns the element with the specified name and type or null if no element with that name and type exists.
Element	get(String name) Returns the element with the specified name or null if no element with that name exists.
Document	getDocument() Returns the element's document.
List<Element>	getElements() Returns the elements in the document.
ElementType	getType() Returns the type for the BSON type.
Document	getValueAsObject() Returns the value for BSON element as a Java Object type.
int	hashCode() Computes a reasonable hash code.
boolean	isDocumentReference() Returns true if this sub-document conforms to the MongoDB DBRef convention, false otherwise.
Iterator<Element>	iterator() Returns an iterator over the documents elements.
DocumentElement	withName(String name) Creates a new element with the same type and value as this element but with the specified name.

Methods inherited from class com.allanbank.mongodb.bson.element.AbstractElement

asElement, find, findFirst, getName, getValueAsString, nullSafeEquals, size, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.allanbank.mongodb.bson.Document

find, findFirst, size

Field Detail

EMPTY_ELEMENTS

public static final List<Element> EMPTY_ELEMENTS

The empty list of elements.

TYPE

public static final ElementType TYPE

The BSON type for a document.

Constructor Detail

DocumentElement

public DocumentElement(String name,
               Collection<Element> elements)

Constructs a new DocumentElement.

Parameters:

name - The name for the BSON document.

elements - The sub-elements for the document.

Throws:

IllegalArgumentException - If the name is null.

DocumentElement

public DocumentElement(String name,
               Document value)

Constructs a new DocumentElement.

Parameters:

name - The name for the BSON document.

value - The document to copy elements from.

Throws:

IllegalArgumentException - If the name or value is null.

DocumentElement

public DocumentElement(String name,
               DocumentElement value)

Constructs a new DocumentElement with a single sub-document element.

Parameters:

name - The name for the BSON document.

value - The document to copy elements from.

Throws:

IllegalArgumentException - If the name or value is null.

DocumentElement

public DocumentElement(String name,
               Element... elements)

Constructs a new DocumentElement.

Parameters:

name - The name for the BSON document.

elements - The sub-elements for the document.

Throws:

IllegalArgumentException - If the name is null.

DocumentElement

public DocumentElement(String name,
               List<Element> elements)

Constructs a new DocumentElement.

Parameters:

name - The name for the BSON document.

elements - The sub-elements for the document.

Throws:

IllegalArgumentException - If the name is null.

DocumentElement

public DocumentElement(String name,
               List<Element> elements,
               boolean takeOwnership)

Constructs a new DocumentElement.

Parameters:

name - The name for the BSON document.

elements - The sub-elements for the document.

takeOwnership - If true this element takes ownership of the list to avoid a copy of the list.

DocumentElement

public DocumentElement(String name,
               List<Element> elements,
               boolean takeOwnership,
               long size)

Constructs a new DocumentElement.

Parameters:

name - The name for the BSON document.

elements - The sub-elements for the document.

takeOwnership - If true this element takes ownership of the list to avoid a copy of the list.

size - The size of the element when encoded in bytes. If not known then use the DocumentElement(String, List, boolean) constructor instead.

Method Detail

accept

public void accept(Visitor visitor)

Accepts the visitor and calls the Visitor.visitDocument(java.lang.String, java.util.List<com.allanbank.mongodb.bson.Element>) method.

Specified by:

accept in interface Document

Specified by:

accept in interface Element

Parameters:

visitor - THe visitor for the document.

See Also:

Element.accept(Visitor)

asDocument

public Document asDocument()

Converts the object into a document.

Returns this element.

Specified by:

asDocument in interface DocumentAssignable

Returns:

The object as a Document.

asDocumentReference

public DocumentReference asDocumentReference()

Returns this sub-document as a DocumentReference if it conforms to the MongoDB DBRef convention. Returns null otherwise.

A DocumentReference contains (order matters):

1. The name of the collection where the referenced document resides: $ref.
2. The value of the _id field in the referenced document: $id.
3. The name of the database where the referenced document resides: $db (Optional).

Returns:

This sub-document as a DocumentReference if it conforms to the MongoDB DBRef convention. Returns null otherwise.

See Also:

isDocumentReference(), MongoDB DBRef Information

compareTo

public int compareTo(Element otherElement)

Overridden to compare the elements based on the tuple (name, type, value).

Overridden to compare the elements based on the tuple (name, type). Derived classes are responsible for the value portion of the full comparison.

Overridden to compare the elements of the document if the base class comparison is equals.

Specified by:

compareTo in interface Element

Specified by:

compareTo in interface Comparable<Element>

Overrides:

compareTo in class AbstractElement

contains

public boolean contains(String name)

Returns true if the document contains an element with the specified name.

Specified by:

contains in interface Document

Parameters:

name - The name of the element to locate.

Returns:

True if the document contains an element with the given name, false otherwise.

See Also:

Document.contains(String)

equals

public boolean equals(Object object)

Determines if the passed object is of this same type as this object and if so that its fields are equal.

Overrides:

equals in class AbstractElement

Parameters:

object - The object to compare to.

See Also:

Object.equals(java.lang.Object)

find

public <E extends Element> List<E> find(Class<E> clazz,
                               String... nameRegexs)

Returns the elements matching the path of regular expressions.

Returns a singleton list if the nameRegexs is empty and this element's type is assignable to E. An empty list otherwise.

Searches this sub-elements for matching elements on the path and are of the right type.

Specified by:

find in interface Document

Specified by:

find in interface Element

Overrides:

find in class AbstractElement

Type Parameters:

E - The type of element to match.

Parameters:

clazz - The class of elements to match.

nameRegexs - The path of regular expressions.

Returns:

The elements matching the path of regular expressions.

See Also:

Element.find(java.lang.Class<E>, java.lang.String...)

findFirst

public <E extends Element> E findFirst(Class<E> clazz,
                              String... nameRegexs)

Returns the first element matching the path of regular expressions.

Returns a this if the nameRegexs is empty and this element's type is assignable to E. An empty list otherwise.

Searches this sub-elements for matching elements on the path and are of the right type.

Specified by:

findFirst in interface Document

Specified by:

findFirst in interface Element

Overrides:

findFirst in class AbstractElement

Type Parameters:

E - The type of element to match.

Parameters:

clazz - The class of element to match.

nameRegexs - The path of regular expressions.

Returns:

The first element matching the path of regular expressions.

See Also:

Element.findFirst(java.lang.Class<E>, java.lang.String...)

get

public <E extends Element> E get(Class<E> clazz,
                        String name)

Returns the element with the specified name and type or null if no element with that name and type exists.

Specified by:

get in interface Document

Type Parameters:

E - The type of element to get.

Parameters:

clazz - The class of element to get.

name - The name of the element to locate.

Returns:

The sub-element in the document with the given name or null if element exists with the given name.

See Also:

Document.get(Class, String)

get

public Element get(String name)

Returns the element with the specified name or null if no element with that name exists.

Specified by:

get in interface Document

Parameters:

name - The name of the element to locate.

Returns:

The sub-element in the document with the given name or null if element exists with the given name.

See Also:

Document.get(String)

getDocument

public Document getDocument()

Returns the element's document.

Returns:

The document contained within the element.

getElements

public List<Element> getElements()

Returns the elements in the document.

Specified by:

getElements in interface Document

Returns:

The elements in the document.

getType

public ElementType getType()

Returns the type for the BSON type.

Specified by:

getType in interface Element

Returns:

The type for the BSON type.

getValueAsObject

public Document getValueAsObject()

Returns the value for BSON element as a Java Object type.

Automatic conversion from the Object-ified value to an element is provided via the DocumentBuilder.add(String, Object) method. Not all element types will be successfully converted to the same element duing a Element-->Object value-->Element conversion. This cases are noted in the appropriate sub-type's JavaDoc.

Sub-types will also overload this method with the appropriate type returned. e.g., The StringElement.getValueAsObject() method signature returns a String.

Returns a stand-alone Document.

Specified by:

getValueAsObject in interface Element

Returns:

The value for BSON element as a Java Object type.

hashCode

public int hashCode()

Computes a reasonable hash code.

Overrides:

hashCode in class AbstractElement

Returns:

The hash code value.

isDocumentReference

public boolean isDocumentReference()

Returns true if this sub-document conforms to the MongoDB DBRef convention, false otherwise.

A DocumentReference contains (order matters):

1. The name (string or symbol) of the collection where the referenced document resides: $ref.
2. The value of the _id field in the referenced document: $id.
3. The name (string or symbol) of the database where the referenced document resides: $db (Optional).

Returns:

True if this sub-document conforms to the MongoDB DBRef convention, false otherwise.

See Also:

asDocumentReference(), DocumentReference, MongoDB DBRef Information

iterator

public Iterator<Element> iterator()

Returns an iterator over the documents elements.

Specified by:

iterator in interface Iterable<Element>

See Also:

Iterable.iterator()

withName

public DocumentElement withName(String name)

Creates a new element with the same type and value as this element but with the specified name. This is useful when creating a query across a set of collections where the filed name changes in the collections but the values must be identical.

Returns a new DocumentElement.

Specified by:

withName in interface Element

Parameters:

name - The new name for the element.

Returns:

The created element.