Collection Operations & CRUD

/**
 * Generic MongoDB collection interface
 * @param <TDocument> The type of documents in the collection
 */
public interface MongoCollection<TDocument> {
    // Collection metadata
    MongoNamespace getNamespace();
    Class<TDocument> getDocumentClass();
    CodecRegistry getCodecRegistry();
    ReadPreference getReadPreference();
    WriteConcern getWriteConcern();
    ReadConcern getReadConcern();
    
    // Configuration variants
    <NewTDocument> MongoCollection<NewTDocument> withDocumentClass(Class<NewTDocument> clazz);
    MongoCollection<TDocument> withCodecRegistry(CodecRegistry codecRegistry);
    MongoCollection<TDocument> withReadPreference(ReadPreference readPreference);
    MongoCollection<TDocument> withWriteConcern(WriteConcern writeConcern);
    MongoCollection<TDocument> withReadConcern(ReadConcern readConcern);
}

/**
 * Insert a single document
 * @param document The document to insert
 */
void insertOne(TDocument document);

/**
 * Insert a single document with options
 * @param document The document to insert
 * @param options Insert options
 */
void insertOne(TDocument document, InsertOneOptions options);

/**
 * Insert a single document within a session
 * @param clientSession The client session
 * @param document The document to insert
 */
void insertOne(ClientSession clientSession, TDocument document);

/**
 * Insert multiple documents
 * @param documents List of documents to insert
 */
void insertMany(List<? extends TDocument> documents);

/**
 * Insert multiple documents with options
 * @param documents List of documents to insert
 * @param options Insert options including ordered/unordered
 */
void insertMany(List<? extends TDocument> documents, InsertManyOptions options);

/**
 * Insert multiple documents within a session
 * @param clientSession The client session
 * @param documents List of documents to insert
 */
void insertMany(ClientSession clientSession, List<? extends TDocument> documents);

MongoCollection<Document> collection = database.getCollection("users");

// Single document insert
Document user = new Document("name", "Alice")
    .append("age", 30)
    .append("email", "alice@example.com");
collection.insertOne(user);

// Multiple documents insert
List<Document> users = Arrays.asList(
    new Document("name", "Bob").append("age", 25),
    new Document("name", "Charlie").append("age", 35)
);
collection.insertMany(users);

// Insert with options
InsertManyOptions options = new InsertManyOptions().ordered(false);
collection.insertMany(users, options);

/**
 * Find all documents in the collection
 * @return FindIterable for chaining query operations
 */
FindIterable<TDocument> find();

/**
 * Find documents matching a filter
 * @param filter Query filter
 * @return FindIterable for chaining query operations
 */
FindIterable<TDocument> find(Bson filter);

/**
 * Find documents with result type transformation
 * @param filter Query filter
 * @param resultClass Target result class
 * @return FindIterable with transformed type
 */
<TResult> FindIterable<TResult> find(Bson filter, Class<TResult> resultClass);

/**
 * Find documents within a session
 * @param clientSession The client session
 * @param filter Query filter
 * @return FindIterable for chaining query operations
 */
FindIterable<TDocument> find(ClientSession clientSession, Bson filter);

/**
 * Fluent interface for find operations
 * @param <TResult> The result document type
 */
public interface FindIterable<TResult> extends MongoIterable<TResult> {
    // Query modification
    FindIterable<TResult> filter(Bson filter);
    FindIterable<TResult> limit(int limit);
    FindIterable<TResult> skip(int skip);
    FindIterable<TResult> maxTime(long maxTime, TimeUnit timeUnit);
    FindIterable<TResult> batchSize(int batchSize);
    
    // Result modification
    FindIterable<TResult> sort(Bson sort);
    FindIterable<TResult> projection(Bson projection);
    
    // Cursor configuration
    FindIterable<TResult> cursorType(CursorType cursorType);
    FindIterable<TResult> noCursorTimeout(boolean noCursorTimeout);
    
    // Execution
    TResult first();
    MongoCursor<TResult> iterator();
    MongoCursor<TResult> cursor();
}

MongoCollection<Document> collection = database.getCollection("users");

// Find all documents
for (Document doc : collection.find()) {
    System.out.println(doc.toJson());
}

// Find with filter
FindIterable<Document> iterable = collection.find(Filters.eq("status", "active"));

// Find with multiple conditions
FindIterable<Document> results = collection.find(
    Filters.and(
        Filters.gte("age", 18),
        Filters.lt("age", 65),
        Filters.eq("active", true)
    )
);

// Find with sorting and limiting
List<Document> users = collection.find()
    .sort(Sorts.descending("created"))
    .limit(10)
    .into(new ArrayList<>());

// Find first matching document
Document user = collection.find(Filters.eq("email", "alice@example.com")).first();

/**
 * Update a single document
 * @param filter Query filter to match documents
 * @param update Update specification
 * @return Update result with modification details
 */
UpdateResult updateOne(Bson filter, Bson update);

/**
 * Update a single document with options
 * @param filter Query filter to match documents
 * @param update Update specification
 * @param options Update options including upsert
 * @return Update result with modification details
 */
UpdateResult updateOne(Bson filter, Bson update, UpdateOptions options);

/**
 * Update multiple documents
 * @param filter Query filter to match documents
 * @param update Update specification
 * @return Update result with modification details
 */
UpdateResult updateMany(Bson filter, Bson update);

/**
 * Update multiple documents with options
 * @param filter Query filter to match documents
 * @param update Update specification  
 * @param options Update options
 * @return Update result with modification details
 */
