Coverage Report

Coverage Report - com.allanbank.mongodb.bson.Element

Classes in this File

 /*
  * #%L
  * Element.java - mongodb-async-driver - Allanbank Consulting, Inc.
  * %%
  * Copyright (C) 2011 - 2014 Allanbank Consulting, Inc.
  * %%
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  * 
  *      http://www.apache.org/licenses/LICENSE-2.0
  * 
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  * #L%
  */
 package com.allanbank.mongodb.bson;
 
 import java.io.Serializable;
 import java.util.List;
 
 import com.allanbank.mongodb.bson.builder.DocumentBuilder;
 import com.allanbank.mongodb.bson.element.JsonSerializationVisitor;
 import com.allanbank.mongodb.bson.element.TimestampElement;
 
 /**
  * A common interface for the basic BSON types used to construct Documents and
  * arrays.
  * 
  * @api.yes This interface is part of the driver's API. Public and protected
  *          members will be deprecated for at least 1 non-bugfix release
  *          (version numbers are &lt;major&gt;.&lt;minor&gt;.&lt;bugfix&gt;)
  *          before being removed or modified.
  * @copyright 2011-2013, Allanbank Consulting, Inc., All Rights Reserved
  */
 public interface Element extends Serializable, ElementAssignable,
         Comparable<Element> {
 
     /**
      * Accepts the visitor and calls the appropriate method on the visitor based
      * on the element type.
      * 
      * @param visitor
      *            The visitor for the element.
      */
     public void accept(Visitor visitor);
 
     /**
      * {@inheritDoc}
      * <p>
      * Overridden to compare the elements based on the tuple (name, type,
      * value).
      * </p>
      */
     @Override
     public int compareTo(Element otherElement);
 
     /**
      * Returns the elements matching the path of regular expressions.
      * 
      * @param <E>
      *            The type of element to match.
      * @param clazz
      *            The class of elements to match.
      * @param nameRegexs
      *            The path of regular expressions.
      * @return The elements matching the path of regular expressions.
      */
     public <E extends Element> List<E> find(Class<E> clazz,
             String... nameRegexs);
 
     /**
      * Returns the elements matching the path of regular expressions.
      * 
      * @param nameRegexs
      *            The path of regular expressions.
      * @return The elements matching the path of regular expressions.
      */
     public List<Element> find(String... nameRegexs);
 
     /**
      * Returns the first element matching the path of regular expressions.
      * 
      * @param <E>
      *            The type of element to match.
      * @param clazz
      *            The class of element to match.
      * @param nameRegexs
      *            The path of regular expressions.
      * @return The first element matching the path of regular expressions.
      */
     public <E extends Element> E findFirst(Class<E> clazz, String... nameRegexs);
 
     /**
      * Returns the first element matching the path of regular expressions.
      * 
      * @param nameRegexs
      *            The path of regular expressions.
      * @return The first element matching the path of regular expressions.
      */
     public Element findFirst(String... nameRegexs);
 
     /**
      * Returns the name for the BSON type.
      * 
      * @return The name for the BSON type.
      */
     public String getName();
 
     /**
      * Returns the type for the BSON type.
      * 
      * @return The type for the BSON type.
      */
     public ElementType getType();
 
     /**
      * Returns the value for BSON element as a Java {@link Object} type.
      * <p>
      * Automatic conversion from the Object-ified value to an element is
      * provided via the {@link 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.
      * <p>
      * Sub-types will also overload this method with the appropriate type
      * returned. e.g., The
      * {@link com.allanbank.mongodb.bson.element.StringElement#getValueAsObject()}
      * method signature returns a {@link String}.
      * </p>
      * 
      * @return The value for BSON element as a Java {@link Object} type.
      */
     public Object getValueAsObject();
 
     /**
      * Returns the value for BSON element as a Java {@link String}. Automatic
      * conversion from the string value back to an Element is not provided.
      * <p>
      * Generally the string returned will be the expected value. As an example
      * for a LongElement with the value 101 the returned string will be "101".
      * In those cases where there is not canonical form for the value (e.g., a
      * {@link com.allanbank.mongodb.bson.element.TimestampElement} the returned
      * string will match the value when converted to JSON by the
      * {@link JsonSerializationVisitor}. For a {@link TimestampElement} that is
      * a string of the form "ISODate('1970-01-01T00:00:00.000+0000')".
      * </p>
      * 
      * @return The value for BSON element as a {@link String}.
      */
     public String getValueAsString();
 
     /**
      * Returns the number of bytes that are used to encode the element.
      * 
      * @return The bytes that are used to encode the element.
      */
     public long size();
 
     /**
      * 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.
      * 
      * @param name
      *            The new name for the element.
      * @return The created element.
      */
     public Element withName(String name);
 
 }

