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 }