/*
 * Copyright 2008-present MongoDB, 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.
 */

package com.mongodb.client.gridfs;

import com.mongodb.client.MongoIterable;
import com.mongodb.client.gridfs.model.GridFSFile;
import com.mongodb.client.model.Collation;
import com.mongodb.lang.Nullable;
import org.bson.conversions.Bson;

import java.util.concurrent.TimeUnit;

Iterable for the GridFS Files Collection.
Since:
3.1/**
 * Iterable for the GridFS Files Collection.
 *
 * @since 3.1
 */
public interface GridFSFindIterable extends MongoIterable<GridFSFile> {

    
Sets the query filter to apply to the query.

    Below is an example of filtering against the filename and some nested metadata that can also be stored along with the file data:
 

     Filters.and(Filters.eq("filename", "mongodb.png"), Filters.eq("metadata.contentType", "image/png"));
  
Params:
filter – the filter, which may be null.
See Also:
Filters
Returns:
this
@mongodb.driver.manual
reference/method/db.collection.find/ Filter/**
     * Sets the query filter to apply to the query.
     *
     * <p>
     *     Below is an example of filtering against the filename and some nested metadata that can also be stored along with the file data:
     *  <pre>
     *  {@code
     *      Filters.and(Filters.eq("filename", "mongodb.png"), Filters.eq("metadata.contentType", "image/png"));
     *  }
     *  </pre>
     *
     * @param filter the filter, which may be null.
     * @return this
     * @mongodb.driver.manual reference/method/db.collection.find/ Filter
     * @see com.mongodb.client.model.Filters
     */
    GridFSFindIterable filter(@Nullable Bson filter);

    
Sets the limit to apply.
Params:
limit – the limit, which may be null
Returns:
this
@mongodb.driver.manual
reference/method/cursor.limit/#cursor.limit Limit/**
     * Sets the limit to apply.
     *
     * @param limit the limit, which may be null
     * @return this
     * @mongodb.driver.manual reference/method/cursor.limit/#cursor.limit Limit
     */
    GridFSFindIterable limit(int limit);

    
Sets the number of documents to skip.
Params:
skip – the number of documents to skip
Returns:
this
@mongodb.driver.manual
reference/method/cursor.skip/#cursor.skip Skip/**
     * Sets the number of documents to skip.
     *
     * @param skip the number of documents to skip
     * @return this
     * @mongodb.driver.manual reference/method/cursor.skip/#cursor.skip Skip
     */
    GridFSFindIterable skip(int skip);

    
Sets the sort criteria to apply to the query.
Params:
sort – the sort criteria, which may be null.
Returns:
this
@mongodb.driver.manual
reference/method/cursor.sort/ Sort/**
     * Sets the sort criteria to apply to the query.
     *
     * @param sort the sort criteria, which may be null.
     * @return this
     * @mongodb.driver.manual reference/method/cursor.sort/ Sort
     */
    GridFSFindIterable sort(@Nullable Bson sort);

    
The server normally times out idle cursors after an inactivity period (10 minutes)
to prevent excess memory use. Set this option to prevent that.
Params:
noCursorTimeout – true if cursor timeout is disabled
Returns:
this/**
     * The server normally times out idle cursors after an inactivity period (10 minutes)
     * to prevent excess memory use. Set this option to prevent that.
     *
     * @param noCursorTimeout true if cursor timeout is disabled
     * @return this
     */
    GridFSFindIterable noCursorTimeout(boolean noCursorTimeout);

    
Sets the maximum execution time on the server for this operation.
Params:
maxTime –  the max time
timeUnit – the time unit, which may not be null
Returns:
this
@mongodb.driver.manual
reference/method/cursor.maxTimeMS/#cursor.maxTimeMS Max Time/**
     * Sets the maximum execution time on the server for this operation.
     *
     * @param maxTime  the max time
     * @param timeUnit the time unit, which may not be null
     * @return this
     * @mongodb.driver.manual reference/method/cursor.maxTimeMS/#cursor.maxTimeMS Max Time
     */
    GridFSFindIterable maxTime(long maxTime, TimeUnit timeUnit);

    
Sets the number of documents to return per batch.
Params:
batchSize – the batch size
Returns:
this
@mongodb.driver.manual
reference/method/cursor.batchSize/#cursor.batchSize Batch Size/**
     * Sets the number of documents to return per batch.
     *
     * @param batchSize the batch size
     * @return this
     * @mongodb.driver.manual reference/method/cursor.batchSize/#cursor.batchSize Batch Size
     */
    @Override
    GridFSFindIterable batchSize(int batchSize);

    
Sets the collation options
A null value represents the server default.
Params:
collation – the collation options to use
Returns:
this
Since:
3.4
@mongodb.server.release
3.4/**
     * Sets the collation options
     *
     * <p>A null value represents the server default.</p>
     * @param collation the collation options to use
     * @return this
     * @since 3.4
     * @mongodb.server.release 3.4
     */
    GridFSFindIterable collation(@Nullable Collation collation);
}