📚 Library Management Service

A Spring Boot 3 REST API for managing library operations. It enables librarians to manage publications (books and journals) and their cover images, while allowing members to borrow and return items. The system also provides advanced statistical endpoints for analyzing borrowing trends. The system demonstrates solid object-oriented design, modern Java 25 features, and an in-memory persistence layer — no external database required.

---

🧭 Project Overview

🎯 Purpose

The Library Management Service provides RESTful endpoints for managing loans, members, publications, and library analytics. It allows:

• Librarians to manage the publication catalog (Books and Journals), including creating, updating, deleting, and uploading cover images.
• Members to borrow one or multiple available items, return selected or all items, and view loan details.
• System Analysts to view statistical reports, such as top borrowed items, overdue lists, and rolling monthly activity trends.

⚙️ Main Features

• Publication Management: Full CRUD operations for books and journals with support for localized titles.
• Image Handling: Upload and serve cover images using NIO.2 with strict validation and path traversal protection.
• Loan Processing: Checkout items with concurrent availability checks and track due dates.
• Statistical Reporting: Dedicated endpoints for analytics, including top borrowers, yearly trends, and rolling averages using Gatherers.
• Concurrency: Parallel processing during checkout to verify item availability efficiently.
• Localization: Internationalization (i18n) support for error messages and publication titles.
• In-Memory Storage: Uses thread-safe maps for persistence, eliminating the need for an external database.
• Auto-initialized Data: Preloaded sample data for members, publications, and historical loans.

🏗️ Architecture Overview

This API follows a three-layer architecture:

Each layer has a clear responsibility:

• Controller: Handles HTTP requests and responses.
• Service: Contains business logic for borrowing and returning items.
• Repository: Manages in-memory storage using static maps.

---

🧩 UML Diagrams

🧱 Class Diagram

---

🔁 Sequence Diagram

Create Publication Flow

Borrow Flow

Return Flow

---

🌐 API Documentation

🔗 Swagger OpenAPI Documentation

The application provides interactive API documentation using SpringDoc OpenAPI 3.

📍 Access Points

• Swagger UI: http://localhost:8080/swagger-ui.html
• OpenAPI JSON: http://localhost:8080/api-docs
• OpenAPI YAML: http://localhost:8080/api-docs.yaml

⚙️ Configuration

The OpenAPI documentation is configured in application.yml:

springdoc:
  api-docs:
    path: /api-docs
    groups:
      enabled: true
  swagger-ui:
    path: /swagger-ui.html
    operationsSorter: method
    tagsSorter: alpha
    disable-swagger-default-url: true

📋 Features

• Interactive Testing: Execute API calls directly from the browser
• Schema Documentation: Complete request/response model documentation
• Error Responses: All possible HTTP status codes and error formats
• Parameter Documentation: Detailed parameter descriptions and examples

🚀 API Endpoints

📤 Loan

1️⃣ Checkout Items

POST /v1/members/{memberId}/loans

Create a new loan for a member by borrowing one or more available items.

Request Example

{
  "items": [1, 2]
}

Success Response

{
  "id": 1,
  "memberId": 1,
  "loanDate": "2025-10-25",
  "expectedReturnDate": "2025-11-08",
  "items": [
    { "id": 1, "title": "Clean Code", "type": "BOOK" },
    { "id": 2, "title": "Nature Neuroscience", "type": "JOURNAL" }
  ],
  "status": "OPEN"
}

Error Example

{
  "timestamp": "2025-10-25T15:30:00",
  "status": 409,
  "error": "Conflict",
  "message": "Item 'Clean Code' is currently loaned out",
  "path": "/v1/members/1/loans"
}

---

2️⃣ List Member Loans

GET /v1/members/{memberId}/loans

Retrieve a summary of all loans for a member.

Success Response

[
  {
    "loanId": 1,
    "loanDate": "2025-10-25",
    "expectedReturnDate": "2025-11-08",
    "status": "OPEN"
  }
]

---

3️⃣ Get Loan Details

GET /v1/loans/{loanId}

Fetch detailed information about a specific loan and its items.

Success Response

{
  "id": 1,
  "memberId": 1,
  "loanDate": "2025-10-25",
  "expectedReturnDate": "2025-11-08",
  "items": [
    { "id": 1, "title": "Clean Code", "type": "BOOK" }
  ],
  "status": "OPEN"
}

---

4️⃣ Return Items

POST /v1/loans/{loanId}/returns

