# java-final-final

**Repository Path**: bpyhome/java-final-final

## Basic Information

- **Project Name**: java-final-final
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: 2023901701
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-09
- **Last Updated**: 2025-12-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Restaurant Reservation API 🍽️

**Course:** Java Programming (OOP) - Spring Boot  
**Instructor:** Prof. Baptiste Dupuis  
**Author:** Ben  
**Student ID:** 2023901701  
**Deadline:** Sunday 7 December 11:42 PM

---

## 📖 Project Description

A production-grade RESTful API for managing restaurant reservations built with **Spring Boot 3.4.0** and **Java 21**. This system enables restaurants to manage their tables and track bookings, while allowing customers to browse restaurants, check availability, and make reservations online.


## ✨ Features

### Core Functionality (Required)
- **Restaurant Management**: View restaurants and their details with table information
- **Customer Management**: Register customers with user authentication and view profiles
- **Reservation Management**: Create, view, update, and cancel reservations
- **Business Rules Enforcement**:
  - ✅ No double-booking (same table, overlapping time)
  - ✅ Capacity validation (guests ≤ table capacity)
  - ✅ Opening hours respected (configurable per restaurant)
  - ✅ No past reservations
  - ✅ Proper status transitions (PENDING → CONFIRMED → COMPLETED/CANCELLED)

### 🌟 Bonus Features Implemented

#### 1. JWT Authentication & Authorization ✅
- User registration and login with secure password hashing
- JWT token-based authentication
- Protected endpoints (only authenticated users can make reservations)
- Role-based access control (ADMIN vs USER)
- Security context management for authorization checks

#### 2. Unit Tests (JUnit 5 + Mockito) ✅
- Comprehensive service layer tests (12+ test cases)
- Mock-based testing with Mockito
- Success and error scenarios covered
- Business rule validation tests
- Security context testing

#### 3. Review System ✅
- Customers can leave reviews for restaurants
- Rating system (1-5 stars) with comments
- Only customers with completed reservations can review
- One review per reservation (prevents duplicate reviews)
- View reviews by restaurant or customer

#### 4. Swagger/OpenAPI Documentation ✅
- Interactive API documentation at `/swagger-ui.html`
- Complete endpoint descriptions and schemas
- Try-it-out functionality for testing APIs
- Auto-generated from code annotations
- Professional API documentation for developers

### Technical Features
- Clean architecture with Controller → Service → Repository layers
- DTO pattern (entities never exposed directly)
- Custom exception handling with proper HTTP status codes
- Bean Validation for input validation
- H2 in-memory database with sample data
- Centralized validation logic with `ReservationValidator`
- Security utilities for authentication checks

## How to Run

### Prerequisites
- Java 21
- Maven 3.9+

### Running the Application

```bash
# Navigate to project directory
cd reservation-api

# Run with Maven wrapper
./mvnw spring-boot:run

# Or with Maven
mvn spring-boot:run
```

The API will be available at: **http://localhost:8080**

### Accessing H2 Console

URL: **http://localhost:8080/h2-console**

- JDBC URL: `jdbc:h2:mem:restaurantdb`
- Username: `sa`
- Password: (leave blank)

### Accessing Swagger UI (API Documentation)

URL: **http://localhost:8080/swagger-ui.html**

- Interactive API documentation
- Try-it-out functionality for all endpoints
- Complete request/response schemas
- Authentication support for protected endpoints

## 🔌 API Endpoints

### Authentication

| Method | Endpoint          | Description              | Auth Required |
|--------|-------------------|--------------------------|---------------|
| POST   | `/api/auth/register` | Register new user     | No            |
| POST   | `/api/auth/login`    | Login and get JWT     | No            |

### Restaurants

| Method | Endpoint                | Description              | Auth Required |
|--------|-------------------------|--------------------------|---------------|
| GET    | `/api/restaurants`      | Get all restaurants      | No            |
| GET    | `/api/restaurants/{id}` | Get restaurant by ID     | No            |
| POST   | `/api/restaurants`      | Create new restaurant    | Yes (ADMIN)   |

### Customers

| Method | Endpoint              | Description          | Auth Required |
|--------|-----------------------|----------------------|---------------|
| POST   | `/api/customers`      | Register new customer| Yes           |
| GET    | `/api/customers/{id}` | Get customer by ID   | Yes (Owner/Admin) |

### Reservations

| Method | Endpoint                            | Description                  | Auth Required |
|--------|-------------------------------------|------------------------------|---------------|
| POST   | `/api/reservations`                 | Create new reservation       | Yes           |
| GET    | `/api/reservations/{id}`            | Get reservation by ID        | Yes (Owner/Admin) |
| PUT    | `/api/reservations/{id}`            | Update reservation           | Yes (Owner/Admin) |
| DELETE | `/api/reservations/{id}`            | Cancel reservation           | Yes (Owner/Admin) |
| PUT    | `/api/reservations/{id}/complete`   | Mark reservation as complete | Yes (Owner/Admin) |
| GET    | `/api/reservations/customer/{id}`   | Get customer's reservations  | Yes (Owner/Admin) |

