1 /*
2 * #%L
3 * Document.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 /**
26 * Interface for a document.
27 *
28 * @api.yes This interface is part of the driver's API. Public and protected
29 * members will be deprecated for at least 1 non-bugfix release
30 * (version numbers are <major>.<minor>.<bugfix>)
31 * before being removed or modified.
32 * @copyright 2011-2013, Allanbank Consulting, Inc., All Rights Reserved
33 */
34 public interface Document extends Iterable<Element>, DocumentAssignable,
35 Serializable {
36
37 /**
38 * Accepts the visitor and calls the appropriate method on the visitor based
39 * on the document type.
40 *
41 * @param visitor
42 * THe visitor for the document.
43 */
44 public void accept(Visitor visitor);
45
46 /**
47 * Returns true if the document contains an element with the specified name.
48 *
49 * @param name
50 * The name of the element to locate.
51 * @return True if the document contains an element with the given name,
52 * false otherwise.
53 */
54 public boolean contains(String name);
55
56 /**
57 * Returns the elements matching the path of regular expressions.
58 *
59 * @param <E>
60 * The type of element to match.
61 * @param clazz
62 * The class of elements to match.
63 * @param nameRegexs
64 * The path of regular expressions.
65 * @return The elements matching the path of regular expressions. May be an
66 * empty list but will never be <code>null</code>.
67 */
68 public <E extends Element> List<E> find(Class<E> clazz,
69 String... nameRegexs);
70
71 /**
72 * Returns the elements matching the path of regular expressions.
73 *
74 * @param nameRegexs
75 * The path of regular expressions.
76 * @return The elements matching the path of regular expressions. May be an
77 * empty list but will never be <code>null</code>.
78 */
79 public List<Element> find(String... nameRegexs);
80
81 /**
82 * Returns the first element matching the path of regular expressions.
83 * <p>
84 * Note: It is much faster to use the {@link #get(Class,String)} method on a
85 * document than to use the {@link #findFirst(String...)} with a single
86 * {@code nameRegexs}.
87 * </p>
88 *
89 * @param <E>
90 * The type of element to match.
91 * @param clazz
92 * The class of element to match.
93 * @param nameRegexs
94 * The path of regular expressions.
95 * @return The first element matching the path of regular expressions.
96 */
97 public <E extends Element> E findFirst(Class<E> clazz, String... nameRegexs);
98
99 /**
100 * Returns the first element matching the path of regular expressions.
101 * <p>
102 * Note: It is much faster to use the {@link #get(String)} method on a
103 * document than to use the {@link #findFirst(String...)} with a single
104 * {@code nameRegexs}.
105 * </p>
106 *
107 * @param nameRegexs
108 * The path of regular expressions.
109 * @return The first element matching the path of regular expressions.
110 */
111 public Element findFirst(String... nameRegexs);
112
113 /**
114 * Returns the element with the specified name or null if no element with
115 * that name exists.
116 *
117 * @param <E>
118 * The type of element to get.
119 * @param clazz
120 * The class of element to get.
121 * @param name
122 * The name of the element to locate.
123 * @return The sub-element in the document with the given name or null if
124 * element exists with the given name.
125 */
126 public <E extends Element> E get(Class<E> clazz, String name);
127
128 /**
129 * Returns the element with the specified name or null if no element with
130 * that name exists.
131 *
132 * @param name
133 * The name of the element to locate.
134 * @return The sub-element in the document with the given name or null if
135 * element exists with the given name.
136 */
137 public Element get(String name);
138
139 /**
140 * Returns the array of elements that create this document.
141 *
142 * @return The array of elements that create this document.
143 */
144 public List<Element> getElements();
145
146 /**
147 * Returns the size of the document when encoded as bytes.
148 *
149 * @return The size of the document when encoded as bytes.
150 */
151 public long size();
152 }