Coverage Report

Coverage Report - com.allanbank.mongodb.MongoCursorControl

Classes in this File

 /*
  * #%L
  * MongoCursorControl.java - mongodb-async-driver - Allanbank Consulting, Inc.
  * %%
  * Copyright (C) 2011 - 2014 Allanbank Consulting, Inc.
  * %%
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  * 
  *      http://www.apache.org/licenses/LICENSE-2.0
  * 
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  * #L%
  */
 package com.allanbank.mongodb;
 
 import java.io.Closeable;
 
 import com.allanbank.mongodb.bson.Document;
 import com.allanbank.mongodb.builder.Find;
 
 /**
  * MongoCursorControl provides the controls for a MongoDB cursor interaction.
  * Normally this interface is used via a {@link MongoIterator} but in the case
  * of streaming only the controls are returned.
  * 
  * @api.yes This interface is part of the driver's API. Public and protected
  *          members will be deprecated for at least 1 non-bugfix release
  *          (version numbers are &lt;major&gt;.&lt;minor&gt;.&lt;bugfix&gt;)
  *          before being removed or modified.
  * @copyright 2013, Allanbank Consulting, Inc., All Rights Reserved
  */
 public interface MongoCursorControl extends Closeable {
     /** The batch size field in the cursor document. */
     public static final String BATCH_SIZE_FIELD = "batch_size";
 
     /** The cursor id field in the cursor document. */
     public static final String CURSOR_ID_FIELD = "cursor_id";
 
     /** The remaining limit field in the cursor document. */
     public static final String LIMIT_FIELD = "limit";
 
     /** The name space field in the cursor document. */
     public static final String NAME_SPACE_FIELD = "ns";
 
     /** The server name field in the cursor document. */
     public static final String SERVER_FIELD = "server";
 
     /**
      * Returns a {@link Document} that can be used to restart the
      * cursor/iterator.
      * <p>
      * If this iterator is exhausted or closed then the cursor is also closed on
      * the server and this method will return null.
      * </p>
      * <p>
      * If the cursor/{@link Find} was not created with out a timeout then
      * eventually the server will automatically remove the cursor and the
      * restart will fail.
      * </p>
      * <p>
      * Returns the active cursor in the form:<blockquote>
      * 
      * <pre>
      * <code>
      * {
      *     {@value #NAME_SPACE_FIELD} : '&lt;database_name&gt;.$lt;collection_name&gt;',
      *     {@value #CURSOR_ID_FIELD} : &lt;cursor_id&gt;,
      *     {@value #SERVER_FIELD} : '&lt;server&gt;',
      *     {@value #LIMIT_FIELD} : &lt;remaining_limit&gt;
      *     {@value #BATCH_SIZE_FIELD} : &lt;batch_size&gt;
      * }</code>
      * </pre>
      * 
      * </blockquote>
      * 
      * @return A document that can be used to restart the cursor.
      *         <code>null</code> if the server's cursor has been exhausted or
      *         closed.
      */
     public Document asDocument();
 
     /**
      * Close the iterator and release any resources it is holding.
      */
     @Override
     public void close();
 
     /**
      * Returns the size for batches of documents that are requested.
      * 
      * @return The size of the batches of documents that are requested.
      */
     public int getBatchSize();
 
     /**
      * Sets the size for future batch sizes.
      * 
      * @param batchSize
      *            The size to request for future batch sizes.
      */
     public void setBatchSize(int batchSize);
 
     /**
      * Stops the iterator after consuming any received and/or requested batches.
      * <p>
      * <b>WARNING</b>: This will leave the cursor open on the server. Even a
      * {@link #close()} on this object will not close the cursor on the server.
      * Users should persist the state of the cursor as returned from
      * {@link #asDocument()} and restart the cursor using one of the
      * {@link MongoClient#restart(com.allanbank.mongodb.bson.DocumentAssignable)}
      * or
      * {@link MongoClient#restart(StreamCallback, com.allanbank.mongodb.bson.DocumentAssignable)}
      * methods. Use {@link #stop()} with extreme caution.
      * </p>
      * <p>
      * The iterator or stream will naturally stop (
      * {@link MongoIterator#hasNext()} will return false or the stream's call
      * back {@link StreamCallback#done()} method will be called) when the
      * current batch and any batches already requested are exhausted.
      * </p>
      */
     public void stop();
 
 }

