The Library Management System is a comprehensive application that allows users to manage a library's book inventory, handle user checkouts, and generate reports. This README provides all necessary information to install, set up, and use the application.
- Only users with the Admin role can manage (Create, Read, Update, Delete) books in the library. This includes:
- Adding new books to the inventory.
- Updating book details.
- Deleting books from the inventory.
- Admins can also perform all other functions available to regular users, such as checking out books and generating reports.
- Regular users can perform the following actions:
- View the list of books available in the library.
- Checkout books from the library.
- Return books they have checked out.
- Generate reports on book inventory and checkouts.
- When updating the number of copies of a book, the new number of copies cannot be less than the number of copies currently checked out and awaiting return. This ensures that the inventory accurately reflects the books available and prevents over-checkout.
- Users can check out a book more than once.
- Users can only check out books if the total number of checked out books does not exceed the available copies in the inventory.
- The checkout process and the return process are atomic to ensure that a book is not checked out if it is not available.
- User Authentication (Login and Logout)
- Book Management (CRUD Operations)
- User Checkouts and Returns
- Reporting (Books, Pending Returns, Returned Books)
- Java 22
- Spring Boot 3.2.5
- Spring Security
- Spring Data JPA
- Hibernate
- H2 Database (for testing)
- PostgreSQL (for production)
- ModelMapper 2.4.4
- JUnit 5
- Mockito
- Jackson
- JSON Web Tokens (JWT)
- JavaMailSender
- Lombok
- JavaFaker
- Maven 3.9.6 or later
-
Clone the repository:
git https://github.com/ibukunoreofe/library-management-java-spring-boot.git cd library-management-java-spring-boot -
Build the project:
mvn clean install -
Set up the database:
Ensure you have a running PostgreSQL database. Create a database named
library_management.Update the
application.propertiesfile with your database configuration:spring.datasource.url=jdbc:postgresql://localhost:5432/library_management spring.datasource.username=your_db_username spring.datasource.password=your_db_password # JPA and Hibernate configuration spring.jpa.hibernate.ddl-auto=update spring.jpa.show-sql=true # Admin user configuration admin.email=admin@example.com admin.password=password # Mail server configuration spring.mail.host=smtp.mailtrap.io spring.mail.port=587 spring.mail.username=your_mailtrap_username spring.mail.password=your_mailtrap_password spring.mail.properties.mail.smtp.auth=true spring.mail.properties.mail.smtp.starttls.enable=true -
Run the application:
mvn spring-boot:run -
Access the application:
The application will be available at
http://localhost:8080. -
Optionally set JVM
SET JVM HOME to the path installed
$ export JAVA_HOME="~\.jdks\openjdk-22.0.1"
-
Generate JWT Token https://dev.to/tkirwa/generate-a-random-jwt-secret-key-39j4
$ node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
To run the tests for this application, use the following Maven command:
mvn test
The following are the main test classes and their purposes:
-
CreateAndEnsureAdminLoginTest:
Ensures that an admin user is created and can log in successfully. Stores the admin token for use in other tests.
-
BookControllerTest:
Tests all CRUD operations for the
/api/booksendpoints, including pagination and search functionality. -
CheckoutControllerTest:
Tests the checkout and return functionality for the
/api/checkoutsendpoints. -
ReportControllerTest:
Tests the report generation endpoints for checked-out and returned books in the
/api/reports/booksendpoints. -
PasswordResetControllerTest:
Tests the password reset functionality for the
/api/auth/password/reset-requestand/api/auth/password/resetendpoints. -
LogoutControllerTest:
Tests the logout functionality for the
/api/auth/logoutendpoint.
To run a specific test class, use the following Maven command:
mvn -Dtest=ClassNameTest test
For example, to run the BookControllerTest:
mvn -Dtest=BookControllerTest test
Ensure that the required environment variables or system properties are set for the tests to run successfully. The tests may require access to a running database or other services, depending on the application configuration.
The application provides a set of RESTful endpoints for managing the library system. Below is a list of the available endpoints:
-
Login:
POST /api/auth/loginParameters:
{ "email": "admin@example.com", "password": "password" }Response:
{ "token": "your_jwt_token" } -
Register:
POST /api/auth/registerParameters:
{ "name": "User Name", "email": "user@example.com", "password": "password" }Response:
{ "message": "User registered successfully" } -
Request Password Reset:
POST /api/auth/password/reset-requestParameters:
{ "email": "user@example.com" }Response:
{ "message": "Password reset code sent to your email." } -
Reset Password:
POST /api/auth/password/resetParameters:
{ "email": "user@example.com", "password": "newpassword", "password_confirmation": "newpassword", "token": "reset_token" }Response:
{ "message": "Your password has been reset." } -
Logout:
POST /api/auth/logoutParameters:
Response:
{ "message": "User 'username' has been logged out successfully." }
-
Get All Books:
GET /api/booksParameters:
-
paginate(boolean, optional): If true, returns paginated results. -
page(integer, optional): Page number for pagination. -
size(integer, optional): Page size for pagination. -
search(string, optional): Search query for book titles or authors.
Response:
```
[
{
"id": 1,
"title": "Book Title",
"author": "Author Name",
"isbn": "1234567890",
"publishedAt": "2023-01-01",
"copies": 10
},
...
]
```
-
Get Book by ID:
GET /api/books/{id}Response:
{ "id": 1, "title": "Book Title", "author": "Author Name", "isbn": "1234567890", "publishedAt": "2023-01-01", "copies": 10 } -
Create Book:
POST /api/booksRequest Body:
{ "title": "New Book", "author": "Author Name", "isbn": "1234567890", "publishedAt": "2023-01-01", "copies": 10 }Response:
{ "id": 1, "title": "New Book", "author": "Author Name", "isbn": "1234567890", "publishedAt": "2023-01-01", "copies": 10 } -
Update Book:
PUT /api/books/{id}Request Body:
{ "title": "Updated Book", "author": "Author Name", "isbn": "1234567890", "publishedAt": "2023-01-01", "copies": 10 }Response:
{ "id": 1, "title": "Updated Book", "author": "Author Name", "isbn": "1234567890", "publishedAt": "2023-01-01", "copies": 10 } -
Delete Book:
DELETE /api/books/{id}Response:
{ "message": "Book deleted successfully." }
-
Checkout Book:
POST /api/checkoutsRequest Body:
{ "bookId": 1 }Response:
{ "checkoutId": 1, "userId": 1, "bookId": 1, "checkoutPersonName": "Admin User", "checkoutPersonEmailAddress": "admin@example.com", "bookTitle": "Book Title", "bookAuthor": "Author Name", "bookIsbn": "1234567890", "checkoutDateTimeUtc": "2023-01-01T00:00:00Z", "returnDateTimeUtc": null, "createdAt": "2023-01-01T00:00:00Z", "updatedAt": "2023-01-01T00:00:00Z" } -
Return Book:
PATCH /api/checkouts/{checkoutId}Response:
{ "checkoutId": 1, "userId": 1, "bookId": 1, "checkoutPersonName": "Admin User", "checkoutPersonEmailAddress": "admin@example.com", "bookTitle": "Book Title", "bookAuthor": "Author Name", "bookIsbn": "1234567890", "checkoutDateTimeUtc": "2023-01-01T00:00:00Z", "returnDateTimeUtc": "2023-01-02T00:00:00Z", "createdAt": "2023-01-01T00:00:00Z", "updatedAt": "2023-01-02T00:00:00Z" }
-
Get All Books Report:
GET /api/reports/booksParameters:
paginate(boolean, optional) - If true, returns paginated results.page(integer, optional) - Page number for pagination.size(integer, optional) - Number of items per page for pagination.search(string, optional) - Search query for filtering results.
Response:
{ "books": [ { "id": 1, "title": "Book Title", "author": "Author Name", "isbn": "1234567890", "publishedAt": "2023-01-01", "copies": 10, "checkedOutCount": 2, "quantityLeft": 8, "timesCheckedOutAndReturned": 1 } ], "totalPages": 1, "totalItems": 1 } -
Get Books Pending Return:
GET /api/reports/books/pending-returnParameters:
paginate(boolean, optional) - If true, returns paginated results.page(integer, optional) - Page number for pagination.size(integer, optional) - Number of items per page for pagination.search(string, optional) - Search query for filtering results.
Response:
{ "books": [ { "id": 1, "title": "Book Title", "author": "Author Name", "isbn": "1234567890", "publishedAt": "2023-01-01", "copies": 10, "checkedOutCount": 2, "quantityLeft": 8, "timesCheckedOutAndReturned": 1 } ], "totalPages": 1, "totalItems": 1 } -
Get Returned Books:
GET /api/reports/books/returnedParameters:
paginate(boolean, optional) - If true, returns paginated results.page(integer, optional) - Page number for pagination.size(integer, optional) - Number of items per page for pagination.search(string, optional) - Search query for filtering results.
Response:
{ "books": [ { "id": 1, "title": "Book Title", "author": "Author Name", "isbn": "1234567890", "publishedAt": "2023-01-01", "copies": 10, "checkedOutCount": 2, "quantityLeft": 8, "timesCheckedOutAndReturned": 1 } ], "totalPages": 1, "totalItems": 1 }
This project is licensed under the MIT License. You are free to use, modify, and distribute this software, provided that you include the original license and give credit to the original author.
This project was created and is maintained by Ibukun Bello.