LibraTrack (Java/Gradle)

Core library domain model for a simple library system: Books, Shelves, and Readers — with operations for inventory, checkout/returns, and listing. JUnit 5 tests codify expected behavior. Error handling is centralized in an enum (Utilities.Code) with explicit numeric codes and human-readable messages.

For sample I/O traces and additional information, visit the project page: https://www.rsiddiq.com/software-design.html

At a Glance

Project Name: LibraTrack
Modules: single-module Gradle project (root)
Gradle: wrapper 8.5 (gradle/wrapper/gradle-wrapper.properties)
Java Toolchain: not pinned in Gradle (use a modern JDK; 17+ recommended)
Testing: JUnit Jupiter 5.10.0 (useJUnitPlatform())
Entry Point: none (library / domain model); call APIs from your own main or tests
Key Package(s): default package; Utilities (for Code enum)
Example Data: badBooks0.csv, badBooks1.csv, badReader0.csv, badReader1.csv, badShelves0.csv, badShelves1.csv

Project Structure

LibraTrack/
├── gradle/
│   └── wrapper/
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── src/
│   ├── main/
│   │   └── java/
│   │       ├── Utilities/
│   │       │   └── Code.java
│   │       ├── Book.java
│   │       ├── Library.java
│   │       ├── Reader.java
│   │       └── Shelf.java
│   └── test/
│       └── java/
│           ├── BookTest.java
│           ├── LibraryTest.java
│           ├── ReaderTest.java
│           └── ShelfTest.java
├── .gitignore
├── badBooks0.csv
├── badBooks1.csv
├── badReader0.csv
├── badReader1.csv
├── badShelves0.csv
├── badShelves1.csv
├── build.gradle
├── gradlew
├── gradlew.bat
├── Library00.csv
├── Library01.csv
├── Library02.csv
├── README.md
└── settings.gradle

Build & Test

Gradle (wrapper)

./gradlew clean build
./gradlew test

The project does not configure a mainClass or the application plugin. To run a demo program, add your own Main class that uses the API (see Usage).

Features

Domain entities: Book, Reader, Shelf
Library orchestration: Library manages collections, shelves, and readers
Checkouts/Returns: move a Book between shelf and reader lists, enforce limits & existence
Listings: pretty printers for books on a shelf, all readers, all shelves
CSV-friendly: constants in Reader suggest a stable CSV layout for bulk initialization
Deterministic error model: Utilities.Code enum returns structured codes/messages

Code Map

`Book`

Represents a single title (ISBN, title, subject, page count, author, optional dueDate). Implements equality/hash on identity and provides a human-readable toString(). Key API: getISBN, getTitle, getAuthor, getSubject, getPageCount, getDueDate, set*, toString

`Reader`

Represents a patron with cardNumber, name, phone, and a list of checked-out Books. Includes index constants for CSV parsing: CARD_NUMBER_, NAME_, PHONE_, BOOK_COUNT_, BOOK_START_. Key API: addBook(Book), removeBook(Book), getBookCount(Book), getBooks(), getCardNumber(), getName(), getPhone(), set*, toString()

`Shelf`

Holds books for a single subject at a numbered shelfNumber. Maintains counts per Book and supports inventory operations. Key API: addBook(Book), removeBook(Book), getBookCount(Book), listBooks(), getSubject(), getShelfNumber(), set*

listBooks() format (example): 0 books on shelf: 1 : sci-fi
When one book is present: 1 book on shelf: 1 : sci-fi followed by <Book.toString()> 1 per line.

`Library`

Coordinates the whole system: initialization, lookups, list formatting, and state transitions. Notable methods: addBook, addShelf, addReader, removeReader, checkOutBook, returnBook, listBooks, listShelves, listReaders, getBookByISBN, getReaderByCard, getShelf, convertInt, convertDate, errorCode, init

`Utilities.Code`

Centralized error signaling with integer codes and messages. Useful for programmatic checks and UX surfaced errors.

Common Codes (subset)

Code	Value	Meaning
`SUCCESS`	`0`	Transaction was a success
`FILE_NOT_FOUND_ERROR`	`-1`	Could not the file
`LIBRARY_ERROR`	`-3`	problem with the library
`READER_COUNT_ERROR`	`-4`	Reader Count Error
`SHELF_COUNT_ERROR`	`-6`	Shelf count error
`PAGE_COUNT_ERROR`	`-8`	Page count error
`DATE_CONVERSION_ERROR`	`-101`	Date conversion Error
`BOOK_ALREADY_CHECKED_OUT_ERROR`	`-21`	Book already checked out error
`BOOK_LIMIT_REACHED_ERROR`	`-22`	Book limit reached
`BOOK_NOT_IN_INVENTORY_ERROR`	`-23`	book not in stacks or library
`READER_NOT_IN_LIBRARY_ERROR`	`-44`	Reader Does not exists in library
`READER_STILL_HAS_BOOKS_ERROR`	`-48`	Must return all books.

Full list in src/main/java/Utilities/Code.java.

Usage

Below is a minimal example showing how you might wire the library in a Main class:

// Main.java (example)
public class Main {{
    public static void main(String[] args) {{
        Library lib = new Library();
        lib.init(); // if available; else add shelves, readers, and books manually

        Shelf s = new Shelf();
        s.setShelfNumber(1);
        s.setSubject("sci-fi");
        lib.addShelf(s);

        Book dune = new Book();
        dune.setISBN("34-w-34");
        dune.setTitle("Dune");
        dune.setAuthor("Frank Herbert");
        dune.setSubject("sci-fi");
        dune.setPageCount(412);
        lib.addBook(dune);

        Reader r = new Reader(1001, "Ada Lovelace", "555-0100");
        lib.addReader(r);

        // Checkout + list
        lib.checkOutBook("34-w-34", 1001, Library.convertDate("2025-10-01"));
        System.out.println(lib.listReaders());
        System.out.println(s.listBooks());
    }}
}}

Compile & run (if you add Main.java and a matching main method):

./gradlew build
java -cp build/classes/java/main Main

Data Files (CSV)

Sample/validation CSVs are present at repo root:

Books (e.g., badBooks0.csv, badBooks1.csv) — malformed or edge-case rows for negative testing
Readers (e.g., badReader0.csv, badReader1.csv) — checks card/phone parsing and counts
Shelves (e.g., badShelves0.csv, badShelves1.csv) — checks number/subject alignment

Implied schemas (based on parsing constants & method usage):

Reader: cardNumber,name,phone,bookCount,(isbn1,dueDate1, isbn2,dueDate2, ...)
Book: isbn,title,subject,pageCount,author
Shelf: shelfNumber,subject[, ...]

Refer to Library.convertInt/convertDate and error codes for validation rules.

Testing

JUnit 5 tests under src/test/java:
- BookTest, ReaderTest, ShelfTest, LibraryTest
Run:

./gradlew test

r-siddiq/LibraTrack