1		/*
2		* #%L
3		* MongoCursorControl.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.io.Closeable;
23
24		import com.allanbank.mongodb.bson.Document;
25		import com.allanbank.mongodb.builder.Find;
26
27		/**
28		* MongoCursorControl provides the controls for a MongoDB cursor interaction.
29		* Normally this interface is used via a {@link MongoIterator} but in the case
30		* of streaming only the controls are returned.
31		*
32		* @api.yes This interface is part of the driver's API. Public and protected
33		* members will be deprecated for at least 1 non-bugfix release
34		* (version numbers are <major>.<minor>.<bugfix>)
35		* before being removed or modified.
36		* @copyright 2013, Allanbank Consulting, Inc., All Rights Reserved
37		*/
38		public interface MongoCursorControl extends Closeable {
39		/** The batch size field in the cursor document. */
40		public static final String BATCH_SIZE_FIELD = "batch_size";
41
42		/** The cursor id field in the cursor document. */
43		public static final String CURSOR_ID_FIELD = "cursor_id";
44
45		/** The remaining limit field in the cursor document. */
46		public static final String LIMIT_FIELD = "limit";
47
48		/** The name space field in the cursor document. */
49		public static final String NAME_SPACE_FIELD = "ns";
50
51		/** The server name field in the cursor document. */
52		public static final String SERVER_FIELD = "server";
53
54		/**
55		* Returns a {@link Document} that can be used to restart the
56		* cursor/iterator.
57		* <p>
58		* If this iterator is exhausted or closed then the cursor is also closed on
59		* the server and this method will return null.
60		* </p>
61		* <p>
62		* If the cursor/{@link Find} was not created with out a timeout then
63		* eventually the server will automatically remove the cursor and the
64		* restart will fail.
65		* </p>
66		* <p>
67		* Returns the active cursor in the form:<blockquote>
68		*
69		* <pre>
70		* <code>
71		* {
72		* {@value #NAME_SPACE_FIELD} : '<database_name>.$lt;collection_name>',
73		* {@value #CURSOR_ID_FIELD} : <cursor_id>,
74		* {@value #SERVER_FIELD} : '<server>',
75		* {@value #LIMIT_FIELD} : <remaining_limit>
76		* {@value #BATCH_SIZE_FIELD} : <batch_size>
77		* }</code>
78		* </pre>
79		*
80		* </blockquote>
81		*
82		* @return A document that can be used to restart the cursor.
83		* <code>null</code> if the server's cursor has been exhausted or
84		* closed.
85		*/
86		public Document asDocument();
87
88		/**
89		* Close the iterator and release any resources it is holding.
90		*/
91		@Override
92		public void close();
93
94		/**
95		* Returns the size for batches of documents that are requested.
96		*
97		* @return The size of the batches of documents that are requested.
98		*/
99		public int getBatchSize();
100
101		/**
102		* Sets the size for future batch sizes.
103		*
104		* @param batchSize
105		* The size to request for future batch sizes.
106		*/
107		public void setBatchSize(int batchSize);
108
109		/**
110		* Stops the iterator after consuming any received and/or requested batches.
111		* <p>
112		* <b>WARNING</b>: This will leave the cursor open on the server. Even a
113		* {@link #close()} on this object will not close the cursor on the server.
114		* Users should persist the state of the cursor as returned from
115		* {@link #asDocument()} and restart the cursor using one of the
116		* {@link MongoClient#restart(com.allanbank.mongodb.bson.DocumentAssignable)}
117		* or
118		* {@link MongoClient#restart(StreamCallback, com.allanbank.mongodb.bson.DocumentAssignable)}
119		* methods. Use {@link #stop()} with extreme caution.
120		* </p>
121		* <p>
122		* The iterator or stream will naturally stop (
123		* {@link MongoIterator#hasNext()} will return false or the stream's call
124		* back {@link StreamCallback#done()} method will be called) when the
125		* current batch and any batches already requested are exhausted.
126		* </p>
127		*/
128		public void stop();
129
130		}