Return one or more items, or all if no body is provided.

Request Example (specific items)

{
  "items": [1]
}

Response Example (loan closed)

{
  "id": 1,
  "memberId": 1,
  "loanDate": "2025-10-25",
  "expectedReturnDate": "2025-11-08",
  "items": [
    { "id": 1, "title": "Clean Code", "type": "BOOK", "returnedDate": "2025-10-30" }
  ],
  "status": "CLOSED"
}

---

📖 Publication

1️⃣ Create Publication

POST /v1/publications

Create a new book or journal entry.

Request Example (Book)

{
  "type": "BOOK",
  "title": "Domain-Driven Design",
  "author": "Eric Evans",
  "publicationDate": "2003-09-30",
  "category": "TECHNOLOGY",
  "isbn": "9780321125217",
  "genre": "Software Architecture",
  "pageCount": 560
}

Success Response (201 Created)

{
  "id": 100,
  "type": "BOOK",
  "title": "Domain-Driven Design",
  "author": "Eric Evans",
  "available": true,
  "isbn": "9780321125217",
  "genre": "Software Architecture",
  "pageCount": 560
}

---

2️⃣ List Publications

GET /v1/publications

Retrieve all publications. Supports optional filtering by category.

Query Parameters

• category (optional): Filter by category (e.g., TECHNOLOGY, SCIENCE).

Success Response

[
  {
    "id": 1,
    "type": "BOOK",
    "title": "Clean Code",
    "author": "Robert C. Martin",
    "available": true
  }
]

---

️3️⃣ Get Publication by ID

GET /v1/publications/{id}

Retrieve detailed information about a specific publication.

Success Response

{
  "id": 1,
  "type": "BOOK",
  "title": "Clean Code",
  "author": "Robert C. Martin",
  "publicationDate": "2008-08-01",
  "category": "TECHNOLOGY",
  "available": true,
  "isbn": "9780132350884",
  "genre": "Programming",
  "pageCount": 464
}

---

4️⃣️ Publication: Update Publication

PUT /v1/publications/{id}

Update an existing publication. The type in the request must match the stored type.

Request Example

{
  "type": "BOOK",
  "title": "Clean Code: A Handbook of Agile Software Craftsmanship",
  "author": "Robert C. Martin",
  "publicationDate": "2008-08-01",
  "category": "TECHNOLOGY",
  "isbn": "9780132350884",
  "genre": "Software Engineering",
  "pageCount": 464
}

---

5️⃣ Delete Publication

DELETE /v1/publications/{id}

Delete a publication. Returns 204 No Content. Fails with 409 Conflict if the item is currently on loan.

---

6️⃣ Upload Cover Image

POST /v1/publications/{id}/image

Upload or replace the cover image for a publication.

Request

• Content-Type: multipart/form-data
• Parameter: file (File)

Success Response

{
  "id": 1,
  "coverImageFileName": "cover_1_1714123200000.jpg",
  ...
}

---

7️⃣ Get Cover Image

GET /v1/publications/{id}/image

Retrieve the cover image file.

Response

• Content-Type: image/jpeg, image/png, or image/webp.
• Body: Raw image bytes.

---

📈 Statistics

1️⃣ Distinct Borrowers

GET /v1/statistics/members/borrowers

Returns a sorted list of all unique member names who have ever borrowed an item.

Success Response

[
  "Alice Johnson",
  "Bob Williams",
  "Charlie Davis"
]

---

2️⃣ Top Borrowed Items

GET /v1/statistics/items/top-borrowed

Returns the most frequently borrowed items across all time.

Query Parameters

• topN (optional): Number of results (default 10).

Success Response

[
  { "itemId": 1, "title": "Clean Code", "type": "BOOK", "loanCount": 15 }
]

3️⃣ Loan Count by Category

GET /v1/statistics/categories/loan-counts

Returns categories ranked by how many times their items were borrowed.

Success Response

[
  { "category": "TECHNOLOGY", "loanCount": 50 },
  { "category": "SCIENCE", "loanCount": 30 }
]

---

4️⃣ Top Borrowers by Year

GET /v1/statistics/members/top-borrowers/year/{year}

Returns members ranked by items borrowed in the given year, most active first.

Path Parameters

• year: The year to analyze (e.g., 2024).

Success Response

[
  {
    "memberId": 1,
    "firstName": "Alice",
    "lastName": "Johnson",
    "email": "alice@example.com",
    "totalLoans": 12,
    "totalItems": 25
  }
]

