# Interface BookstoreAPI

All Known Implementing Classes:
  `BookstoreArrayList`

public interface BookstoreAPI
Defines the contract for bookstore operations. This is from our previous lab, which we mainly worked with Books. As you can see, this interface is not extensible to other types of materials!

This interface provides an API for managing a book inventory, including CRUD operations, search functionality, and analytics.

Implementations should ensure thread-safety if concurrent access is expected.

Since:
  2024-09-15
Version:
  1.0
Author:
  Navid Mohaghegh

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `add(Book book)`
  Adds a book to the inventory.
  `List<Book>`
  `findByAuthor(String authorQuery)`
  Searches for books by author (case-insensitive, partial match).
  `Book`
  `findByIsbn(String isbn)`
  Finds a book by its ISBN.
  `List<Book>`
  `findByPriceRange(double minPrice, double maxPrice)`
  Finds all books within a price range (inclusive).
  `List<Book>`
  `findByTitle(String titleQuery)`
  Searches for books by title (case-insensitive, partial match).
  `List<Book>`
  `findByYear(int year)`
  Finds all books published in a specific year.
  `List<Book>`
  `getAllBooks()`
  Gets all books in the inventory.
  `Book`
  `getMostExpensive()`
  Finds the most expensive book in the inventory.
  `Book`
  `getMostRecent()`
  Finds the most recently published book.
  `double`
  `inventoryValue()`
  Calculates the total value of all books in inventory.
  `boolean`
  `removeByIsbn(String isbn)`
  Removes a book from the inventory by ISBN.
  `int`
  `size()`
  Gets the number of books in the inventory.
  `Book[]`
  `snapshotArray()`
  Creates a defensive copy of the inventory as an array.

- ## Method Details

  - ### add

    boolean add(Book book)
    Adds a book to the inventory. Duplicate ISBNs are not allowed.
    Parameters:
      `book` - the book to add (non-null)
    Returns:
      true if the book was added, false if ISBN already exists or book is null

  - ### removeByIsbn

    boolean removeByIsbn(String isbn)
    Removes a book from the inventory by ISBN.
    Parameters:
      `isbn` - the ISBN of the book to remove
    Returns:
      true if a book was removed, false if no book with that ISBN exists

  - ### findByIsbn

    Book findByIsbn(String isbn)
    Finds a book by its ISBN.
    Parameters:
      `isbn` - the ISBN to search for
    Returns:
      the book if found, null otherwise

  - ### findByTitle

    List<Book> findByTitle(String titleQuery)
    Searches for books by title (case-insensitive, partial match).
    Parameters:
      `titleQuery` - the title or partial title to search for
    Returns:
      list of matching books (never null, may be empty)

  - ### findByAuthor

    List<Book> findByAuthor(String authorQuery)
    Searches for books by author (case-insensitive, partial match).
    Parameters:
      `authorQuery` - the author name or partial name to search for
    Returns:
      list of matching books (never null, may be empty)

  - ### findByPriceRange

    List<Book> findByPriceRange(double minPrice, double maxPrice)
    Finds all books within a price range (inclusive).
    Parameters:
      `minPrice` - minimum price (inclusive)
      `maxPrice` - maximum price (inclusive)
    Returns:
      list of books within the price range
    Throws:
      `IllegalArgumentException` - if minPrice > maxPrice or prices are negative

  - ### findByYear

    List<Book> findByYear(int year)
    Finds all books published in a specific year.
    Parameters:
      `year` - the publication year
    Returns:
      list of books published in that year

  - ### size

    int size()
    Gets the number of books in the inventory.
    Returns:
      the total number of books

  - ### inventoryValue

    double inventoryValue()
    Calculates the total value of all books in inventory.
    Returns:
      sum of all book prices

  - ### getMostExpensive

    Book getMostExpensive()
    Finds the most expensive book in the inventory.
    Returns:
      the book with highest price, null if inventory is empty

  - ### getMostRecent

    Book getMostRecent()
    Finds the most recently published book.
    Returns:
      the book with the latest publication year, null if inventory is empty

  - ### snapshotArray

    Book[] snapshotArray()
    Creates a defensive copy of the inventory as an array. Changes to the returned array will not affect the inventory.
    Returns:
      array containing all books in the inventory

  - ### getAllBooks

    List<Book> getAllBooks()
    Gets all books in the inventory. The returned list is a defensive copy.
    Returns:
      list of all books (never null, may be empty)