Enhance documentation for various interfaces with detailed descriptions and usage examples

Author: marioserrano09

platform/core/domain/src/main/java/tools/dynamia/domain/AuditableWithJavaTimes.java

@@ -20,7 +20,65 @@
 import java.time.LocalDateTime;
 import java.time.LocalTime;
 
-
+/**
+ * Interface for entities that require audit tracking using Java 8+ date/time types.
+ * <p>
+ * This interface extends the auditing capabilities by separating date and time components using
+ * {@link LocalDate} and {@link LocalTime} instead of legacy {@link java.util.Date}. It tracks
+ * when entities are created and last modified, along with optional user information.
+ * </p>
+ *
+ * <p>
+ * <b>Key features:</b>
+ * <ul>
+ *   <li>Tracks creation and last update timestamps using modern Java time API</li>
+ *   <li>Separates date and time components for flexible querying and display</li>
+ *   <li>Optional tracking of user who created or last modified the entity</li>
+ *   <li>Provides convenient method to get combined creation date-time</li>
+ *   <li>Improves upon legacy {@link Auditable} interface with modern types</li>
+ * </ul>
+ * </p>
+ *
+ * <p>
+ * <b>Usage example:</b>
+ * <pre>{@code
+ * @Entity
+ * public class Document implements AuditableWithJavaTimes {
+ *
+ *     @Column
+ *     private LocalDate creationDate;
+ *
+ *     @Column
+ *     private LocalTime creationTime;
+ *
+ *     @Column
+ *     private LocalDate lastUpdate;
+ *
+ *     @Column
+ *     private String creator;
+ *
+ *     // Implement getters and setters
+ *
+ *     @PrePersist
+ *     protected void onCreate() {
+ *         setCreationDate(LocalDate.now());
+ *         setCreationTime(LocalTime.now());
+ *     }
+ *
+ *     @PreUpdate
+ *     protected void onUpdate() {
+ *         setLastUpdate(LocalDate.now());
+ *     }
+ * }
+ * }</pre>
+ * </p>
+ *
+ * @author Mario A. Serrano Leones
+ * @see Auditable
+ * @see LocalDate
+ * @see LocalTime
+ * @see LocalDateTime
+ */
 public interface AuditableWithJavaTimes {
 
     /**

platform/core/domain/src/main/java/tools/dynamia/domain/OpenPersistenceInViewProvider.java

@@ -17,10 +17,118 @@
 
 package tools.dynamia.domain;
 
+/**
+ * Interface for implementing the Open Session in View (OSIV) pattern provider.
+ * <p>
+ * This interface defines the contract for managing persistence context lifecycle across view rendering,
+ * commonly known as the "Open Session in View" or "Open EntityManager in View" pattern. It ensures that
+ * lazy-loaded entities remain accessible during view rendering by keeping the persistence context open
+ * beyond the service layer.
+ * </p>
+ *
+ * <p>
+ * <b>Key responsibilities:</b>
+ * <ul>
+ *   <li>Open persistence context before view rendering</li>
+ *   <li>Close persistence context after view rendering completes</li>
+ *   <li>Handle transaction boundaries for view layer operations</li>
+ *   <li>Manage nested or concurrent view rendering scenarios</li>
+ *   <li>Provide mechanism to disable OSIV when needed</li>
+ * </ul>
+ * </p>
+ *
+ * <p>
+ * <b>Pattern flow:</b>
+ * <ol>
+ *   <li>{@link #beforeView()} is called before rendering begins</li>
+ *   <li>View rendering occurs with open persistence context</li>
+ *   <li>{@link #afterView(boolean)} is called after rendering completes</li>
+ *   <li>{@link #isDisabled()} can be checked to skip OSIV processing</li>
+ * </ol>
+ * </p>
+ *
+ * <p>
+ * <b>Usage example:</b>
+ * <pre>{@code
+ * @Component
+ * public class JpaOpenPersistenceInViewProvider implements OpenPersistenceInViewProvider {
+ *
+ *     @Autowired
+ *     private EntityManagerFactory emf;
+ *
+ *     private ThreadLocal<EntityManager> contextHolder = new ThreadLocal<>();
+ *
+ *     @Override
+ *     public boolean beforeView() {
+ *         if (contextHolder.get() != null) {
+ *             return false; // Already participating
+ *         }
+ *         EntityManager em = emf.createEntityManager();
+ *         contextHolder.set(em);
+ *         return true;
+ *     }
+ *
+ *     @Override
+ *     public void afterView(boolean participate) {
+ *         if (participate) {
+ *             EntityManager em = contextHolder.get();
+ *             if (em != null) {
+ *                 em.close();
+ *                 contextHolder.remove();
+ *             }
+ *         }
+ *     }
+ *
+ *     @Override
+ *     public boolean isDisabled() {
+ *         return false; // Enable OSIV
+ *     }
+ * }
+ * }</pre>
+ * </p>
+ *
+ * <p>
+ * <b>Note:</b> While OSIV is convenient for avoiding {@code LazyInitializationException}, it should be used
+ * carefully as it can lead to performance issues and unexpected database queries in the view layer.
+ * </p>
+ *
+ * @author Mario A. Serrano Leones
+ */
 public interface OpenPersistenceInViewProvider {
+
+    /**
+     * Called before view rendering begins to open the persistence context.
+     * <p>
+     * Implementations should open a new persistence session/context if one doesn't already exist
+     * for the current thread or request. This method should return {@code true} if a new context
+     * was opened, or {@code false} if already participating in an existing context.
+     * </p>
+     *
+     * @return {@code true} if a new persistence context was opened, {@code false} if already participating
+     */
     boolean beforeView();
 
+    /**
+     * Called after view rendering completes to close the persistence context.
+     * <p>
+     * Implementations should close the persistence context only if this provider opened it
+     * (i.e., {@code participate} is {@code true}). This ensures proper cleanup without interfering
+     * with nested or concurrent view rendering.
+     * </p>
+     *
+     * @param participate {@code true} if this provider opened the context in {@link #beforeView()},
+     *                    {@code false} if it was already open
+     */
     void afterView(boolean participate);
 
+    /**
+     * Checks whether the Open Session in View pattern is disabled.
+     * <p>
+     * When this method returns {@code true}, the OSIV mechanism is skipped entirely, and
+     * persistence context management follows standard service-layer boundaries.
+     * </p>
+     *
+     * @return {@code true} if OSIV is disabled, {@code false} otherwise
+     */
     boolean isDisabled();
 }

platform/core/domain/src/main/java/tools/dynamia/domain/fx/FunctionProvider.java

@@ -17,11 +17,87 @@
 
 package tools.dynamia.domain.fx;
 
+/**
+ * Interface for providing named functions that can be executed dynamically within the framework.
+ * <p>
+ * This interface allows components to expose reusable functions or expressions that can be evaluated
+ * at runtime. Functions can represent business logic, calculations, queries, scripts, or any other
+ * executable code that needs to be referenced by name. This is particularly useful for dynamic
+ * behavior, plugin architectures, rule engines, and expression evaluation systems.
+ * </p>
+ *
+ * <p>
+ * <b>Key use cases:</b>
+ * <ul>
+ *   <li>Dynamic field calculations and computed properties</li>
+ *   <li>Business rule definitions and validation logic</li>
+ *   <li>Query builders and filter expressions</li>
+ *   <li>Scripting and formula evaluation</li>
+ *   <li>Plugin-based extensibility</li>
+ * </ul>
+ * </p>
+ *
+ * <p>
+ * <b>Usage example:</b>
+ * <pre>{@code
+ * @Component
+ * public class TaxCalculationFunction implements FunctionProvider {
+ *
+ *     @Override
+ *     public String getName() {
+ *         return "calculateTax";
+ *     }
+ *
+ *     @Override
+ *     public String getFunction() {
+ *         return "amount * 0.19"; // 19% tax formula
+ *     }
+ * }
+ *
+ * // Or for SQL functions
+ * @Component
+ * public class FullNameFunction implements FunctionProvider {
+ *
+ *     @Override
+ *     public String getName() {
+ *         return "fullName";
+ *     }
+ *
+ *     @Override
+ *     public String getFunction() {
+ *         return "CONCAT(firstName, ' ', lastName)";
+ *     }
+ * }
+ * }</pre>
+ * </p>
+ *
+ * @author Mario A. Serrano Leones
+ * @see Function
+ * @see MultiFunctionProcessor
+ */
 public interface FunctionProvider {
 
-
+    /**
+     * Returns the unique name of this function.
+     * <p>
+     * The name is used to identify and reference the function within the system. It should be
+     * unique, descriptive, and follow naming conventions (e.g., camelCase or snake_case).
+     * </p>
+     *
+     * @return the function name
+     */
     String getName();
 
+    /**
+     * Returns the function definition, expression, or implementation code.
+     * <p>
+     * The returned string can be a formula, expression, SQL snippet, script code, or any other
+     * representation of the function logic. The format depends on how the function will be
+     * processed by the function processor or evaluation engine.
+     * </p>
+     *
+     * @return the function definition or expression
+     */
     String getFunction();
 
 }

platform/core/domain/src/main/java/tools/dynamia/domain/fx/MultiFunctionProcessor.java

@@ -20,9 +20,79 @@
 import java.util.List;
 import java.util.Map;
 
+/**
+ * Interface for processing multiple functions in batch against a dataset.
+ * <p>
+ * This interface defines the contract for executing multiple {@link FunctionProvider} instances
+ * against a single data source with shared arguments, returning the computed results for each function.
+ * This is useful for bulk calculations, aggregations, or applying multiple transformations efficiently
+ * without repeated data access.
+ * </p>
+ *
+ * <p>
+ * <b>Key benefits:</b>
+ * <ul>
+ *   <li>Batch processing of multiple functions reduces overhead</li>
+ *   <li>Shared data context and arguments across all functions</li>
+ *   <li>Results mapped to their corresponding function providers</li>
+ *   <li>Efficient for database queries, calculations, or transformations</li>
+ *   <li>Supports parallel or optimized execution strategies</li>
+ * </ul>
+ * </p>
+ *
+ * <p>
+ * <b>Usage example:</b>
+ * <pre>{@code
+ * @Component
+ * public class SqlFunctionProcessor implements MultiFunctionProcessor<DataSource, Object> {
+ *
+ *     @Override
+ *     public Map<FunctionProvider, Object> compute(DataSource data,
+ *                                                   Map<String, Object> args,
+ *                                                   List<FunctionProvider> functions) {
+ *         Map<FunctionProvider, Object> results = new HashMap<>();
+ *
+ *         try (Connection conn = data.getConnection()) {
+ *             for (FunctionProvider function : functions) {
+ *                 String sql = buildQuery(function, args);
+ *                 Object result = executeQuery(conn, sql);
+ *                 results.put(function, result);
+ *             }
+ *         }
+ *
+ *         return results;
+ *     }
+ * }
+ *
+ * // Usage
+ * List<FunctionProvider> functions = Arrays.asList(totalFunction, avgFunction, maxFunction);
+ * Map<String, Object> args = Map.of("year", 2024, "status", "active");
+ * Map<FunctionProvider, Object> results = processor.compute(dataSource, args, functions);
+ * }</pre>
+ * </p>
+ *
+ * @param <D> the type of data source or dataset to process
+ * @param <R> the type of result produced by each function
+ * @author Mario A. Serrano Leones
+ * @see FunctionProvider
+ * @see Function
+ */
 public interface MultiFunctionProcessor<D, R> {
 
-
+    /**
+     * Computes and executes all provided functions against the given data source with the specified arguments.
+     * <p>
+     * This method processes all functions in the list, applying them to the data source using the shared
+     * arguments. Each function's result is mapped to its corresponding {@link FunctionProvider} in the
+     * returned map. Implementations may optimize execution by batching operations or executing functions
+     * in parallel.
+     * </p>
+     *
+     * @param data the data source or dataset to process (e.g., database connection, entity, collection)
+     * @param args shared arguments/parameters available to all functions during execution
+     * @param functions list of function providers to execute against the data
+     * @return a map where each function provider is associated with its computed result
+     */
     Map<FunctionProvider, R> compute(D data, Map<String, Object> args, List<FunctionProvider> functions);