---

5️⃣ Items Borrowed by Year

GET /v1/statistics/items/borrowed/year/{year}

Returns a lightweight summary of items borrowed in a given year.

Success Response

[
  { "itemId": 1, "title": "Clean Code", "type": "BOOK", "loanCount": 8 }
]

---

6️⃣ Yearly Loan Trend

GET /v1/statistics/loans/yearly-trend

Returns total items loaned per calendar year across all history.

Success Response

[
  { "year": 2024, "loanCount": 120 },
  { "year": 2025, "loanCount": 85 }
]

---

7️⃣ Overdue Items

GET /v1/statistics/loans/overdue

Returns all unreturned items past their due date, sorted by days overdue descending.

Success Response

[
  {
    "loanId": 50,
    "memberId": 2,
    "memberName": "Bob Williams",
    "itemId": 5,
    "itemTitle": "Effective Java",
    "expectedReturnDate": "2025-11-01",
    "daysOverdue": 15
  }
]

---

8️⃣ Average Items Per Loan

GET /v1/statistics/loans/avg-items

Returns the all-time average number of items per loan transaction.

Success Response

2.5

---

9️⃣ Member Active Loans Check

GET /v1/statistics/members/{memberId}/has-active-loans

Returns true if the specified member currently has at least one open loan.

Success Response

true

---

1️⃣0️⃣ Rolling Monthly Activity

GET /v1/statistics/members/monthly-activity

Returns per-member monthly loan counts with a sliding-window rolling average.

Query Parameters

• windowSize (optional): Number of months for the rolling window (default 3).

Success Response

{
    "1": [
       { "year": 2025, "month": 10, "loanCount": 2, "rollingAvg": 2.0 },
       { "year": 2025, "month": 11, "loanCount": 4, "rollingAvg": 3.0 }
    ]
}  

---

📚 Generating Javadoc

The project includes comprehensive Javadoc documentation for all classes, methods, and records.

🛠️ Generate Documentation

# Generate Javadoc
mvn javadoc:javadoc

# View generated documentation
open target/site/apidocs/index.html

📖 Access Javadoc

After generation, open target/site/apidocs/index.html in your browser to view:

• Class Documentation: Detailed descriptions of all entities, services, and controllers
• Method Documentation: Complete parameter and return value documentation
• Record Documentation: DTO field descriptions and usage examples
• Exception Documentation: When and why each exception is thrown
• Inheritance Trees: Class hierarchy and implementation relationships

📋 Javadoc Features

• Complete Coverage: All public and protected methods documented
• Cross-References: @see tags linking related classes and methods
• Parameter Validation: Documentation of constraints and validation rules
• Exception Handling: Detailed @throws documentation
• Return Value Descriptions: Clear explanations of what each method returns

---

🧠 Object-Oriented Design Explanation

Principle	Description	Example
Encapsulation	Data hidden behind getters/setters	LibraryItem fields are private
Inheritance	Common behavior in base classes	Book and Journal extend LibraryItem
Polymorphism	Shared interface with different implementations	getType() returns "BOOK" or "JOURNAL"
Abstraction	Abstract parent defines contract	LibraryItem is an abstract sealed class
Interfaces	Business contracts	LoanService defines loan operations

---

☕ Fundamental Java Features

Feature	Example	Description
Sorting	.sorted(Comparator.comparingInt( LoanStreakStats::streak).reversed())	Sorting collections using Comparator references
Lambdas	Callable<LoanItem> task = () -> { ... }	Usage of functional interfaces (Callable, Function)
Streams (Intermediate)	.filter(...), .map(...), .flatMap(...), .distinct(), .limit(...)	Intermediate operations to transform or filter data streams
Streams (Terminal)	.collect(...), .anyMatch(...), .max(...), .forEach(...), findFirst(), count()	Terminal operations to produce results or side-effects
Collectors	Collectors.toMap(...), Collectors.groupingBy(...)	Mutable reduction operations for maps and grouping
Switch Expressions	Used for modern control flow	Simplified and expressive switch syntax
Sealed Classes	public sealed abstract class LibraryItem permits Book, Journal {}	Restricts subclassing for type safety
Records	public record LoanResponse(...) {}	Compact immutable data transfer obj ects
Date/Time API	plusDays(...), ChronoUnit.DAYS.between(...)	Modern date/time handling

---