### Reviews

| Method | Endpoint                          | Description                  | Auth Required |
|--------|-----------------------------------|------------------------------|---------------|
| POST   | `/api/reviews`                    | Create review for completed reservation | Yes           |
| GET    | `/api/reviews/{id}`               | Get review by ID             | No            |
| GET    | `/api/reviews/restaurant/{id}`    | Get all reviews for restaurant | No          |
| GET    | `/api/reviews/customer/{id}`      | Get customer's reviews       | Yes (Owner/Admin) |

## Sample Data

The application initializes with:
- 1 Restaurant: "The Golden Fork"
  - Address: 123 Main Street, Shanghai
  - Hours: 11:00 - 22:00
- 5 Tables with varying capacities (2, 4, 6, 8, 8 seats)
- 2 Sample Customers:
  - John Doe (john.doe@example.com)
  - Jane Smith (jane.smith@example.com)

## Design Decisions

### Entity Relationships
- **Restaurant** (1) → (N) **RestaurantTable**: One restaurant has many tables
- **RestaurantTable** (1) → (N) **Reservation**: One table can have many reservations
- **Customer** (1) → (N) **Reservation**: One customer can have many reservations

### Time Slot Management
- Reservations use a 2-hour duration window
- Conflict detection checks for overlapping time slots
- Only PENDING and CONFIRMED reservations block time slots

### Status Flow
```
PENDING → CONFIRMED → COMPLETED
    ↓
CANCELLED
```

### Exception Handling
- **404 Not Found**: Resource doesn't exist
- **400 Bad Request**: Validation errors, past reservations, capacity exceeded
- **409 Conflict**: Double-booking, duplicate email, invalid status transitions
- **500 Internal Server Error**: Unexpected errors

## 🧪 Testing

### Unit Tests (JUnit 5 + Mockito)
**You must run the tests in order, or the later tests will fail because they rely on data created by earlier tests.**

The project includes comprehensive unit tests for the service layer:

**Test Coverage:**
- `ReservationServiceTest.java` - 12 test cases covering:
  - ✅ Successful reservation creation
  - ✅ Business rule validations (double-booking, capacity, time restrictions)
  - ✅ Exception handling (ResourceNotFoundException, ValidationException, ConflictException)
  - ✅ Authorization checks (owner vs admin access)
  - ✅ Status transition validations
  - ✅ Edge cases and error scenarios

**Running Tests:**
```bash
# Run all tests
mvn test

# Run specific test class
mvn test -Dtest=ReservationServiceTest

# Run with coverage report
mvn clean test jacoco:report
```

**Test Results:**
```
Tests run: 15, Failures: 0, Errors: 0, Skipped: 0
- ReservationApiApplicationTests: 1 test (context loads)
- ReservationServiceTest: 12 tests (service layer)
- TimeSlotTest: 2 tests (time slot logic)
```

### API Tests (REST Client)

Use the provided test files with REST Client (VS Code extension):

**Test Files:**
- `api-tests.http` - Main API functionality tests
- `rbac-tests.http` - Role-based access control tests

**Test Coverage:**
- ✅ Happy path scenarios (successful operations)
- ✅ Error scenarios (validation failures, business rule violations)
- ✅ Edge cases (double-booking, capacity limits, time restrictions)
- ✅ Authentication and authorization flows
- ✅ RBAC (Role-Based Access Control) scenarios

**Test Categories:**
1. **Authentication Tests** - Registration, login, JWT validation
2. **Restaurant Tests** - CRUD operations, data validation
3. **Reservation Tests** - Create, update, cancel, complete
4. **Business Rule Tests** - Double-booking prevention, capacity checks, time validations
5. **Authorization Tests** - Owner access, admin privileges, access denial

## 📁 Project Structure

