1 /*
2 * #%L
3 * MongoIterator.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;
21
22 import java.util.Iterator;
23 import java.util.List;
24
25 /**
26 * MongoIterator provides an interface for an iterator that can be closed.
27 * <p>
28 * In addition the batch size for the next request for documents from the cursor
29 * can be set.
30 * </p>
31 *
32 * @param <T>
33 * The type of elements being iterated over.
34 *
35 * @api.yes This interface is part of the driver's API. Public and protected
36 * members will be deprecated for at least 1 non-bugfix release
37 * (version numbers are <major>.<minor>.<bugfix>)
38 * before being removed or modified.
39 * @copyright 2012-2013, Allanbank Consulting, Inc., All Rights Reserved
40 */
41 @SuppressWarnings({ "deprecation", "unused" })
42 public interface MongoIterator<T> extends Iterator<T>, Iterable<T>,
43 MongoCursorControl, ClosableIterator<T> {
44 /**
45 * Consumes all of the elements in the iterator and returns them in a single
46 * array.
47 * <p>
48 * WARNING: This method loads all of the iterator results into memory and
49 * may cause an {@link OutOfMemoryError}.
50 * </p>
51 *
52 * @return The remaining elements in the iterator.
53 */
54 Object[] toArray();
55
56 /**
57 * Consumes all of the elements in the iterator and returns them in a single
58 * array.
59 * <p>
60 * WARNING: This method loads all of the iterator results into memory and
61 * may cause an {@link OutOfMemoryError}.
62 * </p>
63 *
64 * @param <S>
65 * The type of elements in the array.
66 * @param to
67 * The array to copy into. If not the right size a new array will
68 * be allocated of the right size.
69 *
70 * @return The remaining elements in the iterator.
71 */
72 <S> S[] toArray(S[] to);
73
74 /**
75 * Consumes all of the elements in the iterator and returns them in a single
76 * mutable list.
77 * <p>
78 * WARNING: This method loads all of the iterator results into memory and
79 * may cause an {@link OutOfMemoryError}.
80 * </p>
81 *
82 * @return The remaining elements in the iterator.
83 */
84 List<T> toList();
85 }