From c43756e943342cccefcb0696407b7c0d718633ed Mon Sep 17 00:00:00 2001 From: Mario Serrano Date: Mon, 25 May 2026 10:40:22 -0500 Subject: [PATCH] Enhance JavaDoc comments across multiple interfaces for improved clarity and documentation --- .../repositories/BookRepository.java | 10 ++++- .../modules/dashboard/UserInfoProvider.java | 37 +++++++++++++++++++ .../entityfile/EntityFileAccountProvider.java | 17 +++++---- .../modules/entityfile/EntityFileStorage.java | 37 +++++++++++++++++++ .../modules/importer/ImportBeanParser.java | 11 ++++++ .../modules/importer/ImportReader.java | 10 +++++ .../reports/core/ReportDataExporter.java | 12 ++++++ .../security/IgnoringSecurityMatcher.java | 10 ++++- .../security/LoginControllerInterceptor.java | 12 ++++++ .../java/tools/dynamia/commons/Lambdas.java | 24 ++++++++++++ .../dynamia/crud/CrudDataSetViewBuilder.java | 21 ++++++++++- .../tools/dynamia/crud/CrudRemoteAction.java | 5 +++ .../zk/viewers/form/FormViewModel.java | 14 ++++++- 13 files changed, 207 insertions(+), 13 deletions(-) diff --git a/examples/demo-zk-books/src/main/java/mybookstore/repositories/BookRepository.java b/examples/demo-zk-books/src/main/java/mybookstore/repositories/BookRepository.java index eac9e833..c58f377b 100644 --- a/examples/demo-zk-books/src/main/java/mybookstore/repositories/BookRepository.java +++ b/examples/demo-zk-books/src/main/java/mybookstore/repositories/BookRepository.java @@ -7,10 +7,18 @@ import java.util.Optional; +/** + * Repository for {@link Book} entities exposed as a REST resource. + */ @RepositoryRestResource(path = "books") - public interface BookRepository extends JpaRepository { + /** + * Finds a book by id using a cache-backed lookup. + * + * @param id the book identifier + * @return an optional containing the matching book when found + */ @Override @Cacheable(cacheNames = "books", key = "'book_'+#id") Optional findById(Long id); diff --git a/extensions/dashboard/sources/src/main/java/tools/dynamia/modules/dashboard/UserInfoProvider.java b/extensions/dashboard/sources/src/main/java/tools/dynamia/modules/dashboard/UserInfoProvider.java index 8c9b1686..6beb4813 100644 --- a/extensions/dashboard/sources/src/main/java/tools/dynamia/modules/dashboard/UserInfoProvider.java +++ b/extensions/dashboard/sources/src/main/java/tools/dynamia/modules/dashboard/UserInfoProvider.java @@ -19,17 +19,54 @@ import java.util.List; +/** + * Provides user identity and authorization data for dashboard runtime decisions. + * Implementations are used by widgets and dashboard services to evaluate visibility, + * permissions, and user-specific behavior. + */ public interface UserInfoProvider { + /** + * Returns the current authenticated username. + * + * @return the username associated with the current user context + */ String getUsername(); + /** + * Indicates whether the current user has administrative privileges. + * + * @return {@code true} when the user is an administrator + */ boolean isAdmin(); + /** + * Checks if the current user has the specified role. + * + * @param roleName the role name to verify + * @return {@code true} when the user is assigned to the role + */ boolean hasRole(String roleName); + /** + * Checks if the current user has the specified grant/permission. + * + * @param grant the grant identifier to verify + * @return {@code true} when the user has the grant + */ boolean hasGrant(String grant); + /** + * Returns the location identifier associated with the current user. + * + * @return the user location id, or {@code null} when not applicable + */ Long getUserLocation(); + /** + * Returns all role names assigned to the current user. + * + * @return a list of user role names + */ List getUserRoles(); } diff --git a/extensions/entity-files/sources/core/src/main/java/tools/dynamia/modules/entityfile/EntityFileAccountProvider.java b/extensions/entity-files/sources/core/src/main/java/tools/dynamia/modules/entityfile/EntityFileAccountProvider.java index 8ff9ad44..b568d8c3 100644 --- a/extensions/entity-files/sources/core/src/main/java/tools/dynamia/modules/entityfile/EntityFileAccountProvider.java +++ b/extensions/entity-files/sources/core/src/main/java/tools/dynamia/modules/entityfile/EntityFileAccountProvider.java @@ -21,24 +21,27 @@ import tools.dynamia.modules.entityfile.domain.EntityFile; /** - * - * @author Mario Serrano Leones + * Resolves tenant/account context for entity-file operations. + * Implementations provide the current account id and can validate whether + * a specific {@link EntityFile} belongs to a valid account scope. */ public interface EntityFileAccountProvider { /** - * Return current account Id for tenant + * Returns the current tenant account identifier. * - * @return account id + * @return the current account id */ Long getAccountId(); /** - * Check is the account id is valid, by default just validate if account id not null + * Validates whether the given entity file has a usable account id. + * The default implementation checks that the entity file is not null, + * account id is not null, and account id is greater than zero. * - * @param entityFile - * @return valid + * @param entityFile the entity file to validate + * @return {@code true} when the file has a valid account id */ default boolean isValidEntityFile(EntityFile entityFile) { return entityFile != null && entityFile.getAccountId() != null && entityFile.getAccountId() > 0; diff --git a/extensions/entity-files/sources/core/src/main/java/tools/dynamia/modules/entityfile/EntityFileStorage.java b/extensions/entity-files/sources/core/src/main/java/tools/dynamia/modules/entityfile/EntityFileStorage.java index 0b51684e..762313d6 100644 --- a/extensions/entity-files/sources/core/src/main/java/tools/dynamia/modules/entityfile/EntityFileStorage.java +++ b/extensions/entity-files/sources/core/src/main/java/tools/dynamia/modules/entityfile/EntityFileStorage.java @@ -19,18 +19,55 @@ import tools.dynamia.modules.entityfile.domain.EntityFile; +/** + * Defines the contract for storing and retrieving files associated with domain entities. + * Implementations may use local storage, cloud providers, or any custom backend. + */ public interface EntityFileStorage { + /** + * Returns the unique technical identifier of this storage implementation. + * + * @return the storage identifier, used internally to select the implementation + */ String getId(); + /** + * Returns the human-readable name of this storage implementation. + * + * @return display name for logs, configuration, or UI labels + */ String getName(); + /** + * Uploads and persists the provided file information for the given entity file record. + * + * @param entityFile the entity file metadata to be updated with storage information + * @param fileInfo metadata and stream details of the file to upload + */ void upload(EntityFile entityFile, UploadedFileInfo fileInfo); + /** + * Downloads the previously stored file associated with the given entity file record. + * + * @param entityFile the entity file metadata used to locate the stored file + * @return the stored file content and metadata + */ StoredEntityFile download(EntityFile entityFile); + /** + * Deletes the stored file associated with the given entity file record. + * + * @param entityFile the entity file metadata used to locate and remove the stored file + */ void delete(EntityFile entityFile); + /** + * Reloads storage-specific runtime parameters. + *

+ * Implementations can override this method when they need to refresh dynamic + * settings (for example, credentials, endpoints, or bucket names) without restart. + */ default void reloadParams(){ } diff --git a/extensions/file-importer/sources/core/src/main/java/tools/dynamia/modules/importer/ImportBeanParser.java b/extensions/file-importer/sources/core/src/main/java/tools/dynamia/modules/importer/ImportBeanParser.java index 22c27578..0f290627 100644 --- a/extensions/file-importer/sources/core/src/main/java/tools/dynamia/modules/importer/ImportBeanParser.java +++ b/extensions/file-importer/sources/core/src/main/java/tools/dynamia/modules/importer/ImportBeanParser.java @@ -19,9 +19,20 @@ import org.apache.poi.ss.usermodel.Row; +/** + * Functional contract for converting a spreadsheet {@link Row} into a domain object. + * + * @param the target object type produced from each row + */ @FunctionalInterface public interface ImportBeanParser { + /** + * Parses a spreadsheet row into a typed object. + * + * @param row the row to parse + * @return the parsed object instance + */ T parse(Row row); } diff --git a/extensions/file-importer/sources/core/src/main/java/tools/dynamia/modules/importer/ImportReader.java b/extensions/file-importer/sources/core/src/main/java/tools/dynamia/modules/importer/ImportReader.java index 341e18e9..75adeea7 100644 --- a/extensions/file-importer/sources/core/src/main/java/tools/dynamia/modules/importer/ImportReader.java +++ b/extensions/file-importer/sources/core/src/main/java/tools/dynamia/modules/importer/ImportReader.java @@ -19,9 +19,19 @@ import org.apache.poi.ss.usermodel.Row; +/** + * Functional callback invoked for each imported spreadsheet {@link Row}. + * Implementations typically perform side effects such as validation, + * persistence, or aggregation. + */ @FunctionalInterface public interface ImportReader { + /** + * Processes a spreadsheet row. + * + * @param row the row to process + */ void read(Row row); } diff --git a/extensions/reports/sources/core/src/main/java/tools/dynamia/modules/reports/core/ReportDataExporter.java b/extensions/reports/sources/core/src/main/java/tools/dynamia/modules/reports/core/ReportDataExporter.java index 122513a1..9350db07 100644 --- a/extensions/reports/sources/core/src/main/java/tools/dynamia/modules/reports/core/ReportDataExporter.java +++ b/extensions/reports/sources/core/src/main/java/tools/dynamia/modules/reports/core/ReportDataExporter.java @@ -1,5 +1,17 @@ package tools.dynamia.modules.reports.core; +/** + * Converts {@link ReportData} into a specific output representation. + * + * @param the exported output type (for example, a map, DTO, or serialized structure) + */ public interface ReportDataExporter { + + /** + * Exports the provided report data into the target representation. + * + * @param reportData the report data to transform + * @return the exported representation of the report data + */ T export(ReportData reportData); } diff --git a/extensions/security/sources/core/src/main/java/tools/dynamia/modules/security/IgnoringSecurityMatcher.java b/extensions/security/sources/core/src/main/java/tools/dynamia/modules/security/IgnoringSecurityMatcher.java index c389c4b0..30c3a9f8 100644 --- a/extensions/security/sources/core/src/main/java/tools/dynamia/modules/security/IgnoringSecurityMatcher.java +++ b/extensions/security/sources/core/src/main/java/tools/dynamia/modules/security/IgnoringSecurityMatcher.java @@ -15,11 +15,17 @@ package tools.dynamia.modules.security; /** - * - * @author Mario Serrano Leones + * Provides request matcher patterns that should bypass security filters. + * Implementations are typically used to register public paths such as static + * assets, health endpoints, or public APIs. */ public interface IgnoringSecurityMatcher { + /** + * Returns the matcher expressions that must be ignored by security. + * + * @return an array of path matcher patterns + */ String[] matchers(); } diff --git a/extensions/security/sources/core/src/main/java/tools/dynamia/modules/security/LoginControllerInterceptor.java b/extensions/security/sources/core/src/main/java/tools/dynamia/modules/security/LoginControllerInterceptor.java index 540f5bef..8ba2f9cc 100644 --- a/extensions/security/sources/core/src/main/java/tools/dynamia/modules/security/LoginControllerInterceptor.java +++ b/extensions/security/sources/core/src/main/java/tools/dynamia/modules/security/LoginControllerInterceptor.java @@ -16,8 +16,20 @@ import jakarta.servlet.http.HttpServletRequest; import java.util.Map; +/** + * Intercepts login controller rendering to customize model data or flow. + * Implementations can inject additional attributes, flags, or contextual + * values before the login view is rendered. + */ public interface LoginControllerInterceptor { + /** + * Called when the login controller is preparing the login page. + * + * @param request the current HTTP request + * @param viewName the view name that will be rendered + * @param params mutable model parameters for the login view + */ void login(HttpServletRequest request, String viewName, Map params); diff --git a/platform/core/commons/src/main/java/tools/dynamia/commons/Lambdas.java b/platform/core/commons/src/main/java/tools/dynamia/commons/Lambdas.java index 67c87a03..d4cc0810 100644 --- a/platform/core/commons/src/main/java/tools/dynamia/commons/Lambdas.java +++ b/platform/core/commons/src/main/java/tools/dynamia/commons/Lambdas.java @@ -14,13 +14,37 @@ public class Lambdas { + /** + * Consumer variant that allows checked exceptions. + * + * @param the consumed value type + */ @FunctionalInterface public interface ThrowingConsumer { + + /** + * Performs this operation on the given argument. + * + * @param t the input argument + * @throws Exception if processing fails + */ void accept(T t) throws Exception; } + /** + * Supplier variant that allows checked exceptions. + * + * @param the supplied value type + */ @FunctionalInterface public interface ThrowingSupplier { + + /** + * Gets a result value. + * + * @return the supplied value + * @throws Exception if value retrieval fails + */ T get() throws Exception; } diff --git a/platform/core/crud/src/main/java/tools/dynamia/crud/CrudDataSetViewBuilder.java b/platform/core/crud/src/main/java/tools/dynamia/crud/CrudDataSetViewBuilder.java index 6a8e594d..1f54372d 100644 --- a/platform/core/crud/src/main/java/tools/dynamia/crud/CrudDataSetViewBuilder.java +++ b/platform/core/crud/src/main/java/tools/dynamia/crud/CrudDataSetViewBuilder.java @@ -19,15 +19,32 @@ import tools.dynamia.viewers.DataSetView; /** - * - * @author Mario A. Serrano Leones + * Builds {@link DataSetView} instances for CRUD screens. + * Implementations map a view type to its UI builder and optionally + * indicate a preferred controller implementation. */ public interface CrudDataSetViewBuilder { + /** + * Returns the view type name handled by this builder. + * + * @return the supported view type identifier + */ String getViewTypeName(); + /** + * Returns the preferred CRUD controller class for this view builder. + * + * @return the preferred controller type, or {@code null} when not restricted + */ Class getPreferredController(); + /** + * Builds the dataset view for the provided CRUD view component. + * + * @param crudView the CRUD view component context + * @return the constructed dataset view + */ DataSetView build(CrudViewComponent crudView); } diff --git a/platform/core/crud/src/main/java/tools/dynamia/crud/CrudRemoteAction.java b/platform/core/crud/src/main/java/tools/dynamia/crud/CrudRemoteAction.java index b826b8f5..83c455b0 100644 --- a/platform/core/crud/src/main/java/tools/dynamia/crud/CrudRemoteAction.java +++ b/platform/core/crud/src/main/java/tools/dynamia/crud/CrudRemoteAction.java @@ -4,6 +4,11 @@ import tools.dynamia.actions.RemoteAction; +/** + * Remote CRUD action contract with class-aware behavior. + * Implementations represent actions that can be executed remotely + * and are limited to specific {@link CrudState} values. + */ public interface CrudRemoteAction extends RemoteAction, ClassAction { /** diff --git a/platform/ui/zk/src/main/java/tools/dynamia/zk/viewers/form/FormViewModel.java b/platform/ui/zk/src/main/java/tools/dynamia/zk/viewers/form/FormViewModel.java index 04fb1786..02954465 100644 --- a/platform/ui/zk/src/main/java/tools/dynamia/zk/viewers/form/FormViewModel.java +++ b/platform/ui/zk/src/main/java/tools/dynamia/zk/viewers/form/FormViewModel.java @@ -19,12 +19,24 @@ package tools.dynamia.zk.viewers.form; /** - * @author Mario A. Serrano Leones + * Defines the value contract for form view models. + * + * @param the value type managed by the form model */ public interface FormViewModel { + /** + * Returns the current model value bound to the form. + * + * @return the current value + */ T getValue(); + /** + * Updates the model value bound to the form. + * + * @param value the new value to set + */ void setValue(T value);