DOCSP-54965: Java backend scaffolding setup

[cbullinger]

Setup of Java Spring Boot backend for the MongoDB Sample MFlix application

This PR implements the initial setup of a Java Spring Boot backend for the MongoDB Sample MFlix application (parity with the current Express.js/TypeScript backend). The implementation demonstrates direct MongoDB Java Driver usage for educational purposes while following Spring Boot best practices.

---

What to Review

Database Configuration (config/)

• Connection pool settings appropriate for production
• Timeout values (10s) reasonable
• Error handling in DatabaseVerification robust
• Text index creation matches Express backend
• Logging messages helpful

Domain Models (model/)

• All fields match TypeScript interfaces
• Nested class structure clean and maintainable
• Lombok annotations used appropriately
• Field types correct (Integer vs int, Date vs Instant)

DTOs (model/dto/)

• Validation annotations appropriate
• Optional fields correctly marked
• DTOs match Express backend structures
• Field naming consistent

Response Models (model/response/)

• Generic type usage in SuccessResponse<T> correct
• @JsonInclude(NON_NULL) behavior desired
• Timestamp format matches Express backend
• Error response structure matches Express backend

Repository Layer (repository/)

• BSON Document conversion logic correct
• Null-safe handling throughout
• All nested object conversions working
• MongoDB operations using correct methods
• No data loss in conversion

Service Layer (service/)

• Query building logic correct (buildFilter, buildSort)
• Text search using $text operator properly
• Regex patterns for genre search correct
• Pagination logic with limit capping (max 100)
• Validation logic appropriate
• Exception handling comprehensive

Controller Layer (controller/)

• All endpoints match Express backend
• HTTP status codes correct (200, 201, 404, 400, 409, 500)
• Request parameter mapping correct
• Response wrapping consistent
• @Valid annotations on request bodies

Exception Handling (exception/)

• All exception types handled
• Error response format consistent
• HTTP status codes appropriate
• Logging comprehensive
• MongoDB-specific errors handled (duplicate key, write errors)

---

What's NOT in This PR

Testing (Future Work)

• Unit tests for service layer
• Integration tests for controller layer
• Repository layer tests
• Test coverage reporting

Advanced API Endpoints (Future Work)

• Aggregation
• FTS
• Vector Search
• Geospatial

Documentation (Partial)

• API documentation (Swagger/OpenAPI) - configuration exists but not fully documented
• README updates for Java backend

---

Build Verification

$ cd server/java-spring && ./mvnw clean package -DskipTests
[INFO] BUILD SUCCESS
[INFO] Compiling 22 source files
[INFO] Building jar: sample-mflix-spring-1.0.0.jar

---

API Endpoints

All endpoints are fully implemented and match the current Express backend:

Method	Endpoint	Description	Status
GET	/	API information	Implemented
GET	/api/movies	List movies with filtering, sorting, pagination	Implemented
GET	/api/movies/{id}	Get movie by ID	Implemented
POST	/api/movies	Create single movie	Implemented
POST	/api/movies/batch	Create multiple movies	Implemented
PUT	/api/movies/{id}	Update movie	Implemented
PATCH	/api/movies	Update multiple movies	Implemented
DELETE	/api/movies/{id}	Delete movie	Implemented
DELETE	/api/movies	Delete multiple movies	Implemented
DELETE	/api/movies/{id}/find-and-delete	Find and delete movie	Implemented

Query Parameters (GET /api/movies)

• q - Full-text search
• genre - Filter by genre (case-insensitive)
• year - Filter by year (exact match)
• minRating - Minimum IMDB rating
• maxRating - Maximum IMDB rating
• limit - Results per page (default: 20, max: 100)
• skip - Number of results to skip
• sortBy - Field to sort by (default: title)
• sortOrder - Sort order: asc or desc (default: asc)

---

Design Decisions

Why Lombok?

• Reduces boilerplate (getters, setters, constructors, toString, equals, hashCode)
• Improves readability
• Changes to fields automatically update generated methods
• Industry standard in Spring Boot projects

Why Custom Repository (Not Spring Data)?

• Demonstrates direct MongoDB Driver usage for educational purposes
• Matches Express backend approach (Node.js driver)
• Full control over BSON document structure and queries
• Shows explicit MongoDB operations
• Better for learning MongoDB concepts

Why Manual BSON Conversion?

• Educational value - shows how MongoDB stores data
• Full control over serialization/deserialization
• No hidden magic - explicit conversion logic
• Easier to debug and understand data flow

Why Nested Classes?

• Encapsulation (only used within parent context)
• Namespace clarity (Movie.Awards vs separate MovieAwards class)
• Matches MongoDB nested document structure
• Reduces file count and improves organization

---

Testing Recommendations

Manual Testing

1. Start the application: ./mvnw spring-boot:run
2. Test root endpoint: curl http://localhost:3001/
3. Test GET all movies: curl http://localhost:3001/api/movies?limit=5
4. Test GET by ID: curl http://localhost:3001/api/movies/{id}
5. Test POST create: curl -X POST http://localhost:3001/api/movies -H "Content-Type: application/json" -d '{"title":"Test Movie"}'
6. Test PUT update: curl -X PUT http://localhost:3001/api/movies/{id} -H "Content-Type: application/json" -d '{"year":2024}'
7. Test DELETE: curl -X DELETE http://localhost:3001/api/movies/{id}