Coding

MongOCOM Copilot Instructions

MongOCOM (Mongo Object-COllection Mapper) is a lightweight Java Object-Document Mapping (ODM) library for MongoDB. It provides an annotation-based approach to map Java objects to MongoDB documents, similar to how JPA/Hibernate works for relational databases.

promptBeginner5 min to valuemarkdown

0 views

Jan 22, 2026

Sign in to like and favorite skills

View Original Source

Share:

Related Skills

PromptBeginner5 minmarkdown

Nano Banana Pro

Agent skill for nano-banana-pro

PromptBeginner5 minmarkdown

Markdown Converter

Agent skill for markdown-converter

PromptBeginner5 minmarkdown

1password

Agent skill for 1password

MongOCOM Copilot Instructions

Project Overview

MongOCOM (Mongo Object-COllection Mapper) is a lightweight Java Object-Document Mapping (ODM) library for MongoDB. It provides an annotation-based approach to map Java objects to MongoDB documents, similar to how JPA/Hibernate works for relational databases.

Key Features

Annotation-based mapping (
```
@Document
```
,
```
@ObjectId
```
,
```
@Internal
```
,
```
@Reference
```
)
Basic CRUD operations through
```
CollectionManager
```
Support for embedded documents and document relationships
Multiple configuration approaches (properties file, programmatic, web application)
Comprehensive quality assurance pipeline

Development Environment Setup

Prerequisites

Java 17 (target version for development)
Maven 3.x for build management
MongoDB server (2.x or 3.x) for testing
IDE with Java support (IntelliJ IDEA, Eclipse, VS Code)

Getting Started

# Clone the repository
git clone https://github.com/devops-thiago/MongOCOM.git
cd MongOCOM

# Build the project
mvn clean compile

# Run tests
mvn test

# Run all quality checks
./check-quality.sh

Architecture & Core Components

CollectionManager

The main entry point for database operations:

```
CollectionManagerFactory
```
- Factory for creating CollectionManager instances
```
CollectionManager
```
- Handles CRUD operations and object mapping
Thread-safe and implements
```
Closeable
```

Annotations

```
@Document(collection="name")
```
- Marks a class as a MongoDB document
```
@ObjectId
```
- Marks a field as the MongoDB
```
_id
```
field
```
@Internal
```
- Marks embedded objects that should be stored within parent document
```
@Reference
```
- Marks relationships to separate documents
```
@Index
```
- Defines indexes on fields (for optimization)

Configuration Options

Properties file:
```
database.properties
```
in classpath
Programmatic: Direct instantiation with connection parameters
Web application: Configuration files in
```
WEB-INF/conf/
```

Code Style Guidelines

Java Coding Standards

Follow Google Java Format style (enforced by Spotless)
Use descriptive variable and method names
Always provide default constructors for document classes
Implement proper error handling and logging
Close
```
CollectionManager
```
instances to free resources

Quality Metrics

Code Coverage: Target 80%+ (measured by JaCoCo)
Static Analysis: Pass SpotBugs, PMD, and Checkstyle checks
Code Formatting: Enforced by Spotless plugin

Running Quality Checks

# Check code formatting
mvn spotless:check

# Fix formatting issues
mvn spotless:apply

# Run static analysis
mvn checkstyle:check pmd:check spotbugs:check

# Generate coverage report
mvn test jacoco:report

Testing Guidelines

Test Structure

Unit tests in
```
src/test/java
```
Use JUnit for testing framework
Mock MongoDB interactions where appropriate
Test annotation processing and object mapping

Test Best Practices

Test both positive and negative scenarios
Verify proper handling of null values
Test edge cases in annotation processing
Ensure proper resource cleanup in tests

Common Development Tasks

Adding New Annotations

Create annotation in
```
com.arquivolivre.mongocom.annotation
```
package
Add processing logic in
```
CollectionManager
```
Add tests for the new annotation
Update documentation and examples

Adding New CRUD Operations

Add method to
```
CollectionManager
```
class
Follow existing patterns for MongoDB interaction
Add proper error handling and logging
Write comprehensive tests
Update API documentation

Working with Document Mapping

@Document(collection = "users")
public class User {
    @ObjectId
    private String id;
    
    private String name;
    private String email;
    
    @Internal
    private Address address;  // Embedded document
    
    @Reference
    private List<Order> orders;  // Referenced documents
    
    // Default constructor required
    public User() {}
    
    // Getters and setters...
}

Configuration Examples

// Properties file approach
CollectionManager cm = CollectionManagerFactory.setup();

// Programmatic approach
CollectionManager cm = CollectionManagerFactory
    .createCollectionManager("localhost", 27017, "myapp");

// With authentication
CollectionManager cm = CollectionManagerFactory
    .createCollectionManager("localhost", 27017, "myapp", "user", "pass");

Build and Deployment

Maven Phases

```
mvn compile
```
- Compile source code
```
mvn test
```
- Run unit tests with coverage
```
mvn package
```
- Create JAR file
```
mvn verify
```
- Run all quality checks
```
mvn clean
```
- Clean build artifacts

CI/CD Pipeline

Automated Testing: All tests run on PR and push
Code Coverage: JaCoCo reports uploaded to CodeCov
Quality Gates: SonarCloud analysis
Artifact Generation: JAR files uploaded as build artifacts

Release Process

Update version in
```
pom.xml
```
Run full quality check:
```
./check-quality.sh
```
Create release tag
Deploy to Sonatype repository

Dependencies Management

Core Dependencies

```
mongo-java-driver
```
- MongoDB Java driver
```
javax.javaee-web-api
```
- Java EE web API for servlet support
```
junit
```
- Testing framework

Plugin Configuration

Compiler Plugin: Set to Java 17 compatibility
JaCoCo: Code coverage reporting
Spotless: Code formatting
SpotBugs: Static analysis for bug detection
PMD: Code quality analysis
Checkstyle: Code style enforcement

Troubleshooting

Common Issues

Build Failures: Check Java version compatibility
Test Failures: Ensure MongoDB is running for integration tests
Formatting Issues: Run
```
mvn spotless:apply
```
to fix
Coverage Issues: Add tests for uncovered code paths

Debug Tips

Use logging to trace object mapping issues
Check MongoDB connection configuration
Verify annotation placement and parameters
Review stack traces for reflection-related errors

Contributing Guidelines

Before Submitting PRs

Run all quality checks:
```
./check-quality.sh
```
Ensure tests pass and coverage meets targets
Follow established code style and patterns
Update documentation for new features
Add appropriate tests for changes

Code Review Focus Areas

Proper resource management (closing connections)
Error handling and edge cases
Thread safety considerations
Performance implications
Backward compatibility

Migration Notes (Java 17)

This project is prepared for migration to Java 17:

Maven compiler plugin configured for Java 17
CI workflows updated to use JDK 17
All dependencies verified for Java 17 compatibility
Modern Java features can be adopted incrementally

When migrating:

Update source code to use modern Java features as appropriate
Test thoroughly with Java 17 runtime
Update documentation examples
Consider performance optimizations available in newer Java versions