UpdateResult updateMany(Bson filter, Bson update, UpdateOptions options);

/**
 * Replace a single document entirely
 * @param filter Query filter to match document
 * @param replacement Replacement document
 * @return Update result with modification details
 */
UpdateResult replaceOne(Bson filter, TDocument replacement);

/**
 * Replace a single document with options
 * @param filter Query filter to match document
 * @param replacement Replacement document
 * @param options Replace options including upsert
 * @return Update result with modification details
 */
UpdateResult replaceOne(Bson filter, TDocument replacement, ReplaceOptions options);

MongoCollection<Document> collection = database.getCollection("users");

// Update single document
UpdateResult result = collection.updateOne(
    Filters.eq("email", "alice@example.com"),
    Updates.set("lastLogin", new Date())
);

// Update multiple documents
collection.updateMany(
    Filters.lt("lastLogin", oldDate),
    Updates.set("status", "inactive")
);

// Update with multiple operations
collection.updateOne(
    Filters.eq("_id", userId),
    Updates.combine(
        Updates.set("name", "Alice Smith"),
        Updates.inc("loginCount", 1),
        Updates.currentDate("lastModified")
    )
);

// Upsert operation
UpdateOptions options = new UpdateOptions().upsert(true);
collection.updateOne(
    Filters.eq("email", "new@example.com"),
    Updates.set("name", "New User"),
    options
);

/**
 * Delete a single document
 * @param filter Query filter to match document
 * @return Delete result with count of deleted documents
 */
DeleteResult deleteOne(Bson filter);

/**
 * Delete a single document with options
 * @param filter Query filter to match document
 * @param options Delete options
 * @return Delete result with count of deleted documents
 */
DeleteResult deleteOne(Bson filter, DeleteOptions options);

/**
 * Delete multiple documents
 * @param filter Query filter to match documents
 * @return Delete result with count of deleted documents
 */
DeleteResult deleteMany(Bson filter);

/**
 * Delete multiple documents with options
 * @param filter Query filter to match documents
 * @param options Delete options
 * @return Delete result with count of deleted documents
 */
DeleteResult deleteMany(Bson filter, DeleteOptions options);

// Delete single document
DeleteResult result = collection.deleteOne(Filters.eq("_id", userId));

// Delete multiple documents
collection.deleteMany(Filters.eq("status", "inactive"));

// Delete with complex filter
collection.deleteMany(
    Filters.and(
        Filters.lt("lastLogin", cutoffDate),
        Filters.ne("role", "admin")
    )
);

/**
 * Count all documents in collection (deprecated, use countDocuments)
 * @return Document count
 */
@Deprecated
long count();

/**
 * Count documents matching filter (deprecated, use countDocuments)
 * @param filter Query filter
 * @return Document count
 */
@Deprecated  
long count(Bson filter);

/**
 * Count documents matching filter
 * @return Exact document count
 */
long countDocuments();

/**
 * Count documents matching filter
 * @param filter Query filter
 * @return Exact document count
 */
long countDocuments(Bson filter);

/**
 * Count documents with options
 * @param filter Query filter
 * @param options Count options including limit and skip
 * @return Exact document count
 */
long countDocuments(Bson filter, CountOptions options);

/**
 * Get estimated document count using collection metadata
 * @return Estimated document count (fast but approximate)
 */
long estimatedDocumentCount();

/**
 * Get estimated document count with options
 * @param options Estimation options
 * @return Estimated document count
 */
long estimatedDocumentCount(EstimatedDocumentCountOptions options);

/**
 * Find distinct values for a field
 * @param fieldName Field name to get distinct values for
 * @param resultClass Class of the field values
 * @return DistinctIterable for the distinct values
 */
<TResult> DistinctIterable<TResult> distinct(String fieldName, Class<TResult> resultClass);

/**
 * Find distinct values for a field with filter
 * @param fieldName Field name to get distinct values for  
 * @param filter Query filter
 * @param resultClass Class of the field values
 * @return DistinctIterable for the distinct values
 */
<TResult> DistinctIterable<TResult> distinct(String fieldName, Bson filter, Class<TResult> resultClass);

// Get distinct values
DistinctIterable<String> cities = collection.distinct("city", String.class);
for (String city : cities) {
    System.out.println(city);
}

// Get distinct values with filter
DistinctIterable<Integer> ages = collection.distinct("age", 
    Filters.eq("status", "active"), Integer.class);

/**
 * Result of insert operations
 */
public abstract class InsertOneResult {
    public abstract boolean wasAcknowledged();
    public abstract BsonValue getInsertedId();
}

/**
 * Result of update operations
 */
public abstract class UpdateResult {
    public abstract boolean wasAcknowledged();
    public abstract long getMatchedCount();
    public abstract long getModifiedCount();
    public abstract BsonValue getUpsertedId();
}

/**
 * Result of delete operations  
 */
public abstract class DeleteResult {
    public abstract boolean wasAcknowledged();
    public abstract long getDeletedCount();
}

/**
 * Options for insert operations
 */
public final class InsertOneOptions {
    public InsertOneOptions bypassDocumentValidation(Boolean bypassDocumentValidation);
    public Boolean getBypassDocumentValidation();
}

/**
 * Options for update operations
 */
public class UpdateOptions {
    public UpdateOptions upsert(boolean upsert);
    public UpdateOptions bypassDocumentValidation(Boolean bypassDocumentValidation);
    public boolean isUpsert();
    public Boolean getBypassDocumentValidation();
}