View Javadoc
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 &lt;major&gt;.&lt;minor&gt;.&lt;bugfix&gt;)
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  }