Skip to content

Commit

Permalink
Improve Javadoc Comments
Browse files Browse the repository at this point in the history
  • Loading branch information
Harshmhajn committed Oct 1, 2024
1 parent c3e3433 commit 3f69ee9
Show file tree
Hide file tree
Showing 10 changed files with 343 additions and 174 deletions.
67 changes: 51 additions & 16 deletions src/main/java/com/libraryman_api/book/BookController.java
Original file line number Diff line number Diff line change
Expand Up @@ -9,46 +9,73 @@

/**
* REST controller for managing books in the LibraryMan application.
* This controller provides endpoints for performing CRUD operations on books,
* including retrieving all books, getting a book by its ID, adding a new book,
* updating an existing book, and deleting a book.
*
* <p>This controller provides a set of endpoints for performing CRUD operations
* on books. The operations include retrieving a list of all books, fetching
* a book by its ID, adding a new book, updating an existing book, and deleting
* a book.</p>
*
* <p>All endpoints are accessible under the base URL path <code>/api/books</code>.</p>
*
* <p>Note: The {@link ResourceNotFoundException} is thrown when an invalid book ID is
* provided for retrieval, update, or deletion.</p>
*
* <p>Usage examples for each endpoint can be found in the API documentation.</p>
*/
@RestController
@RequestMapping("/api/books")
public class BookController {

private final BookService bookService;

/**
* Constructs a new {@code BookController} with the specified {@code BookService}.
*
* @param bookService the service used to manage book operations
*/
@Autowired
private BookService bookService;
public BookController(BookService bookService) {
this.bookService = bookService;
}

/**
* Retrieves a list of all books in the library.
*
* @return a list of {@link Book} objects representing all the books in the library.
* <p>This endpoint handles GET requests to <code>/api/books</code> and
* returns a list of all books currently available in the library.</p>
*
* @return a list of {@link Book} objects representing all books in the library
*/
@GetMapping
public List<Book> getAllBooks() {
return bookService.getAllBooks();
}

/**
* Retrieves a book by its ID.
* Retrieves a specific book by its ID.
*
* <p>This endpoint handles GET requests to <code>/api/books/{id}</code>
* and returns the details of the book with the specified ID.</p>
*
* @param id the ID of the book to retrieve.
* @return a {@link ResponseEntity} containing the {@link Book} object, if found.
* @throws ResourceNotFoundException if the book with the specified ID is not found.
* @param id the ID of the book to retrieve
* @return a {@link ResponseEntity} containing the {@link Book} object if found
* @throws ResourceNotFoundException if the book with the specified ID is not found
*/
@GetMapping("/{id}")
public ResponseEntity<Book> getBookById(@PathVariable int id) {
return bookService.getBookById(id)
.map(ResponseEntity::ok)
.orElseThrow(() -> new ResourceNotFoundException("Book not found"));
.orElseThrow(() -> new ResourceNotFoundException("Book with ID " + id + " not found"));
}

/**
* Adds a new book to the library.
*
* @param book the {@link Book} object representing the new book to add.
* @return the added {@link Book} object.
* <p>This endpoint handles POST requests to <code>/api/books</code>
* to add a new book to the library.</p>
*
* @param book the {@link Book} object representing the new book to add
* @return the added {@link Book} object
*/
@PostMapping
public Book addBook(@RequestBody Book book) {
Expand All @@ -58,9 +85,13 @@ public Book addBook(@RequestBody Book book) {
/**
* Updates an existing book in the library.
*
* @param id the ID of the book to update.
* @param bookDetails the {@link Book} object containing the updated book details.
* @return the updated {@link Book} object.
* <p>This endpoint handles PUT requests to <code>/api/books/{id}</code>
* to update the details of an existing book in the library.</p>
*
* @param id the ID of the book to update
* @param bookDetails the updated {@link Book} details
* @return the updated {@link Book} object
* @throws ResourceNotFoundException if the book with the specified ID is not found
*/
@PutMapping("/{id}")
public Book updateBook(@PathVariable int id, @RequestBody Book bookDetails) {
Expand All @@ -70,7 +101,11 @@ public Book updateBook(@PathVariable int id, @RequestBody Book bookDetails) {
/**
* Deletes a book from the library by its ID.
*
* @param id the ID of the book to delete.
* <p>This endpoint handles DELETE requests to <code>/api/books/{id}</code>
* to remove a book from the library.</p>
*
* @param id the ID of the book to delete
* @throws ResourceNotFoundException if the book with the specified ID is not found
*/
@DeleteMapping("/{id}")
public void deleteBook(@PathVariable int id) {
Expand Down
81 changes: 51 additions & 30 deletions src/main/java/com/libraryman_api/book/BookService.java
Original file line number Diff line number Diff line change
Expand Up @@ -7,94 +7,115 @@
import java.util.Optional;

/**
* Service class for managing books in the LibraryMan system.
* Service class responsible for managing book-related operations in the LibraryMan system.
*
* <p>This service provides methods to perform CRUD operations on books, including
* retrieving all books, retrieving a book by its ID, adding a new book, updating
* an existing book, and deleting a book by its ID.</p>
* <p>This service handles various CRUD operations, such as retrieving all books, fetching
* a book by its ID, adding a new book, updating book details, and deleting a book from the system.</p>
*
* <p>Each method in this service interacts with the {@link BookRepository} to
* perform database operations.</p>
*
* <p>In the case of an invalid book ID being provided, the service throws a
* <p>All interactions with the database are facilitated via the {@link BookRepository}.
* If a book with a given ID is not found, the service throws a
* {@link ResourceNotFoundException}.</p>
*
* @author Ajay Negi
*
* <p>Usage examples and further documentation on the book management process
* can be found in the associated API documentation.</p>
*
* @see BookRepository
* @see ResourceNotFoundException
* @author
*/
@Service
public class BookService {

private final BookRepository bookRepository;

/**
* Constructs a new {@code BookService} with the specified {@code BookRepository}.
* Constructs a new {@code BookService} instance, injecting the required
* {@link BookRepository} to facilitate database operations.
*
* @param bookRepository the repository to be used by this service to interact with the database
* @param bookRepository the repository used to access and modify book data in the database
*/
public BookService(BookRepository bookRepository) {
this.bookRepository = bookRepository;
}

/**
* Retrieves all books from the database.
* Retrieves all books stored in the library.
*
* <p>This method interacts with the database to fetch a complete list of
* all {@link Book} entities available in the library's collection.</p>
*
* @return a list of all books
* @return a {@link List} of all books in the system
*/
public List<Book> getAllBooks() {
return bookRepository.findAll();
}

/**
* Retrieves a book by its ID.
* Fetches a specific book by its ID.
*
* @param bookId the ID of the book to retrieve
* @return an {@code Optional} containing the found book, or {@code Optional.empty()} if no book was found
* <p>If the book with the specified ID exists, it is returned as an
* {@link Optional}. If the book is not found, {@code Optional.empty()} is returned.</p>
*
* @param bookId the unique identifier of the book to be retrieved
* @return an {@link Optional} containing the book if found, or {@code Optional.empty()} if not
*/
public Optional<Book> getBookById(int bookId) {
return bookRepository.findById(bookId);
}

/**
* Adds a new book to the database.
* Adds a new book to the library.
*
* <p>This method saves the provided {@link Book} entity to the database.
* The book entity must contain the necessary details such as title, author,
* and publication details.</p>
*
* @param book the book to be added
* @return the saved book
* @param book the {@link Book} object to be added to the library
* @return the saved {@link Book} entity with any auto-generated fields populated (e.g., ID)
*/
public Book addBook(Book book) {
return bookRepository.save(book);
}

/**
* Updates an existing book with the given details.
* Updates an existing book's details.
*
* @param bookId the ID of the book to update
* @param bookDetails the new details for the book
* @return the updated book
* @throws ResourceNotFoundException if the book with the specified ID is not found
* <p>When called, this method updates the properties of an existing book
* using the new data passed in {@code bookDetails}. If the book with the
* specified ID does not exist, a {@link ResourceNotFoundException} is thrown.</p>
*
* @param bookId the unique identifier of the book to update
* @param bookDetails the new details to be applied to the book
* @return the updated {@link Book} object after saving the changes
* @throws ResourceNotFoundException if the book with the specified ID does not exist
*/
public Book updateBook(int bookId, Book bookDetails) {
Book book = bookRepository.findById(bookId)
.orElseThrow(() -> new ResourceNotFoundException("Book not found"));
.orElseThrow(() -> new ResourceNotFoundException("Book with ID " + bookId + " not found"));

book.setTitle(bookDetails.getTitle());
book.setAuthor(bookDetails.getAuthor());
book.setIsbn(bookDetails.getIsbn());
book.setPublisher(bookDetails.getPublisher());
book.setPublishedYear(bookDetails.getPublishedYear());
book.setGenre(bookDetails.getGenre());
book.setCopiesAvailable(bookDetails.getCopiesAvailable());

return bookRepository.save(book);
}

/**
* Deletes a book by its ID.
* Deletes a book from the library by its ID.
*
* @param bookId the ID of the book to delete
* <p>If the book with the specified ID exists, it is removed from the system.
* If not, a {@link ResourceNotFoundException} is thrown.</p>
*
* @param bookId the unique identifier of the book to delete
* @throws ResourceNotFoundException if the book with the specified ID is not found
*/
public void deleteBook(int bookId) {
Book book = bookRepository.findById(bookId)
.orElseThrow(() -> new ResourceNotFoundException("Book not found"));
.orElseThrow(() -> new ResourceNotFoundException("Book with ID " + bookId + " not found"));
bookRepository.delete(book);
}

}
39 changes: 30 additions & 9 deletions src/main/java/com/libraryman_api/email/EmailSender.java
Original file line number Diff line number Diff line change
Expand Up @@ -3,20 +3,41 @@
import com.libraryman_api.notification.Notifications;

/**
* Interface representing an email sending service for the Library Management System.
* Classes implementing this interface are responsible for sending emails
* and updating the status of notifications in the system.
* Interface representing an email sending service for the LibraryMan system.
*
* <p>This interface defines the contract for sending emails asynchronously to recipients.
* Implementing classes are responsible for constructing and sending the email, as well as
* updating the status of notifications (represented by {@link Notifications}) within the system.</p>
*
* <p>The email sending process involves constructing an email with a subject, body, and recipient
* details, and ensuring that the notification entity is updated based on whether the email
* was successfully sent or encountered an error.</p>
*
* <p>Classes implementing this interface typically use a mailing service such as
* {@link org.springframework.mail.javamail.JavaMailSender} to perform the actual email delivery.</p>
*
* @see Notifications
*/
public interface EmailSender {

/**
* Sends an email to the specified recipient with the given body, subject, and notification details.
*
* Sends an email asynchronously to the specified recipient with the provided content and subject.
*
* <p>This method is responsible for constructing the email message, sending it to the recipient,
* and updating the corresponding notification status within the system based on the outcome.
* The email body can be in HTML or plain text format, and the associated {@link Notifications} entity
* tracks the status of the email (e.g., SENT or FAILED).</p>
*
* <p>In case of errors during the sending process, the implementation of this method should handle
* the exceptions and log any failures accordingly. The notification status should be updated to reflect
* the success or failure of the email operation.</p>
*
* @param to the email address of the recipient
* @param body the body of the email, typically in HTML or plain text format
* @param subject the subject of the email
* @param notification the notification entity associated with the email being sent,
* used to track the status of the notification
* @param body the content of the email, either in HTML or plain text format
* @param subject the subject line of the email
* @param notification the notification entity representing the email notification in the system,
* used to track the status (SENT or FAILED) of the email being sent
* @throws IllegalStateException if there is an issue sending the email
*/
void send(String to, String body, String subject, Notifications notification);
}
Loading

0 comments on commit 3f69ee9

Please sign in to comment.