com.allanbank.mongodb.bson.element

Class ArrayElement

java.lang.Object

com.allanbank.mongodb.bson.element.AbstractElement

com.allanbank.mongodb.bson.element.ArrayElement

All Implemented Interfaces:

Element, ElementAssignable, Serializable, Comparable<Element>

public class ArrayElement
extends AbstractElement

A wrapper for a BSON array.

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 ElementType	TYPE The BSON type for an array.

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

ELEMENT_TYPE

Constructor Summary

Constructors

Constructor and Description
ArrayElement(String name, Element... entries) Constructs a new ArrayElement.
ArrayElement(String name, List<Element> entries) Constructs a new ArrayElement.
ArrayElement(String name, List<Element> entries, long size) Constructs a new ArrayElement.

Method Summary

Methods

Modifier and Type	Method and Description
void	accept(Visitor visitor) Accepts the visitor and calls the Visitor.visitArray(String, List) method.
int	compareTo(Element otherElement)
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.
List<Element>	getEntries() Returns the entries in the array.
ElementType	getType() Returns the type for the BSON type.
Element[]	getValueAsObject() Returns the value for BSON element as a Java Object type.
int	hashCode() Computes a reasonable hash code.
static String	nameFor(int index) Similar to the caching of Integer object values for a range we cache the index names for an array's first 256 positions.
ArrayElement	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

Field Detail

TYPE

public static final ElementType TYPE

The BSON type for an array.

Constructor Detail

ArrayElement

public ArrayElement(String name,
            Element... entries)
             throws IllegalArgumentException

Constructs a new ArrayElement.

Parameters:

name - The name for the BSON array.

entries - The entries in the array.

Throws:

IllegalArgumentException - If the name is null.

ArrayElement

public ArrayElement(String name,
            List<Element> entries)
             throws IllegalArgumentException

Constructs a new ArrayElement.

Parameters:

name - The name for the BSON array.

entries - The entries in the array.

Throws:

IllegalArgumentException - If the name is null.

ArrayElement

public ArrayElement(String name,
            List<Element> entries,
            long size)
             throws IllegalArgumentException

Constructs a new ArrayElement.

Parameters:

name - The name for the BSON array.

entries - The entries in the array.

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

Throws:

IllegalArgumentException - If the name is null.

Method Detail

nameFor

public static final String nameFor(int index)

Similar to the caching of Integer object values for a range we cache the index names for an array's first 256 positions.

Parameters:

index - The index for the array element.

Returns:

The name of the value at that index.

accept

public void accept(Visitor visitor)

Accepts the visitor and calls the Visitor.visitArray(String, List) method.

Parameters:

visitor - The visitor for the element.

See Also:

Element.accept(Visitor)

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 array 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

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 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 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...)

getEntries

public List<Element> getEntries()

Returns the entries in the array. The name attribute will be ignored when encoding the elements. When decoded the names will be the strings 0, 1, 2, 3, etc..

Returns:

The entries in the array.

getType

public ElementType getType()

Returns the type for the BSON type.

Returns:

The type for the BSON type.

getValueAsObject

public Element[] 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 an 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.

withName

public ArrayElement 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 ArrayElement.

Parameters:

name - The new name for the element.

Returns:

The created element.