🛠️ Advanced Java Features

Feature	Example	Description
Concurrency	ExecutorService executor = Executors.newFixedThreadPool(threads);	Managing concurrent tasks using thread pools and Callables
NIO.2	Files.createDirectories(...), Files.copy(...), Path.resolve(...)	Modern non-blocking I/O operations for robust file handling
Localization	ReloadableResourceBundleMessageSource, LocaleResolver	Internationalization (i18n) support via message bundles
Gatherers	.gather(Gatherer.ofSequential(...))	Custom intermediate operations for stateful stream processing

---

🚀 Java 25 Features Utilized

JEP	Feature	Example in Code
JEP 481	Scoped Values	CorrelationIdFilter uses ScopedValue for request context propagation
JEP 485	Stream Gatherers	StatisticsServiceImpl uses custom gatherers for rolling averages
JEP 513	Flexible Constructor Bodies	Book class constructor with validation before super()
JEP 512	Compact Source Files and Instance Main	Application class with simplified main() method

🔧 Code Examples

JEP 481: Scoped Values

// CorrelationIdFilter.java
ScopedValue.where(RequestContext.CORRELATION_ID, finalCorrelationId)
    .run(() -> LoggingContext.runWithLoggingContext(() -> { ... }));

JEP 513: Flexible Constructor Bodies

public class Book extends LibraryItem {
    public Book(String title, String author, LocalDate publicationDate, String isbn, String genre, int pageCount) {
        super(title, author, publicationDate);
        if (pageCount <= 0) {
            throw new IllegalArgumentException("Page count must be positive");
        }
        this.isbn = isbn;
        this.genre = genre;
        this.pageCount = pageCount;
    }
}

JEP 512: Compact Source Files and Instance Main

@SpringBootApplication
public class LibraryManagementApplication {
    public static void main(String[] args) {
        SpringApplication.run(LibraryManagementApplication.class, args);
    }
}

---

💾 In-Memory Data Management

This project replaces JPA/H2 with a thread-safe in-memory approach:

• Uses ConcurrentHashMap as storage for each repository.
• Uses AtomicLong to auto-generate IDs.
• Loads mock data via @PostConstruct in LibraryBootstrap:
  • 3 members: Alice, Bob, Charlie
  • Multiple publications: Books and Journals across various categories (Tech, Science, Fiction).
  • Historical Loans: Pre-seeded loans across multiple years (2024-2025) to support statistical analysis.

Example repository initialization:

@PostConstruct
void seed() {
  memberData.getMembers().forEach(memberRepository::save);
  itemData.getBooks().forEach(itemRepository::save);
  // ...
}

---

🚀 Running the Application

Prerequisites

• Java 25+
• Maven 3.9+

Run Command

mvn spring-boot:run

Default Endpoint

http://localhost:8080/v1

---

✅ Tests

This project includes both unit tests and integration tests using Karate DSL to ensure correctness and reliability of the Library Management Service.

---

🧪 Unit Tests

Unit tests validate the behavior of individual components such as services and repositories. They are written using JUnit 5 and cover core business logic like loan creation, item return, and exception handling.

▶️ Run Unit Tests

mvn test

This command will execute all unit tests located in the src/test/java directory. Results will be displayed in the console and stored in the target/surefire-reports folder.

---

🥋 Integration Tests with Karate DSL

Karate is a powerful DSL for testing REST APIs. It allows you to write expressive, scenario-based tests that validate the full request/response lifecycle.

📌 Goals of Karate Tests

• Verify end-to-end flows for borrowing and returning items.
• Ensure the API behaves correctly under different conditions.
• Simulate real-world usage with dynamic data and assertions.

🧾 Covered Scenarios

• Full Borrow and Return Flow Borrow items, save loan ID, return items, assert loan is closed and returnedDate is set.
• Partial Return Flow Borrow items 3 and 5, return item 3, then item 5 — validating intermediate loan states.

▶️ Run Karate Tests

mvn -Dtest=com.lms.library.karate.BorrowAndReturnBooksTest test

This command runs the Karate feature file located at classpath:karate/BorrowAndReturnBooks.feature.

📊 View Test Report

After execution, a detailed HTML report is generated at:

target/karate-reports/karate-summary.html

This report includes scenario results, request/response logs, and assertion outcomes.

🧾 License

This project is for educational and demonstration purposes — showing clean architecture, Java 25 features, and OOP principles in a Spring Boot REST API.