Something went wrong. Try again.
The next MongoDB driver for Kotlin ktmongo.opensavvy.dev
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132/* * Copyright (c) 2026, OpenSavvy and contributors. * * 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. */
package opensavvy.ktmongo.sync.api
/** * Streaming-capable iterable cursor to read data from the database. * * ### External resources * * - [Official documentation](https://www.mongodb.com/docs/manual/core/cursors/) */interface MongoIterable<Document : Any> {
/** * Returns the first document found by this query, or throws an exception. * * @throws NoSuchElementException If this query returned no results. * @see firstOrNull Return `null` instead of throwing an exception. */ fun first(): Document
/** * Returns the first document found by this query, or returns `null`. * * @see first Throw an exception instead of returning `null`. */ fun firstOrNull(): Document?
/** * Performs a client-side streaming mapping on the results. */ fun <Out : Any> map(transform: (Document) -> Out): MongoIterable<Out>
/** * Executes [action] for each document returned by this query. * * This method streams all returned documents into the [action] function. * The entire response set is not loaded at once into memory. * * MongoDB cursors are batched: a batch is queried, processed, then another batch is requested, etc. * The batch size can be configured in the operation creating this iterable. * * If the operation contains a sort without an index, MongoDB will load all results * into memory. The driver will still stream the results. * * @see toList Store all results in a [List]. * @see toSet Store all results in a [Set]. */ fun forEach(action: (Document) -> Unit)
/** * Reads the entirety of this iterable into a [List]. * * Since lists are in-memory, this method loads the entirety of the results into memory. * * @see forEach Execute an action for each result. * @see toSet Store all results in a [Set]. */ fun toList(): List<Document> { val list = ArrayList<Document>() forEach { list.add(it) } return list }
/** * Reads the entirety of this iterable into a [Set]. * * Since sets are in-memory, this method loads the entirety of the results into memory. * * @see forEach Execute an action for each result. * @see toList Store all results in a [List]. */ fun toSet(): Set<Document> { val set = HashSet<Document>() forEach { set.add(it) } return set }
/** * This method always throws an exception. * * Streaming a [MongoIterable] into a [Sequence] is not supported, because iterables * must be closed, and sequences cannot detect when iteration finishes. * * If you want to use a [Sequence] data structure for convenience, and the volume of data * is low, use [toList] followed by [asSequence][List.asSequence]. * All data will be loaded in memory at once. * * If streaming is important, either use [forEach], `stream` (Java-only). * * @see forEach Execute an action for each result. * @see toList Store all results in a [List]. * @see toSet Store all results in a [Set]. */ @Deprecated("Kotlin Sequences are not capable of closing a resource after they are done. Using sequences with a MongoIterable will create memory leaks. Instead, use toList, forEach, stream (Java only) or the coroutines driver's asFlow", ReplaceWith("this.toList().asSequence()"), level = DeprecationLevel.ERROR) fun asSequence(): Sequence<Document> = throw UnsupportedOperationException("Sequences are not supported because they create memory lists. Use lists, streams, or simply forEach instead.")
/** * This method always throws an exception. * * Streaming a [MongoIterable] into a [Sequence] is not supported, because iterables * must be closed, and sequences cannot detect when iteration finishes. * * If you want to use a [Sequence] data structure for convenience, and the volume of data * is low, use [toList] followed by [asSequence][List.asSequence]. * All data will be loaded in memory at once. * * If streaming is important, either use [forEach], `stream` (Java-only). * * @see forEach Execute an action for each result. * @see toList Store all results in a [List]. * @see toSet Store all results in a [Set]. */ @Deprecated("Kotlin Sequences are not capable of closing a resource after they are done. Using sequences with a MongoIterable will create memory leaks. Instead, use toList, forEach, stream (Java only) or the coroutines driver's asFlow", ReplaceWith("this.toList().asSequence()"), level = DeprecationLevel.ERROR) fun toSequence(): Sequence<Document> = throw UnsupportedOperationException("Sequences are not supported because they create memory lists. Use lists, streams, or simply forEach instead.")
}