From 9948c2185785ec0cdf5af0d06f0c966bdf4e52a1 Mon Sep 17 00:00:00 2001 From: TatuJLund Date: Sun, 30 Jun 2024 21:56:21 +0300 Subject: [PATCH] Add JavaDocs in Crud package --- .../tatu/vaadincreate/crud/BookForm.java | 10 +- .../tatu/vaadincreate/crud/BookGrid.java | 17 ++- .../vaadincreate/crud/BooksPresenter.java | 85 ++++++++++++++ .../tatu/vaadincreate/crud/BooksView.java | 104 +++++++++++++++++- .../tatu/vaadincreate/crud/FakeGrid.java | 6 +- 5 files changed, 217 insertions(+), 5 deletions(-) diff --git a/vaadincreate-ui/src/main/java/org/vaadin/tatu/vaadincreate/crud/BookForm.java b/vaadincreate-ui/src/main/java/org/vaadin/tatu/vaadincreate/crud/BookForm.java index e46d932..63854af 100644 --- a/vaadincreate-ui/src/main/java/org/vaadin/tatu/vaadincreate/crud/BookForm.java +++ b/vaadincreate-ui/src/main/java/org/vaadin/tatu/vaadincreate/crud/BookForm.java @@ -40,7 +40,6 @@ public class BookForm extends Composite implements HasI18N { // Localization constants private static final String AVAILABILITY_MISMATCH = "availability-mismatch"; - private static final String DISCARD_CHANGES = "discard-changes"; private static final String SAVE = "save"; private static final String CANCEL = "cancel"; private static final String CANNOT_CONVERT = "cannot-convert"; @@ -99,6 +98,15 @@ public Result convertToModel(String value, } + /** + * Represents a form for creating or editing a book. This form is used in + * the Vaadin Create application. It allows users to enter information about + * a book, such as its price, stock count, and category. The form includes + * validation for the entered data and provides buttons for saving, + * discarding, canceling, and deleting the book. The form is bound to a + * presenter, which handles the business logic for saving, editing, and + * deleting books. + */ public BookForm(BooksPresenter presenter) { setCompositionRoot(layout); buildForm(); diff --git a/vaadincreate-ui/src/main/java/org/vaadin/tatu/vaadincreate/crud/BookGrid.java b/vaadincreate-ui/src/main/java/org/vaadin/tatu/vaadincreate/crud/BookGrid.java index d686521..4b0dbcf 100644 --- a/vaadincreate-ui/src/main/java/org/vaadin/tatu/vaadincreate/crud/BookGrid.java +++ b/vaadincreate-ui/src/main/java/org/vaadin/tatu/vaadincreate/crud/BookGrid.java @@ -31,8 +31,7 @@ * data sets. */ @SuppressWarnings("serial") -public class BookGrid extends Grid - implements HasI18N { +public class BookGrid extends Grid implements HasI18N { private static final String CATEGORIES = "categories"; private static final String IN_STOCK = "in-stock"; @@ -50,6 +49,13 @@ public class BookGrid extends Grid private int edited; private DecimalFormat decimalFormat; + /** + * The BookGrid class represents a grid component that displays a list of + * books. It provides various columns to display different properties of the + * books, such as id, name, price, availability, stock count, and + * categories. The grid also supports highlighting the last edited row and + * showing a traffic light icon for availability. + */ public BookGrid() { setId("book-grid"); setSizeFull(); @@ -183,6 +189,13 @@ public void attach() { decimalFormat.setMinimumFractionDigits(2); } + /** + * Adjusts the visibility and width of columns in the book grid based on the + * specified width. + * + * @param width + * the width of the grid + */ private void adjustColumns(int width) { setDescriptionGenerator(book -> { var user = lockedBooks.isLocked(Product.class, book.getId()); diff --git a/vaadincreate-ui/src/main/java/org/vaadin/tatu/vaadincreate/crud/BooksPresenter.java b/vaadincreate-ui/src/main/java/org/vaadin/tatu/vaadincreate/crud/BooksPresenter.java index c6cdaa2..f338bd4 100644 --- a/vaadincreate-ui/src/main/java/org/vaadin/tatu/vaadincreate/crud/BooksPresenter.java +++ b/vaadincreate-ui/src/main/java/org/vaadin/tatu/vaadincreate/crud/BooksPresenter.java @@ -54,6 +54,9 @@ private CompletableFuture> loadCategoriesAsync() { executor); } + /** + * Requests an update of the products and updates the view asynchronously. + */ public void requestUpdateProducts() { future = loadProductsAsync().thenAccept(products -> { logger.info("Fetching products complete"); @@ -62,6 +65,11 @@ public void requestUpdateProducts() { }); } + /** + * Cancels the update of products and unlocks the book. If there is a future + * task running, it will be cancelled and the future reference will be set + * to null. + */ public void cancelUpdateProducts() { unlockBook(); if (future != null) { @@ -71,6 +79,15 @@ public void cancelUpdateProducts() { } } + /** + * Initializes the BooksPresenter. + * + * This method is responsible for initializing the presenter and setting up + * the initial state of the view. It calls the editProduct method with a + * null parameter to ensure that the view is in an editable state. If the + * current user is not an admin, it disables the ability to create new + * products. + */ public void init() { editProduct(null); // Hide and disable if not admin @@ -79,11 +96,21 @@ public void init() { } } + /** + * Cancels the current product operation. This method calls the + * `cancelProduct` method of the view and unlocks the book. + */ public void cancelProduct() { view.cancelProduct(); unlockBook(); } + /** + * Unlocks the currently editing book. If there is a book currently being + * edited, it will be unlocked by calling the `unlock` method of the + * `lockedBooks` object. After unlocking the book, the `editing` variable is + * set to null. + */ public void unlockBook() { if (editing != null) { lockedBooks.unlock(Product.class, editing); @@ -91,6 +118,13 @@ public void unlockBook() { } } + /** + * Locks a book with the specified ID for editing. If there is already a + * book being edited, it will be unlocked first. + * + * @param id + * the ID of the book to lock for editing + */ private void lockBook(Integer id) { if (editing != null) { unlockBook(); @@ -99,6 +133,16 @@ private void lockBook(Integer id) { editing = id; } + /** + * Handles the navigation to the view with the specified product ID. If the + * product ID is "new", it creates a new product. Otherwise, it attempts to + * find the product with the given ID and selects it in the view. If the + * product ID is not valid or cannot be parsed as an integer, an error + * message is shown in the view. + * + * @param productId + * the ID of the product to navigate to + */ public void enter(String productId) { if (productId != null && !productId.isEmpty()) { if (productId.equals("new")) { @@ -121,11 +165,24 @@ public void enter(String productId) { } } + /** + * Finds a product by its ID. + * + * @param productId + * the ID of the product to find + * @return the product with the specified ID, or null if not found + */ public Product findProduct(int productId) { logger.info("Fetching product {}", productId); return service.getProductById(productId); } + /** + * Saves the given product. + * + * @param product + * The product to be saved. + */ public void saveProduct(Product product) { view.showSaveNotification(product.getProductName()); view.clearSelection(); @@ -141,6 +198,12 @@ public void saveProduct(Product product) { view.setFragmentParameter(""); } + /** + * Deletes a product from the system. + * + * @param product + * the product to be deleted + */ public void deleteProduct(Product product) { view.showDeleteNotification(product.getProductName()); view.clearSelection(); @@ -151,6 +214,15 @@ public void deleteProduct(Product product) { view.setFragmentParameter(""); } + /** + * Edits the specified product. If the product is null, it sets the fragment + * parameter to an empty string and unlocks the book. If the product's ID is + * -1, it sets the fragment parameter to "new". Otherwise, it sets the + * fragment parameter to the product's ID and locks the book. + * + * @param product + * the product to be edited + */ public void editProduct(Product product) { if (product == null) { view.setFragmentParameter(""); @@ -166,6 +238,11 @@ public void editProduct(Product product) { view.editProduct(product); } + /** + * Creates a new product. This method clears the selection, sets the + * fragment parameter to "new", logs an info message, and edits a new + * product in the view. + */ public void newProduct() { view.clearSelection(); view.setFragmentParameter("new"); @@ -173,6 +250,14 @@ public void newProduct() { view.editProduct(new Product()); } + /** + * Handles the event when a row is selected in the UI. If the user has the + * role of ADMIN and the selected product is not locked, the product is + * edited. Otherwise, the selection is cleared. + * + * @param product + * the selected product + */ public void rowSelected(Product product) { if (accessControl.isUserInRole(Role.ADMIN)) { if (product != null && lockedBooks.isLocked(Product.class, diff --git a/vaadincreate-ui/src/main/java/org/vaadin/tatu/vaadincreate/crud/BooksView.java b/vaadincreate-ui/src/main/java/org/vaadin/tatu/vaadincreate/crud/BooksView.java index cc0efe4..54192c4 100644 --- a/vaadincreate-ui/src/main/java/org/vaadin/tatu/vaadincreate/crud/BooksView.java +++ b/vaadincreate-ui/src/main/java/org/vaadin/tatu/vaadincreate/crud/BooksView.java @@ -121,6 +121,16 @@ private boolean filterCondition(Object object, String filterText) { .contains(filterText.toLowerCase()); } + /** + * Checks if a given book passes the filter based on the filter text. + * + * @param book + * The book to be checked. + * @param filterText + * The filter text to be applied. + * @return {@code true} if the book passes the filter, {@code false} + * otherwise. + */ private boolean passesFilter(Product book, String filterText) { filterText = filterText.trim(); return filterCondition(book.getProductName(), filterText) @@ -128,6 +138,14 @@ private boolean passesFilter(Product book, String filterText) { || filterCondition(book.getCategory(), filterText); } + /** + * Creates a horizontal layout for the top bar of the BooksView. The top bar + * contains a filter TextField and a newProduct Button. The filter TextField + * is used to filter the data in the grid. The newProduct Button is used to + * create a new product. + * + * @return the created HorizontalLayout for the top bar + */ private HorizontalLayout createTopBar() { filter = new TextField(); filter.setId("filter-field"); @@ -166,6 +184,13 @@ public void enter(ViewChangeEvent event) { form.setCategories(ProductDataService.get().getAllCategories()); } + /** + * Cancels the product editing and discards any changes made. If there are + * unsaved changes, a confirmation dialog is displayed. If the changes are + * confirmed, the form is hidden, the selection is cleared, and the fragment + * parameter is set to an empty string. If there are no unsaved changes, the + * form is hidden and the selection is cleared. + */ public void cancelProduct() { if (form.hasChanges()) { var dialog = createDiscardChangesConfirmDialog(); @@ -205,40 +230,93 @@ public void setProductsAsync(Collection products) { } } + /** + * Displays an error message using a Vaadin notification. + * + * @param msg + * the error message to be displayed + */ public void showError(String msg) { Notification.show(msg, Type.ERROR_MESSAGE); } + /** + * Displays an error message indicating that the provided product ID is not + * valid. + * + * @param productId + * the invalid product ID + */ public void showNotValidId(String productId) { showError(getTranslation(NOT_VALID_PID, productId)); } + /** + * Shows a notification indicating that a book has been saved. + * + * @param book + * the name of the saved book + */ public void showSaveNotification(String book) { Notification.show(getTranslation(UPDATED, book), Type.TRAY_NOTIFICATION); } + /** + * Shows a notification indicating that a book has been deleted. + * + * @param book + * the name of the book that has been deleted + */ public void showDeleteNotification(String book) { Notification.show(getTranslation(REMOVED, book), Type.TRAY_NOTIFICATION); } + /** + * Sets the enabled state of the "New Product" button. + * + * @param enabled + * true to enable the button, false to disable it + */ public void setNewProductEnabled(boolean enabled) { newProduct.setEnabled(enabled); } + /** + * Clears the selection in the grid. + */ public void clearSelection() { grid.getSelectionModel().deselectAll(); } + /** + * Selects the specified row in the grid. + * + * @param row + * the row to be selected + */ public void selectRow(Product row) { grid.getSelectionModel().select(row); } + /** + * Returns the selected row from the grid as a {@link Product} object. + * + * @return the selected row as a {@link Product} object, or null if no row + * is selected + */ public Product getSelectedRow() { return grid.getSelectedRow(); } + /** + * Updates the specified product in the grid and refreshes the data + * provider. After updating the product, the form is hidden. + * + * @param product + * the product to be updated + */ public void updateProduct(Product product) { logger.info("Refresh item"); grid.setEdited(product); @@ -246,6 +324,12 @@ public void updateProduct(Product product) { form.showForm(false); } + /** + * Updates the grid with a new product and performs necessary UI actions. + * + * @param product + * the product to be added to the grid + */ public void updateGrid(Product product) { logger.info("Refresh grid"); dataProvider.getItems().add(product); @@ -254,14 +338,27 @@ public void updateGrid(Product product) { grid.scrollToEnd(); } + /** + * Removes a product from the data provider and refreshes the view. + * + * @param product + * the product to be removed + */ public void removeProduct(Product product) { dataProvider.getItems().remove(product); dataProvider.refreshAll(); } + /** + * Edits the specified product. + * + * @param product + * the product to be edited + */ public void editProduct(Product product) { grid.setEdited(null); if (product != null) { + // Ensure the product is up-to-date if (product.getId() > 0) { product = refreshProduct(dataProvider, product); } @@ -321,6 +418,11 @@ public void beforeLeave(ViewBeforeLeaveEvent event) { } } + /** + * Creates a confirmation dialog for displaying unsaved changes. + * + * @return The created ConfirmDialog instance. + */ private ConfirmDialog createDiscardChangesConfirmDialog() { var dialog = new ConfirmDialog(getTranslation(UNSAVED_CHANGES), ConfirmDialog.Type.ALERT); @@ -351,7 +453,7 @@ private Product refreshProduct(ListDataProvider dataProvider, var list = ((List) dataProvider.getItems()); var updatedProduct = presenter.findProduct(product.getId()); list.set(list.indexOf(product), updatedProduct); - logger.info("Refreshed {}", product.getId()); + logger.debug("Refreshed {}", product.getId()); dataProvider.refreshItem(updatedProduct); return updatedProduct; } diff --git a/vaadincreate-ui/src/main/java/org/vaadin/tatu/vaadincreate/crud/FakeGrid.java b/vaadincreate-ui/src/main/java/org/vaadin/tatu/vaadincreate/crud/FakeGrid.java index bc38229..9eecfc6 100644 --- a/vaadincreate-ui/src/main/java/org/vaadin/tatu/vaadincreate/crud/FakeGrid.java +++ b/vaadincreate-ui/src/main/java/org/vaadin/tatu/vaadincreate/crud/FakeGrid.java @@ -14,6 +14,10 @@ public class FakeGrid extends Composite { private static final String FAKEGRID_SPINNERWRAPPER = "fakegrid-spinnerwrapper"; private static final String FAKEGRID = "fakegrid"; + /** + * This class represents a fake grid component. It is used to display a + * loading spinner while the actual grid data is being fetched. + */ public FakeGrid() { VerticalLayout layout = new VerticalLayout(); setCompositionRoot(layout); @@ -35,6 +39,6 @@ public FakeGrid() { spinnerWrapper.addComponent(spinner); spinnerWrapper.setComponentAlignment(spinner, Alignment.MIDDLE_CENTER); layout.addComponents(fakeHeader, spinnerWrapper); - layout. setExpandRatio(spinnerWrapper, 1); + layout.setExpandRatio(spinnerWrapper, 1); } }