```
src/main/java/com/restaurant/reservationapi/
├── config/
│   ├── DataInitializer.java
│   ├── OpenAPIConfig.java
│   └── SecurityConfig.java
├── constants/
│   ├── ReservationConstants.java
│   └── SecurityConstants.java
├── controller/
│   ├── AuthController.java
│   ├── CustomerController.java
│   ├── ReservationController.java
│   ├── RestaurantController.java
│   └── ReviewController.java
├── dto/
│   ├── request/
│   │   ├── CreateCustomerRequest.java
│   │   ├── CreateReservationRequest.java
│   │   ├── CreateRestaurantRequest.java
│   │   ├── CreateReviewRequest.java
│   │   ├── CreateTableRequest.java
│   │   ├── LoginRequest.java
│   │   └── RegisterRequest.java
│   └── response/
│       ├── AuthResponse.java
│       ├── AvailabilityResponse.java
│       ├── CustomerResponse.java
│       ├── ReservationResponse.java
│       ├── RestaurantDetailResponse.java
│       ├── RestaurantResponse.java
│       ├── ReviewResponse.java
│       └── TableResponse.java
├── exception/
│   ├── BusinessException.java
│   ├── ConflictException.java
│   ├── ErrorResponse.java
│   ├── GlobalExceptionHandler.java
│   ├── ResourceNotFoundException.java
│   └── ValidationException.java
├── model/
│   ├── Customer.java
│   ├── Reservation.java
│   ├── ReservationStatus.java
│   ├── Restaurant.java
│   ├── RestaurantTable.java
│   ├── Review.java
│   ├── Role.java
│   └── User.java
├── repository/
│   ├── CustomerRepository.java
│   ├── ReservationRepository.java
│   ├── RestaurantRepository.java
│   ├── RestaurantTableRepository.java
│   ├── ReviewRepository.java
│   └── UserRepository.java
├── security/
│   ├── JwtAuthenticationFilter.java
│   ├── JwtTokenProvider.java
│   ├── SecurityUtils.java
│   └── UserDetailsServiceImpl.java
├── service/
│   ├── AuthService.java
│   ├── CustomerService.java
│   ├── ReservationService.java
│   ├── RestaurantService.java
│   └── ReviewService.java
├── validator/
│   └── ReservationValidator.java
└── ReservationApiApplication.java

src/test/java/com/restaurant/reservationapi/
├── service/
│   ├── ReservationServiceTest.java
│   └── TimeSlotTest.java
└── ReservationApiApplicationTests.java
```

## 🎨 Clean Code Principles Applied

### 1. Naming Conventions ✅
- **Classes**: PascalCase (`ReservationService`, `JwtTokenProvider`)
- **Methods/Variables**: camelCase (`findByRestaurantId`, `validateReservationTime`)
- **Constants**: UPPER_SNAKE_CASE (`RESERVATION_DURATION_HOURS`, `JWT_EXPIRATION`)
- **Packages**: lowercase (`com.restaurant.reservationapi.service`)

### 2. Method Length ✅
- **Most methods**: ≤ 20 lines (optimal)
- **Complex methods**: ≤ 25 lines (acceptable)
- **Maximum**: 35 lines (only for justified cases like complex validation)
- **Refactoring applied**: Long methods split into smaller, focused helper methods

### 3. Single Responsibility Principle ✅
- Each class has one clear purpose
- Controllers: HTTP handling only
- Services: Business logic only
- Repositories: Data access only
- Validators: Validation logic only

### 4. DRY Principle (Don't Repeat Yourself) ✅
- No code duplication
- Shared validation logic extracted to `ReservationValidator`
- Common security checks in `SecurityUtils`
- Reusable constants in `ReservationConstants`

### 5. Proper Encapsulation ✅
- All entity fields are private
- DTOs used for API communication (entities never exposed)
- Getters/setters only where needed
- Immutable DTOs where possible

### 6. Meaningful Names ✅
- Self-documenting code
- Examples:
  - `validateReservationTime()` not `validate()`
  - `checkForConflicts()` not `check()`
  - `findConflictingReservations()` not `find()`

### 7. No Magic Numbers ✅
- All constants defined:
  - `RESERVATION_DURATION_HOURS = 2`
  - `JWT_EXPIRATION = 86400000` (24 hours)
  - Opening/closing times stored in database

### 8. Separation of Concerns ✅
- Clear layer boundaries
- Business logic isolated from HTTP concerns
- Validation logic centralized
- Security logic separated

## 💡 Challenges & Solutions

