Spring Vacancy

Spring Vacancy is a comprehensive Java Spring Boot application for vacancy and candidate management with ranking capabilities. Built with Maven and containerized with Docker for easy deployment.

Features

• 🏢 Vacancy Management - Complete CRUD operations for job vacancies
• 👤 Candidate Management - Full candidate lifecycle management
• 🏆 Ranking System - Smart candidate ranking based on configurable criteria
• 📊 Criteria Scoring - Age, salary, and gender-based scoring algorithm
• 🐳 Docker Support - Containerized application with MongoDB
• 🔍 Search & Filter - Advanced search and filtering capabilities
• 📡 REST API - Comprehensive RESTful endpoints with consistent response format

Tech Stack

• Backend: Java 24, Spring Boot 3.5.5
• Database: MongoDB 7.0 with authentication
• Build Tool: Maven 3.9+
• Containerization: Docker & Docker Compose
• API Documentation: Built-in endpoint discovery

Getting Started

Prerequisites

• Java 24 or later
• Maven 3.9+
• Docker & Docker Compose (for containerized deployment)

Running the Application

Option 1: Using run.cmd (Recommended for Windows)

# Simply run the batch script
run.cmd

Note: We use run.cmd instead of mvn spring-boot:run due to ClassNotFoundException issues with the direct Maven command. The script builds a JAR and runs it directly, which resolves dependency conflicts.

Option 2: Manual JAR Execution

# Build the project
mvn clean package -DskipTests

# Run the JAR directly
java -jar target/vacancy-0.0.1-SNAPSHOT.jar

Option 3: Docker (Recommended for Production)

# Build and start all services (app + MongoDB + Mongo Express)
docker compose up --build

# Or run in background
docker compose up --build -d

# Stop services
docker compose down

Docker includes:

• Spring Boot application on http://localhost:8080
• MongoDB database with authentication
• Mongo Express UI on http://localhost:8081 (admin/password)

Application URLs

• API Base: http://localhost:8080/api
• Health Check: http://localhost:8080/api/health
• API Documentation: http://localhost:8080/api/info
• Mongo Express (Docker only): http://localhost:8081

API Endpoints

Health & Info

• GET /api/health - Application health status
• GET /api/info - Complete API documentation

Vacancy Management

• GET /api/vacancy - List all vacancies
• POST /api/vacancy - Create new vacancy
• GET /api/vacancy/{id} - Get vacancy by ID
• PUT /api/vacancy/{id} - Update vacancy
• DELETE /api/vacancy/{id} - Delete vacancy
• GET /api/vacancy/code/{code} - Get by code
• GET /api/vacancy/search/* - Various search options

Candidate Management

• GET /api/candidate - List all candidates
• POST /api/candidate - Create new candidate
• GET /api/candidate/{id} - Get candidate by ID
• PUT /api/candidate/{id} - Update candidate
• DELETE /api/candidate/{id} - Delete candidate
• GET /api/candidate/email/{email} - Get by email

Ranking System

• GET /api/ranking/{code} - Get ranked candidates for vacancy
• GET /api/ranking/{code}/summary - Get ranking statistics

Project Structure

Project Structure

spring-vacancy/
├── src/main/java/com/spring_vacancy/app/
│   ├── controller/          # REST Controllers
│   │   ├── VacancyController.java
│   │   ├── CandidateController.java
│   │   ├── RankingController.java
│   │   └── HealthController.java
│   ├── model/              # Data Models
│   │   ├── Vacancy.java
│   │   ├── Candidate.java
│   │   ├── Criteria.java
│   │   └── ApiResponse.java
│   ├── repository/         # MongoDB Repositories
│   ├── service/           # Business Logic
│   └── SpringVacancyApplication.java
├── docker-compose.yml     # Docker services configuration
├── Dockerfile            # Application container
├── run.cmd              # Windows batch script for easy running
└── pom.xml              # Maven dependencies

Development Notes

Why run.cmd instead of mvn spring-boot:run?

The direct Maven command mvn spring-boot:run causes ClassNotFoundException issues in this project. The run.cmd script solves this by:

1. Building a complete JAR with all dependencies
2. Running the JAR directly with java -jar
3. Providing better error handling and debugging output

Docker Benefits

• Consistent Environment: Same setup across development/production
• Database Included: Pre-configured MongoDB with authentication
• Easy Management: Single command to start/stop everything
• No Local Setup: No need to install Java/Maven locally

Testing with Postman

📦 Ready-to-Import Collection

We provide a comprehensive Postman collection for easy API testing:

📁 Collection Location: postman/Spring Vacancy API.postman_collection.json

✨ Collection Features:

• 29 API Endpoints - Complete coverage of all controllers
• Sample Data - Pre-filled request bodies with realistic data
• Environment Variables - Configured for localhost:8080
• Organized Folders - Grouped by functionality (Health, Vacancy, Candidate, Ranking)
• Response Tests - Built-in validation scripts
• Easy Import - Postman v2.1 format

🚀 How to Import:

1. Open Postman
2. Click Import (top left corner)
3. Upload Files → Select postman/Spring Vacancy API.postman_collection.json
4. Import → Collection appears in your workspace
5. Start Testing! 🎉

📊 What's Included:

Category	Endpoints	Description
🏥 Health Check	2	Application status and API documentation
🏢 Vacancy Management	15	Full CRUD + search & filter operations
👤 Candidate Management	10	Complete candidate lifecycle
🏆 Ranking System	2	Smart candidate scoring and statistics

🔧 Pre-configured Variables:

• baseUrl: http://localhost:8080
• Sample IDs, names, and test data
• Realistic request examples

💡 Tip: Make sure your application is running before testing the endpoints!

License

This project is licensed under the MIT License.

Maven Commands Reference

# Compile the project
mvn compile

# Clean and compile
mvn clean compile

# Package into JAR
mvn package

# Run tests
mvn test

# Install to local repository
mvn install

# Note: mvn spring-boot:run has ClassNotFoundException issues
# Use run.cmd or java -jar target/vacancy-0.0.1-SNAPSHOT.jar instead