1 /*
2 * #%L
3 * Visitor.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.util.List;
23
24 import com.allanbank.mongodb.bson.element.ArrayElement;
25 import com.allanbank.mongodb.bson.element.DocumentElement;
26 import com.allanbank.mongodb.bson.element.ObjectId;
27
28 /**
29 * Interface for callbacks to navigate the document structure. The accept method
30 * of each {@link Element} calls the appropriate Visit method in this interface
31 * The user is responsible for recursively navigating the structure.
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 Visitor {
40
41 /**
42 * Visit the root document.
43 * <p>
44 * Implementations of {@link Document} may see a significant performance
45 * enhancement if they ensure that the list of elements is the same list.
46 * (Identify check instead of {@link Object#equals(Object)}.
47 * </p>
48 *
49 * @param elements
50 * The sub elements of the document.
51 */
52 public void visit(List<Element> elements);
53
54 /**
55 * Visits an array of elements.
56 * <p>
57 * The {@link ArrayElement} implementation ensures that the list of elements
58 * is always the same list. Visitors may use this fact to cache intermediate
59 * results.
60 * </p>
61 *
62 * @param name
63 * The name of the element.
64 * @param elements
65 * The elements in the array.
66 */
67 public void visitArray(String name, List<Element> elements);
68
69 /**
70 * Visits a binary element.
71 *
72 * @param name
73 * The name of the element.
74 * @param subType
75 * The binary data sub type.
76 * @param data
77 * The binary data.
78 */
79 public void visitBinary(String name, byte subType, byte[] data);
80
81 /**
82 * Visits a boolean element.
83 *
84 * @param name
85 * The name of the element.
86 * @param value
87 * The boolean value.
88 */
89 public void visitBoolean(String name, boolean value);
90
91 /**
92 * Visits a deprecated DBPointer element.
93 *
94 * @param name
95 * The name of the element.
96 * @param databaseName
97 * The name of the database containing the document.
98 * @param collectionName
99 * The name of the collection containing the document.
100 * @param id
101 * The id for the document.
102 */
103 public void visitDBPointer(String name, String databaseName,
104 String collectionName, ObjectId id);
105
106 /**
107 * Visits a sub-document element.
108 * <p>
109 * The {@link DocumentElement} implementation ensures that the list of
110 * elements is always the same list. Visitors may use this fact to cache
111 * intermediate results.
112 * </p>
113 *
114 * @param name
115 * The name of the element.
116 * @param elements
117 * The sub elements of the document.
118 */
119 public void visitDocument(String name, List<Element> elements);
120
121 /**
122 * Visits a double element.
123 *
124 * @param name
125 * The name of the element.
126 * @param value
127 * The double value.
128 */
129 public void visitDouble(String name, double value);
130
131 /**
132 * Visits a integer (32-bit signed) element.
133 *
134 * @param name
135 * The name of the element.
136 * @param value
137 * The integer value.
138 */
139 public void visitInteger(String name, int value);
140
141 /**
142 * Visits a JavaScript element.
143 *
144 * @param name
145 * The name of the element.
146 * @param code
147 * The java script code.
148 */
149 public void visitJavaScript(String name, String code);
150
151 /**
152 * Visits a JavaScript with Scope element.
153 *
154 * @param name
155 * The name of the element.
156 * @param code
157 * The java script code.
158 * @param scope
159 * The scope for the JacaScript code.
160 */
161 public void visitJavaScript(String name, String code, Document scope);
162
163 /**
164 * Visits a long (64-bit signed) element.
165 *
166 * @param name
167 * The name of the element.
168 * @param value
169 * The long value.
170 */
171 public void visitLong(String name, long value);
172
173 /**
174 * Visits a minimum key value element. Used as an absolute upper bounds.
175 *
176 * @param name
177 * The name of the element.
178 */
179 public void visitMaxKey(String name);
180
181 /**
182 * Visits a minimum key value element. Used as an absolute lower bounds.
183 *
184 * @param name
185 * The name of the element.
186 */
187 public void visitMinKey(String name);
188
189 /**
190 * Visits a MongoDB Timestamp element.
191 *
192 * @param name
193 * The name of the element.
194 * @param value
195 * The mongoDB timstamp value.
196 */
197 public void visitMongoTimestamp(String name, long value);
198
199 /**
200 * Visits a <code>null</code> valued element.
201 *
202 * @param name
203 * The name of the element.
204 */
205 public void visitNull(String name);
206
207 /**
208 * Visits an ObjectId element.
209 *
210 * @param name
211 * The name of the element.
212 * @param id
213 * The object id.
214 */
215 public void visitObjectId(String name, ObjectId id);
216
217 /**
218 * Visits a regular expression element.
219 *
220 * @param name
221 * The name of the element.
222 * @param pattern
223 * The pattern for the regular expression.
224 * @param options
225 * The regular expression options. See the BSON specification for
226 * details.
227 */
228 public void visitRegularExpression(String name, String pattern,
229 String options);
230
231 /**
232 * Visits a string element.
233 *
234 * @param name
235 * The name of the element.
236 * @param value
237 * The string value.
238 */
239 public void visitString(String name, String value);
240
241 /**
242 * Visits a symbol element.
243 *
244 * @param name
245 * The name of the element.
246 * @param symbol
247 * The symbol value.
248 */
249 public void visitSymbol(String name, String symbol);
250
251 /**
252 * Visits a timestamp element. The timestamp is the number of milliseconds
253 * since the Unix epoch.
254 *
255 * @param name
256 * The name of the element.
257 * @param timestamp
258 * The number of milliseconds since the Unix epoch.
259 */
260 public void visitTimestamp(String name, long timestamp);
261 }