### Challenge 1: Conflict Detection Algorithm
**Problem**: How to prevent double-booking of tables with overlapping time slots?  
**Solution**: Implemented interval overlap detection using custom JPQL query:
- Query checks if new reservation's time range overlaps with existing reservations
- Uses `DATEADD` function to calculate reservation end time (start + 2 hours)
- Only considers PENDING and CONFIRMED reservations (CANCELLED/COMPLETED don't block)
- Formula: `(newStart < existingEnd) AND (newEnd > existingStart)`

### Challenge 2: JWT Authentication Integration
**Problem**: How to secure endpoints while maintaining clean architecture?  
**Solution**: 
- Created `JwtAuthenticationFilter` to intercept requests and validate tokens
- Implemented `SecurityUtils` for centralized authorization checks
- Used Spring Security's `SecurityContextHolder` for authentication state
- Separated authentication logic from business logic

### Challenge 3: Validation Logic Duplication
**Problem**: Reservation validation logic was duplicated between create and update operations.  
**Solution**: 
- Extracted validation logic into dedicated `ReservationValidator` component
- Created reusable validation methods: `validateNewReservation()` and `validateReservationUpdate()`
- Reduced code duplication and improved maintainability
- Made validation logic testable in isolation

### Challenge 4: Time Zone and Midnight Crossing
**Problem**: Reservations spanning across midnight caused validation issues.  
**Solution**: 
- Added explicit midnight crossing check: `if (endTime.isBefore(startTime))`
- Enforced business rule: reservations must complete on the same day
- Used `LocalTime` for time-of-day comparisons
- Clear error messages for users

### Challenge 5: Authorization Granularity
**Problem**: Need different access levels (owner vs admin) for reservations.  
**Solution**: 
- Implemented `checkOwnershipOrAdmin()` helper method
- Admins can access all reservations
- Regular users can only access their own reservations
- Consistent authorization checks across all operations


---

## 📊 Project Compliance with Requirements

### Core Requirements (100% Complete)

#### ✅ Functional Requirements
- ✅ Restaurant Management (view all, view details, check availability)
- ✅ Reservation Management (create, view, update, cancel, complete)
- ✅ Customer Management (register, view profile)

#### ✅ Business Rules Enforcement
- ✅ No double-booking (interval overlap detection)
- ✅ Capacity check (guests ≤ table capacity)
- ✅ Opening hours validation (configurable per restaurant)
- ✅ No past reservations (time validation)
- ✅ Cancellation rules (status-based validation)

#### ✅ Technical Requirements
- ✅ Spring Boot 3.4.0 with Java 21
- ✅ Spring Data JPA for persistence
- ✅ H2 Database (in-memory)
- ✅ Spring Validation (Bean Validation)
- ✅ Proper exception handling (@RestControllerAdvice)
- ✅ Controller → Service → Repository layers
- ✅ DTO pattern (entities never exposed)
- ✅ Custom exceptions for business errors

#### ✅ Clean Code Requirements
- ✅ Naming conventions (PascalCase, camelCase, UPPER_SNAKE_CASE)
- ✅ Methods under 25 lines (most under 20)
- ✅ No magic numbers (constants used)
- ✅ No code duplication (DRY principle)
- ✅ Meaningful names (self-documenting)
- ✅ Single Responsibility Principle
- ✅ Proper encapsulation

#### ✅ API Design
- ✅ RESTful conventions
- ✅ Proper HTTP methods and status codes
- ✅ JSON request/response format
- ✅ Meaningful error messages
- ✅ Proper validation feedback

### Bonus Features (Implemented)

#### ✅ Unit Tests (JUnit 5)
- ✅ Service layer tests (12+ test cases)
- ✅ Mockito for mocking repositories
- ✅ Success and error cases covered
- ✅ Business rule validation tests

#### ✅ JWT Authentication
- ✅ User registration and login
- ✅ Protected endpoints
- ✅ Role-based access (ADMIN vs USER)
- ✅ Token-based authentication

#### ✅ Review System
- ✅ Reviews can be created for completed reservations
- ✅ Only completed reservations can be reviewed
- ✅ Rating system (1-5 stars) with comments
- ✅ One review per reservation validation
- ✅ View reviews by restaurant or customer

#### ✅ Swagger/OpenAPI Documentation
- ✅ Interactive API documentation
- ✅ Complete endpoint descriptions
- ✅ Interactive API documentation
- ✅ Complete endpoint descriptions
- ✅ Request/response schemas
- ✅ Try-it-out functionality

### Testing Coverage

#### ✅ API Tests (rbac-tests.http)
- ✅ Happy path scenarios
- ✅ Error scenarios
- ✅ Business rule violations
- ✅ Validation errors
- ✅ 48+ comprehensive test cases

---

## 📝 Development Process

### Git Workflow
- **Branch**: `2023901701` (student ID)
- **Commits**: 10+ meaningful commits with descriptive messages
- **Commit Language**: All in English
- **Development**: Incremental progress visible through commits

### Documentation
- ✅ Comprehensive README.md
- ✅ API endpoints documented
- ✅ Design decisions explained
- ✅ Challenges and solutions documented
- ✅ Clean code principles applied

---

## 🎓 Learning Outcomes

This project demonstrates proficiency in:

1. **Spring Boot Framework**: Configuration, dependency injection, auto-configuration
2. **Spring Data JPA**: Entity relationships, custom queries, repository pattern
3. **RESTful API Design**: HTTP methods, status codes, resource naming
4. **Security**: JWT authentication, authorization, password hashing
5. **Testing**: Unit testing, mocking, test-driven development
6. **Clean Code**: SOLID principles, naming conventions, code organization
7. **Problem Solving**: Complex business logic, validation, conflict detection
8. **Git**: Version control, branching, commit best practices

---

**Project Status**: ✅ Complete and ready for evaluation