1		/*
2		* #%L
3		* Element.java - mongodb-async-driver - Allanbank Consulting, Inc.
4		* %%
5		* Copyright (C) 2011 - 2014 Allanbank Consulting, Inc.
6		* %%
7		* Licensed under the Apache License, Version 2.0 (the "License");
8		* you may not use this file except in compliance with the License.
9		* You may obtain a copy of the License at
10		*
11		* http://www.apache.org/licenses/LICENSE-2.0
12		*
13		* Unless required by applicable law or agreed to in writing, software
14		* distributed under the License is distributed on an "AS IS" BASIS,
15		* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16		* See the License for the specific language governing permissions and
17		* limitations under the License.
18		* #L%
19		*/
20		package com.allanbank.mongodb.bson;
21
22		import java.io.Serializable;
23		import java.util.List;
24
25		import com.allanbank.mongodb.bson.builder.DocumentBuilder;
26		import com.allanbank.mongodb.bson.element.JsonSerializationVisitor;
27		import com.allanbank.mongodb.bson.element.TimestampElement;
28
29		/**
30		* A common interface for the basic BSON types used to construct Documents and
31		* arrays.
32		*
33		* @api.yes This interface is part of the driver's API. Public and protected
34		* members will be deprecated for at least 1 non-bugfix release
35		* (version numbers are <major>.<minor>.<bugfix>)
36		* before being removed or modified.
37		* @copyright 2011-2013, Allanbank Consulting, Inc., All Rights Reserved
38		*/
39		public interface Element extends Serializable, ElementAssignable,
40		Comparable<Element> {
41
42		/**
43		* Accepts the visitor and calls the appropriate method on the visitor based
44		* on the element type.
45		*
46		* @param visitor
47		* The visitor for the element.
48		*/
49		public void accept(Visitor visitor);
50
51		/**
52		* {@inheritDoc}
53		* <p>
54		* Overridden to compare the elements based on the tuple (name, type,
55		* value).
56		* </p>
57		*/
58		@Override
59		public int compareTo(Element otherElement);
60
61		/**
62		* Returns the elements matching the path of regular expressions.
63		*
64		* @param <E>
65		* The type of element to match.
66		* @param clazz
67		* The class of elements to match.
68		* @param nameRegexs
69		* The path of regular expressions.
70		* @return The elements matching the path of regular expressions.
71		*/
72		public <E extends Element> List<E> find(Class<E> clazz,
73		String... nameRegexs);
74
75		/**
76		* Returns the elements matching the path of regular expressions.
77		*
78		* @param nameRegexs
79		* The path of regular expressions.
80		* @return The elements matching the path of regular expressions.
81		*/
82		public List<Element> find(String... nameRegexs);
83
84		/**
85		* Returns the first element matching the path of regular expressions.
86		*
87		* @param <E>
88		* The type of element to match.
89		* @param clazz
90		* The class of element to match.
91		* @param nameRegexs
92		* The path of regular expressions.
93		* @return The first element matching the path of regular expressions.
94		*/
95		public <E extends Element> E findFirst(Class<E> clazz, String... nameRegexs);
96
97		/**
98		* Returns the first element matching the path of regular expressions.
99		*
100		* @param nameRegexs
101		* The path of regular expressions.
102		* @return The first element matching the path of regular expressions.
103		*/
104		public Element findFirst(String... nameRegexs);
105
106		/**
107		* Returns the name for the BSON type.
108		*
109		* @return The name for the BSON type.
110		*/
111		public String getName();
112
113		/**
114		* Returns the type for the BSON type.
115		*
116		* @return The type for the BSON type.
117		*/
118		public ElementType getType();
119
120		/**
121		* Returns the value for BSON element as a Java {@link Object} type.
122		* <p>
123		* Automatic conversion from the Object-ified value to an element is
124		* provided via the {@link DocumentBuilder#add(String, Object)} method. Not
125		* all element types will be successfully converted to the same element
126		* duing a Element-->Object value-->Element conversion. This cases are noted
127		* in the appropriate sub-type's JavaDoc.
128		* <p>
129		* Sub-types will also overload this method with the appropriate type
130		* returned. e.g., The
131		* {@link com.allanbank.mongodb.bson.element.StringElement#getValueAsObject()}
132		* method signature returns a {@link String}.
133		* </p>
134		*
135		* @return The value for BSON element as a Java {@link Object} type.
136		*/
137		public Object getValueAsObject();
138
139		/**
140		* Returns the value for BSON element as a Java {@link String}. Automatic
141		* conversion from the string value back to an Element is not provided.
142		* <p>
143		* Generally the string returned will be the expected value. As an example
144		* for a LongElement with the value 101 the returned string will be "101".
145		* In those cases where there is not canonical form for the value (e.g., a
146		* {@link com.allanbank.mongodb.bson.element.TimestampElement} the returned
147		* string will match the value when converted to JSON by the
148		* {@link JsonSerializationVisitor}. For a {@link TimestampElement} that is
149		* a string of the form "ISODate('1970-01-01T00:00:00.000+0000')".
150		* </p>
151		*
152		* @return The value for BSON element as a {@link String}.
153		*/
154		public String getValueAsString();
155
156		/**
157		* Returns the number of bytes that are used to encode the element.
158		*
159		* @return The bytes that are used to encode the element.
160		*/
161		public long size();
162
163		/**
164		* Creates a new element with the same type and value as this element but
165		* with the specified name. This is useful when creating a query across a
166		* set of collections where the filed name changes in the collections but
167		* the values must be identical.
168		*
169		* @param name
170		* The new name for the element.
171		* @return The created element.
172		*/
173		public Element withName(String name);
174
175		}