You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@unomi.apache.org by "sergehuber (via GitHub)" <gi...@apache.org> on 2026/05/06 09:21:12 UTC

[PR] UNOMI-888: Javadoc and API cleanup for import/export router extension [unomi]

sergehuber opened a new pull request, #756:
URL: https://github.com/apache/unomi/pull/756

   ## Summary
   
   [JIRA: UNOMI-888](https://issues.apache.org/jira/browse/UNOMI-888)
   
   Improves public documentation for the profile **import/export router** (`extensions/router/router-api`, `extensions/router/router-core`) by replacing placeholder comments with substantive Javadoc on the facade, configuration types, services, processors, route builders, aggregation strategies, and related API types.
   
   Includes a few **small behavioral/API corrections** found while documenting.
   
   ## What changed
   
   ### Documentation
   - **`IRouterCamelContext`**: Facade-level description and method-level Javadoc for route lifecycle operations.
   - **`ImportExportConfiguration`**, **`ProfileToImport`**, **`BadProfileDataFormatException`**, import/export **service interfaces**: Expanded and clarified docs (including consistent wording for shared import/export configuration).
   - **`RouterCamelContext`**, **processors**, **route builders**, **aggregation strategies**, **`CollectProfileBean`**: Class and member documentation aligned with actual responsibilities.
   
   ### Small fixes (non-doc)
   - **`IRouterCamelContext`**: Add **`Object getCamelContext()`** so API consumers are not forced to depend on Camel types at compile time (implementations may still return the concrete Camel context).
   - **`RouterCamelContext`**: **`setTracing(boolean)`** now honors the argument (previously always enabled tracing); **`@Override`** + **`{@inheritDoc}`** on interface methods.
   - **`ImportExportConfiguration#setColumnSeparator`**: Null-check the **parameter** (consistent with **`setLineSeparator`**).
   - **`LineSplitFailureHandler`**: **`@Override`** on **`process(Exchange)`**.
   
   ## Verification
   
   - [X] Local build successful  
   - [X] Integration tests successful  
   
   *(Fill in the exact Maven commands you ran, e.g. router modules compile / full `itests`.)*
   
   ## Scope
   
   - **24 files** under `extensions/router/` (commit `51aa61c9f`).


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@unomi.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] UNOMI-888: Javadoc and API cleanup for import/export router extension [unomi]

Posted by "sergehuber (via GitHub)" <gi...@apache.org>.
sergehuber commented on code in PR #756:
URL: https://github.com/apache/unomi/pull/756#discussion_r3254129302


##########
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/route/ProfileImportOneShotRouteBuilder.java:
##########
@@ -30,18 +30,59 @@
 import java.util.Map;
 
 /**
- * Created by amidani on 22/05/2017.
+ * A Camel route builder that handles one-time profile imports from files.
+ * This route builder creates routes that process CSV files dropped into a
+ * monitored directory for one-time import operations.
+ *
+ * <p>Features:
+ * <ul>
+ *   <li>File-based import processing</li>
+ *   <li>Configuration lookup from filename</li>
+ *   <li>CSV file processing with error handling</li>
+ *   <li>Support for both Kafka and direct endpoints</li>
+ *   <li>Automatic file movement after processing</li>
+ *   <li>Error reporting and failed file handling</li>
+ * </ul>
+ * </p>
+ *
+ * @since 1.0
  */
 public class ProfileImportOneShotRouteBuilder extends RouterAbstractRouteBuilder {
 
     private static final Logger LOGGER = LoggerFactory.getLogger(ProfileImportOneShotRouteBuilder.class.getName());
+
+    /** Processor for extracting import configuration from filenames */
     private ImportConfigByFileNameProcessor importConfigByFileNameProcessor;
+
+    /** Directory to monitor for import files */
     private String uploadDir;
 
+    /**
+     * Constructs a new route builder with Kafka configuration.
+     *
+     * @param kafkaProps map containing Kafka configuration properties
+     * @param configType the type of configuration (kafka/direct)

Review Comment:
   Same fix — transport mode documented as `kafka` / `nobroker`, not `direct`.



##########
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/route/ProfileImportToUnomiRouteBuilder.java:
##########
@@ -29,19 +29,56 @@
 import java.util.Map;
 
 /**
- * Created by amidani on 26/04/2017.
+ * A Camel route builder that handles the final stage of profile imports by storing
+ * processed profile data into Apache Unomi's storage system.
+ *
+ * <p>Features:
+ * <ul>
+ *   <li>Final processing of imported profiles</li>
+ *   <li>Integration with Unomi's storage system</li>
+ *   <li>Support for both Kafka and direct endpoints</li>
+ *   <li>Import completion handling</li>
+ *   <li>Error handling and reporting</li>
+ * </ul>
+ * </p>
+ *
+ * @since 1.0
  */
 public class ProfileImportToUnomiRouteBuilder extends RouterAbstractRouteBuilder {
 
     private static final Logger LOGGER = LoggerFactory.getLogger(ProfileImportToUnomiRouteBuilder.class.getName());
 
+    /** Processor for storing profiles in Unomi */
     private UnomiStorageProcessor unomiStorageProcessor;
+
+    /** Processor for handling import completion */
     private ImportRouteCompletionProcessor importRouteCompletionProcessor;
 
+    /**
+     * Constructs a new route builder with Kafka configuration.
+     *
+     * @param kafkaProps map containing Kafka configuration properties
+     * @param configType the type of configuration (kafka/direct)

Review Comment:
   Same fix — updated class and constructor Javadoc for the actual `configType` values.



##########
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/processor/ImportRouteCompletionProcessor.java:
##########
@@ -26,15 +26,51 @@
 import java.util.*;
 
 /**
- * Created by amidani on 14/06/2017.
+ * A Camel processor that handles the completion of profile import routes.
+ * This processor manages the final stage of import operations, collecting statistics,
+ * handling errors, and updating the import configuration with execution results.
+ *
+ * <p>The processor performs the following operations:
+ * <ul>
+ *   <li>Collects import statistics (success, failure, ignore counts)</li>
+ *   <li>Manages error reporting with configurable limits</li>

Review Comment:
   Adjusted Javadoc to describe only persisted statistics (success/failure counts and errors). `ignoreCount` is counted locally but not written to the execution record — docs no longer claim it is collected.



##########
extensions/router/router-api/src/main/java/org/apache/unomi/router/api/exceptions/BadProfileDataFormatException.java:
##########
@@ -17,18 +17,57 @@
 package org.apache.unomi.router.api.exceptions;
 
 /**
- * Created by amidani on 13/06/2017.
+ * Exception thrown when profile data cannot be properly parsed or formatted during import/export operations.
+ * This exception indicates issues with the structure or content of profile data that prevent it from being
+ * properly processed by the Unomi router.
+ *
+ * <p>Common scenarios where this exception is thrown:
+ * <ul>
+ *   <li>Invalid CSV format in import files</li>
+ *   <li>Missing required profile fields</li>
+ *   <li>Incorrect data types for profile properties</li>
+ *   <li>Malformed multi-value fields</li>
+ *   <li>Invalid date formats</li>

Review Comment:
   Removed "invalid date formats" from the documented scenarios; date fields are not format-validated separately today. Listed causes now match what `LineSplitProcessor` actually throws for.



##########
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/bean/CollectProfileBean.java:
##########
@@ -22,17 +22,43 @@
 import java.util.List;
 
 /**
- * Created by amidani on 28/06/2017.
+ * A bean that handles the collection of profiles based on segment criteria.
+ * This class provides functionality to extract profiles from Unomi's persistence
+ * layer based on segment membership.
+ *
+ * <p>Features:
+ * <ul>
+ *   <li>Segment-based profile extraction</li>
+ *   <li>Integration with Unomi's persistence service</li>
+ *   <li>Batch profile retrieval capabilities</li>

Review Comment:
   Removed the "batch profile retrieval" bullet. Docs now describe segment-based query via `persistenceService.query(...)`, consistent with the memory note (UNOMI-759).



##########
extensions/router/router-api/src/main/java/org/apache/unomi/router/api/services/ProfileImportService.java:
##########
@@ -21,9 +21,54 @@
 import java.lang.reflect.InvocationTargetException;
 
 /**
- * Created by amidani on 20/05/2017.
+ * Service interface for handling the import of individual profiles into Apache Unomi.
+ * This service is responsible for the actual processing and storage of imported profile data,
+ * including merging with existing profiles or creating new ones as needed.
+ *
+ * <p>Key responsibilities:
+ * <ul>
+ *   <li>Processing individual profile imports</li>
+ *   <li>Merging imported data with existing profiles</li>
+ *   <li>Handling profile creation for new imports</li>
+ *   <li>Managing profile deletion when specified</li>
+ * </ul>
+ * </p>
+ *
+ * <p>Usage in Unomi:
+ * <ul>
+ *   <li>Called by import route processors to handle individual profile data</li>
+ *   <li>Used during batch import operations</li>
+ *   <li>Integrated with Unomi's profile management system</li>
+ * </ul>
+ * </p>
+ *
+ * <p>Implementation considerations:
+ * <ul>
+ *   <li>Must handle profile merging strategies</li>
+ *   <li>Should implement proper error handling</li>
+ *   <li>Must maintain data consistency</li>
+ *   <li>Should handle property type conversions</li>
+ * </ul>

Review Comment:
   Updated implementation considerations: property type conversion happens upstream (e.g. `LineSplitProcessor`); this service merges/deletes/saves prepared profiles only.



##########
extensions/router/router-api/src/main/java/org/apache/unomi/router/api/exceptions/BadProfileDataFormatException.java:
##########
@@ -17,18 +17,57 @@
 package org.apache.unomi.router.api.exceptions;
 
 /**
- * Created by amidani on 13/06/2017.
+ * Exception thrown when profile data cannot be properly parsed or formatted during import/export operations.
+ * This exception indicates issues with the structure or content of profile data that prevent it from being
+ * properly processed by the Unomi router.

Review Comment:
   Narrowed class Javadoc to **import** line processing only; export paths do not throw or handle this exception.



##########
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/context/RouterCamelContext.java:
##########
@@ -49,7 +49,25 @@
 import java.util.concurrent.TimeUnit;
 
 /**
- * Created by amidani on 04/05/2017.
+ * The main Camel context manager for the Unomi Router component.
+ * This class manages the lifecycle of all import and export routes,
+ * handles route configuration updates, and maintains the Camel context.
+ *
+ * <p>Features:
+ * <ul>
+ *   <li>Initializes and manages the Camel context</li>
+ *   <li>Sets up import and export routes</li>
+ *   <li>Handles route configuration updates</li>
+ *   <li>Manages route lifecycle (start/stop/update)</li>
+ *   <li>Provides monitoring through event notifications</li>

Review Comment:
   Removed "monitoring through event notifications" from the feature list. The class does not publish router events today (`fireEvent` is unused).



##########
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/context/RouterCamelContext.java:
##########
@@ -79,8 +97,11 @@ public class RouterCamelContext implements IRouterCamelContext {
     private Integer configsRefreshInterval = 1000;
     private ScheduledFuture<?> scheduledFuture;
 
+    /** Event topic fired when a router configuration or route is removed (reserved for integrations). */

Review Comment:
   Documented `EVENT_ID_REMOVE` as a **reserved** topic identifier for future use — not published by the current implementation. We kept constants as placeholders rather than implementing emission in this PR.



##########
extensions/router/router-api/src/main/java/org/apache/unomi/router/api/services/ProfileExportService.java:
##########
@@ -23,12 +23,67 @@
 import java.util.Collection;
 
 /**
- * Created by amidani on 30/06/2017.
+ * Service interface for handling the export of profiles from Apache Unomi.
+ * This service is responsible for extracting profiles based on segment criteria
+ * and converting them into the appropriate export format (e.g., CSV).
+ *
+ * <p>Key responsibilities:
+ * <ul>
+ *   <li>Extracting profiles based on segment criteria</li>
+ *   <li>Converting profiles to export format</li>
+ *   <li>Handling data formatting and transformation</li>
+ *   <li>Managing export file generation</li>
+ * </ul>
+ * </p>
+ *
+ * <p>Usage in Unomi:
+ * <ul>
+ *   <li>Called by export route processors to handle profile extraction</li>
+ *   <li>Used during scheduled export operations</li>
+ *   <li>Integrated with Unomi's segmentation system</li>
+ * </ul>
+ * </p>
+ *
+ * <p>Implementation considerations:
+ * <ul>
+ *   <li>Must handle large data sets efficiently</li>
+ *   <li>Should implement proper error handling</li>
+ *   <li>Must respect profile property formatting</li>
+ *   <li>Should handle multi-valued properties</li>
+ * </ul>
+ * </p>
+ *
+ * @see Profile
+ * @see ExportConfiguration
+ * @see PropertyType
+ * @since 1.0
  */
 public interface ProfileExportService {
 
+    /**
+     * Extracts profiles belonging to a specified segment and formats them for export.
+     * This method handles the bulk export operation, including:
+     * - Querying profiles based on segment criteria
+     * - Formatting profiles according to export configuration
+     * - Generating the export content
+     *
+     * @param exportConfiguration the configuration specifying export parameters and format

Review Comment:
   Updated `extractProfilesBySegment` Javadoc to mention that implementations query profiles, build CSV content, **append an execution record**, and **persist** the updated export configuration — not a pure read/format helper.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@unomi.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] UNOMI-888: Javadoc and API cleanup for import/export router extension [unomi]

Posted by "sergehuber (via GitHub)" <gi...@apache.org>.
sergehuber merged PR #756:
URL: https://github.com/apache/unomi/pull/756


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@unomi.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] UNOMI-888: Javadoc and API cleanup for import/export router extension [unomi]

Posted by "sergehuber (via GitHub)" <gi...@apache.org>.
sergehuber commented on code in PR #756:
URL: https://github.com/apache/unomi/pull/756#discussion_r3254128922


##########
extensions/router/router-api/src/main/java/org/apache/unomi/router/api/ProfileToImport.java:
##########
@@ -22,56 +22,118 @@
 import java.util.List;
 
 /**
- * An extension of {@link Profile} to handle merge strategy and deletion when importing profiles
+ * A specialized Profile class designed for import operations in Apache Unomi.
+ * This class extends the standard {@link Profile} with additional properties and behaviors
+ * specifically needed during the profile import process.
+ *
+ * <p>Key features:
+ * <ul>
+ *   <li>Controls which properties should be overwritten during import</li>
+ *   <li>Specifies the property used for merging with existing profiles</li>
+ *   <li>Handles profile deletion flags</li>
+ *   <li>Controls overwrite behavior for existing profiles</li>
+ * </ul>
+ * </p>
+ *
+ * <p>Usage in Unomi:
+ * <ul>
+ *   <li>Used by import processors to handle profile data</li>
+ *   <li>Consumed by ProfileImportService for import operations</li>
+ *   <li>Supports different import strategies (merge/overwrite/delete)</li>
+ * </ul>
+ * </p>
+ *
+ * @see Profile
+ * @see org.apache.unomi.router.api.services.ProfileImportService
+ * @since 1.0
  */
 public class ProfileToImport extends Profile {
 
+    /** List of property names that should be overwritten during import */
     private List<String> propertiesToOverwrite;
+
+    /** Property used to identify existing profiles for merging */
     private String mergingProperty;
+
+    /** Flag indicating if this profile should be deleted */
     private boolean profileToDelete;
-    private boolean overwriteExistingProfiles;
 
+    /** Flag controlling whether to overwrite existing profile data */
+    private boolean overwriteExistingProfiles;
 
+    /**
+     * Gets the list of properties that should be overwritten during import.
+     * These properties will be updated even if they already exist in the target profile.
+     *
+     * @return list of property names to overwrite
+     */
     public List<String> getPropertiesToOverwrite() {
         return this.propertiesToOverwrite;
     }
 
+    /**
+     * Sets the list of properties that should be overwritten during import.
+     *
+     * @param propertiesToOverwrite list of property names that should be overwritten
+     */
     public void setPropertiesToOverwrite(List<String> propertiesToOverwrite) {
         this.propertiesToOverwrite = propertiesToOverwrite;
     }
 
+    /**
+     * Checks if this profile is marked for deletion.
+     * When true, the matching profile in the system will be deleted rather than updated.
+     *
+     * @return true if the profile should be deleted, false otherwise
+     */
     public boolean isProfileToDelete() {
         return this.profileToDelete;
     }
 
+    /**
+     * Sets whether this profile should be deleted during import.
+     *
+     * @param profileToDelete true to mark the profile for deletion, false otherwise
+     */
     public void setProfileToDelete(boolean profileToDelete) {
         this.profileToDelete = profileToDelete;
     }
 
+    /**
+     * Checks if existing profiles should be overwritten during import.
+     * When true, all properties of existing profiles will be overwritten with imported data.
+     *
+     * @return true if existing profiles should be overwritten, false for selective updates
+     */
     public boolean isOverwriteExistingProfiles() {
         return this.overwriteExistingProfiles;
     }
 
     /**
-     * Sets the overwriteExistingProfiles flag.
-     * @param overwriteExistingProfiles flag used to specify if we want to overwrite existing profiles
+     * Sets whether existing profiles should be completely overwritten during import.
+     *
+     * @param overwriteExistingProfiles true to overwrite all properties, false for selective updates
      */

Review Comment:
   Thanks — agreed. Updated `isOverwriteExistingProfiles()` / setter Javadoc to match `ProfileImportServiceImpl`: when `true` and `propertiesToOverwrite` is non-empty, only listed properties are updated; otherwise the full properties map is replaced.



##########
extensions/router/router-api/src/main/java/org/apache/unomi/router/api/ImportExportConfiguration.java:
##########
@@ -16,15 +16,50 @@
  */
 package org.apache.unomi.router.api;
 
-        import org.apache.unomi.api.Item;
+import org.apache.unomi.api.Item;
 
-        import java.util.ArrayList;
-        import java.util.HashMap;
-        import java.util.List;
-        import java.util.Map;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
 
 /**
- * Created by amidani on 21/06/2017.
+ * Base configuration class for import and export operations in Apache Unomi.
+ * This class serves as the foundation for both ImportConfiguration and ExportConfiguration,
+ * providing common configuration properties and behaviors needed for data transfer operations.
+ *
+ * <p>Key features and responsibilities:
+ * <ul>
+ *   <li>Defines common configuration properties for import/export operations</li>
+ *   <li>Manages separators and delimiters for CSV-like file formats</li>
+ *   <li>Tracks execution status and history</li>
+ *   <li>Handles configuration activation/deactivation</li>
+ * </ul>
+ * </p>
+ *
+ * <p>Usage in Unomi:
+ * <ul>
+ *   <li>Used by ImportExportConfigurationService to manage data transfer configurations</li>
+ *   <li>Consumed by Camel routes to determine how to process data</li>
+ *   <li>Referenced by import/export processors to format data correctly</li>
+ * </ul>
+ * </p>
+ *
+ * <p>Configuration properties include:
+ * <ul>
+ *   <li>name - unique identifier for the configuration</li>

Review Comment:
   Good catch. Class-level docs now distinguish `itemId` (persisted identifier used by router services and routes) from `name` (display label only).



##########
extensions/router/router-api/src/main/java/org/apache/unomi/router/api/ImportExportConfiguration.java:
##########
@@ -53,43 +88,49 @@ public void setProperty(String name, Object value) {
     }
 
     /**
-     * Retrieves the name of the import configuration
-     * @return the name of the import configuration
+     * Retrieves the display name of this configuration.
+     *
+     * @return the name of this configuration
      */
     public String getName() { return this.name; }
 
     /**
-     * Sets the name of the import configuration
-     * @param name the name of the import configuration
+     * Sets the display name of this configuration.
+     *
+     * @param name the name of this configuration
      */
     public void setName(String name) {
         this.name = name;
     }
 
     /**
-     * Retrieves the description of the import configuration
-     * @return the description of the import configuration
+     * Retrieves the human-readable description of this configuration.
+     *
+     * @return the description of this configuration
      */
     public String getDescription() { return this.description; }
 
     /**
-     * Sets the description of the import configuration
-     * @param description the description of the import configuration
+     * Sets the human-readable description of this configuration.
+     *
+     * @param description the description of this configuration
      */
     public void setDescription(String description) {
         this.description = description;
     }
 
 
     /**
-     * Retrieves the config type of the import configuration
-     * @return the config type of the import configuration
+     * Retrieves the configuration type (for example import vs export semantics used by the router).
+     *
+     * @return the config type of this configuration
      */
     public String getConfigType() { return this.configType; }
 
     /**
-     * Sets the config type of the import configuration
-     * @param configType the config type of the import configuration
+     * Sets the configuration type.
+     *
+     * @param configType the config type for this configuration
      */

Review Comment:
   Fixed. `getConfigType()` / `setConfigType()` Javadoc now documents scheduling mode (`recurrent` / `oneshot` via `RouterConstants.IMPORT_EXPORT_CONFIG_TYPE_*`), not import vs export.



##########
extensions/router/router-api/src/main/java/org/apache/unomi/router/api/ImportExportConfiguration.java:
##########
@@ -159,11 +200,12 @@ public String getColumnSeparator() {
     }
 
     /**
-     * Sets the column separator.
-     * @param columnSeparator property used to specify a line separator. Defaults to ','
+     * Sets the column separator used when reading or writing delimited text (typically CSV).
+     *
+     * @param columnSeparator the column delimiter; defaults to {@code ","} when not overridden
      */
     public void setColumnSeparator(String columnSeparator) {
-        if(this.columnSeparator !=null) {
+        if (columnSeparator != null) {

Review Comment:
   Addressed. `setColumnSeparator()` now rejects empty or multi-character values with `IllegalArgumentException`, consistent with import (`charAt(0)`) and export usage.



##########
extensions/router/router-api/src/main/java/org/apache/unomi/router/api/IRouterCamelContext.java:
##########
@@ -17,15 +17,78 @@
 package org.apache.unomi.router.api;
 
 /**
- * Created by amidani on 18/10/2017.
+ * Facade for the Apache Camel runtime used by the Unomi Router extension.
+ * Implementations manage dynamic routes for profile import (from sources such as Kafka or files)
+ * and profile export (collection and producer pipelines), and expose a minimal API so callers do not
+ * depend on Camel types unless they choose to.
+ *
+ * <p>Key responsibilities:
+ * <ul>
+ *   <li>Removing obsolete Camel route definitions when configurations change or are deleted</li>
+ *   <li>Rebuilding import reader routes after an {@link org.apache.unomi.router.api.ImportConfiguration} update</li>
+ *   <li>Rebuilding export reader routes after an {@link org.apache.unomi.router.api.ExportConfiguration} update</li>
+ *   <li>Optional Camel tracing for troubleshooting route execution</li>
+ * </ul>
+ * </p>
+ *
+ * <p>Typical usage:
+ * <ul>
+ *   <li>Management services call update methods when import/export configuration documents change</li>
+ *   <li>Cleanup paths call {@link #killExistingRoute(String, boolean)} to drop routes whose configs were removed</li>
+ * </ul>
+ * </p>
+ *
+ * @see org.apache.unomi.router.core.context.RouterCamelContext

Review Comment:
   Removed the `@see` to `RouterCamelContext` so `router-api` Javadoc stays implementation-neutral and does not reference `router-core`.



##########
extensions/router/router-api/src/main/java/org/apache/unomi/router/api/IRouterCamelContext.java:
##########
@@ -17,15 +17,78 @@
 package org.apache.unomi.router.api;
 
 /**
- * Created by amidani on 18/10/2017.
+ * Facade for the Apache Camel runtime used by the Unomi Router extension.
+ * Implementations manage dynamic routes for profile import (from sources such as Kafka or files)
+ * and profile export (collection and producer pipelines), and expose a minimal API so callers do not
+ * depend on Camel types unless they choose to.
+ *
+ * <p>Key responsibilities:
+ * <ul>
+ *   <li>Removing obsolete Camel route definitions when configurations change or are deleted</li>
+ *   <li>Rebuilding import reader routes after an {@link org.apache.unomi.router.api.ImportConfiguration} update</li>
+ *   <li>Rebuilding export reader routes after an {@link org.apache.unomi.router.api.ExportConfiguration} update</li>
+ *   <li>Optional Camel tracing for troubleshooting route execution</li>
+ * </ul>
+ * </p>
+ *
+ * <p>Typical usage:
+ * <ul>
+ *   <li>Management services call update methods when import/export configuration documents change</li>
+ *   <li>Cleanup paths call {@link #killExistingRoute(String, boolean)} to drop routes whose configs were removed</li>
+ * </ul>
+ * </p>
+ *
+ * @see org.apache.unomi.router.core.context.RouterCamelContext
+ * @since 1.0
  */
 public interface IRouterCamelContext {
 
+    /**
+     * Stops and removes an existing Camel route by id, if it is currently registered in the context.
+     *
+     * @param routeId   Camel route identifier (usually aligned with import/export configuration id)
+     * @param fireEvent when {@code true}, signals that router lifecycle events may be emitted; the concrete
+     *                  implementation defines whether events are fired (reserved hook for observability)
+     * @throws Exception if Camel fails to remove the route definition
+     */
     void killExistingRoute(String routeId, boolean fireEvent) throws Exception;
 
+    /**
+     * Refreshes the profile import reader route for the given configuration: removes any existing route with the
+     * same id, loads the {@link org.apache.unomi.router.api.ImportConfiguration}, and—for recurrent configs—
+     * registers a new route built from current settings.
+     *
+     * @param configId  identifier of the import configuration whose reader route should be updated
+     * @param fireEvent when {@code true}, signals that router lifecycle events may be emitted after the update
+     * @throws Exception if route removal or registration fails
+     */
     void updateProfileImportReaderRoute(String configId, boolean fireEvent) throws Exception;
 
+    /**
+     * Refreshes the profile export reader (collect) route for the given configuration: removes any existing route
+     * with the same id, loads the {@link org.apache.unomi.router.api.ExportConfiguration}, and—for recurrent
+     * configs—registers a new collect route built from current settings.
+     *
+     * @param configId  identifier of the export configuration whose reader route should be updated
+     * @param fireEvent when {@code true}, signals that router lifecycle events may be emitted after the update
+     * @throws Exception if route removal or registration fails
+     */
     void updateProfileExportReaderRoute(String configId, boolean fireEvent) throws Exception;
 
+    /**
+     * Enables or disables Camel route tracing on the underlying {@code CamelContext} for debugging (message flow,
+     * exchanges). Intended for diagnostics in development or incident analysis; may have performance impact when on.
+     *
+     * @param tracing {@code true} to enable Camel tracing, {@code false} to disable
+     */
     void setTracing(boolean tracing);
+
+    /**
+     * Returns the underlying Camel context instance.
+     * The API uses {@link Object} so consumers of this module are not required to depend on Camel at compile time.
+     * Callers that ship Camel may cast to {@code org.apache.camel.CamelContext}.
+     *
+     * @return the Camel context instance, or {@code null} if not initialized
+     */
+    Object getCamelContext();

Review Comment:
   Agreed. `getCamelContext()` is now a **default** method returning `null`, so existing third-party implementations remain source-compatible; `RouterCamelContext` overrides with the real context.



##########
extensions/router/router-api/src/main/java/org/apache/unomi/router/api/services/ProfileExportService.java:
##########
@@ -23,12 +23,67 @@
 import java.util.Collection;
 
 /**
- * Created by amidani on 30/06/2017.
+ * Service interface for handling the export of profiles from Apache Unomi.
+ * This service is responsible for extracting profiles based on segment criteria
+ * and converting them into the appropriate export format (e.g., CSV).
+ *
+ * <p>Key responsibilities:
+ * <ul>
+ *   <li>Extracting profiles based on segment criteria</li>
+ *   <li>Converting profiles to export format</li>
+ *   <li>Handling data formatting and transformation</li>
+ *   <li>Managing export file generation</li>
+ * </ul>
+ * </p>
+ *
+ * <p>Usage in Unomi:
+ * <ul>
+ *   <li>Called by export route processors to handle profile extraction</li>
+ *   <li>Used during scheduled export operations</li>
+ *   <li>Integrated with Unomi's segmentation system</li>
+ * </ul>
+ * </p>
+ *
+ * <p>Implementation considerations:
+ * <ul>
+ *   <li>Must handle large data sets efficiently</li>
+ *   <li>Should implement proper error handling</li>
+ *   <li>Must respect profile property formatting</li>
+ *   <li>Should handle multi-valued properties</li>
+ * </ul>
+ * </p>
+ *
+ * @see Profile
+ * @see ExportConfiguration
+ * @see PropertyType
+ * @since 1.0
  */
 public interface ProfileExportService {
 
+    /**
+     * Extracts profiles belonging to a specified segment and formats them for export.
+     * This method handles the bulk export operation, including:
+     * - Querying profiles based on segment criteria
+     * - Formatting profiles according to export configuration
+     * - Generating the export content
+     *
+     * @param exportConfiguration the configuration specifying export parameters and format
+     * @return a String containing the formatted export data
+     */
     String extractProfilesBySegment(ExportConfiguration exportConfiguration);
 
+    /**
+     * Converts a single profile to a CSV line format according to the export configuration.
+     * This method handles the formatting of individual profiles, including:
+     * - Property selection and ordering
+     * - Value formatting
+     * - Multi-value handling
+     * - Line separator management
+     *
+     * @param profile the profile to convert
+     * @param exportConfiguration the configuration specifying the export format
+     * @return a String containing the CSV-formatted profile data

Review Comment:
   Updated `convertProfileToCSVLine` Javadoc: it returns a single row without line separators; callers/routes add separators between rows.



##########
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/route/RouterAbstractRouteBuilder.java:
##########
@@ -28,26 +28,66 @@
 import java.util.Map;
 
 /**
- * Created by amidani on 13/06/2017.
+ * Abstract base class for all Unomi router route builders.
+ * This class provides common functionality and configuration for both import
+ * and export routes, supporting both Kafka and direct endpoint configurations.
+ *
+ * <p>Features:
+ * <ul>
+ *   <li>Common Kafka configuration handling</li>
+ *   <li>Endpoint URI generation for both Kafka and direct modes</li>
+ *   <li>Shared configuration for JSON data format</li>
+ *   <li>Profile service integration</li>
+ *   <li>Endpoint security through allowlist</li>
+ * </ul>
+ * </p>
+ *
+ * @since 1.0
  */
 public abstract class RouterAbstractRouteBuilder extends RouteBuilder {
 
+    /** JSON data format configuration */
     protected JacksonDataFormat jacksonDataFormat;
 
+    /** Kafka broker host */
     protected String kafkaHost;
+
+    /** Kafka broker port */
     protected String kafkaPort;
+
+    /** Topic for import operations */
     protected String kafkaImportTopic;
+
+    /** Topic for export operations */
     protected String kafkaExportTopic;
+
+    /** Consumer group ID for import operations */
     protected String kafkaImportGroupId;
+
+    /** Consumer group ID for export operations */
     protected String kafkaExportGroupId;
+
+    /** Number of Kafka consumers */
     protected String kafkaConsumerCount;
+
+    /** Auto-commit configuration for Kafka */
     protected String kafkaAutoCommit;
 
+    /** Configuration type (kafka/direct) */
     protected String configType;
+
+    /** List of allowed endpoint schemes */
     protected String allowedEndpoints;
 
+    /** Service for profile operations */
     protected ProfileService profileService;
 
+    /**
+     * Constructs a new route builder with Kafka configuration.
+     *
+     * @param kafkaProps map containing Kafka configuration properties
+     * @param configType the type of configuration (kafka/direct)

Review Comment:
   Corrected transport-mode documentation to `kafka` / `nobroker` (`RouterConstants.CONFIG_TYPE_*`), clarifying that in-process `direct:` endpoints are used when `nobroker`, not as a `configType` value.



##########
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/route/ProfileExportCollectRouteBuilder.java:
##########
@@ -31,19 +31,58 @@
 import java.util.Map;
 
 /**
- * Created by amidani on 27/06/2017.
+ * A Camel route builder that handles the collection of profiles for export.
+ * This route builder creates routes that periodically collect profiles based on
+ * segment criteria and prepare them for export processing.
+ *
+ * <p>Features:
+ * <ul>
+ *   <li>Timer-based profile collection</li>
+ *   <li>Segment-based profile filtering</li>
+ *   <li>Support for multiple export configurations</li>
+ *   <li>Configurable collection intervals</li>
+ *   <li>Security through endpoint allowlist</li>
+ *   <li>Support for both Kafka and direct endpoints</li>
+ * </ul>
+ * </p>
+ *
+ * @since 1.0
  */
 public class ProfileExportCollectRouteBuilder extends RouterAbstractRouteBuilder {
 
     private static final Logger LOGGER = LoggerFactory.getLogger(ProfileExportCollectRouteBuilder.class);
 
+    /** List of export configurations to process */
     private List<ExportConfiguration> exportConfigurationList;
+
+    /** Service for persisting and retrieving data */
     private PersistenceService persistenceService;
 
+    /**
+     * Constructs a new route builder with Kafka configuration.
+     *
+     * @param kafkaProps map containing Kafka configuration properties
+     * @param configType the type of configuration (kafka/direct)

Review Comment:
   Same fix as other route builders: constructor/param Javadoc now references `CONFIG_TYPE_KAFKA` / `CONFIG_TYPE_NOBROKER` instead of `kafka/direct`.



##########
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/route/ProfileExportProducerRouteBuilder.java:
##########
@@ -29,24 +29,67 @@
 import java.util.Map;
 
 /**
- * Created by amidani on 28/06/2017.
+ * A Camel route builder that handles the production of export data from collected profiles.
+ * This route builder creates routes that process collected profiles and formats them
+ * for export to the configured destination.
+ *
+ * <p>Features:
+ * <ul>
+ *   <li>Profile data transformation to export format</li>
+ *   <li>Line-by-line processing with aggregation</li>
+ *   <li>Support for multiple export destinations</li>
+ *   <li>Completion handling and status updates</li>
+ *   <li>Support for both Kafka and direct endpoints</li>
+ * </ul>
+ * </p>
+ *
+ * @since 1.0
  */
 public class ProfileExportProducerRouteBuilder extends RouterAbstractRouteBuilder {
 
     private static final Logger LOGGER = LoggerFactory.getLogger(ProfileExportProducerRouteBuilder.class);
 
+    /** Processor for handling export completion */
     private ExportRouteCompletionProcessor exportRouteCompletionProcessor;
 
+    /** Service for profile export operations */
     private ProfileExportService profileExportService;
 
+    /**
+     * Constructs a new route builder with Kafka configuration.
+     *
+     * @param kafkaProps map containing Kafka configuration properties
+     * @param configType the type of configuration (kafka/direct)

Review Comment:
   Same fix — documented `kafka` / `nobroker` transport modes per `RouterConstants`.



##########
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/route/ProfileImportFromSourceRouteBuilder.java:
##########
@@ -37,20 +37,59 @@
 import java.util.Map;
 
 /**
- * Created by amidani on 26/04/2017.
+ * A Camel route builder that handles the import of profiles from configured sources.
+ * This route builder creates routes that process incoming profile data from various
+ * sources and prepares it for import into Unomi.
+ *
+ * <p>Features:
+ * <ul>
+ *   <li>Support for multiple import configurations</li>
+ *   <li>Line-by-line processing of import data</li>
+ *   <li>Error handling and failure reporting</li>
+ *   <li>Configuration validation and status updates</li>
+ *   <li>Support for both Kafka and direct endpoints</li>
+ *   <li>Graceful shutdown handling</li>
+ * </ul>
+ * </p>
+ *
+ * @since 1.0
  */
-
 public class ProfileImportFromSourceRouteBuilder extends RouterAbstractRouteBuilder {
 
     private static final Logger LOGGER = LoggerFactory.getLogger(ProfileImportFromSourceRouteBuilder.class.getName());
 
+    /** List of import configurations to process */
     private List<ImportConfiguration> importConfigurationList;
+
+    /** Service for managing import configurations */
     private ImportExportConfigurationService<ImportConfiguration> importConfigurationService;
 
+    /**
+     * Constructs a new route builder with Kafka configuration.
+     *
+     * @param kafkaProps map containing Kafka configuration properties
+     * @param configType the type of configuration (kafka/direct)

Review Comment:
   Same fix — `configType` Javadoc aligned with `RouterConstants.CONFIG_TYPE_KAFKA` / `CONFIG_TYPE_NOBROKER`.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@unomi.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] UNOMI-888: Javadoc and API cleanup for import/export router extension [unomi]

Posted by "sergehuber (via GitHub)" <gi...@apache.org>.
sergehuber commented on code in PR #756:
URL: https://github.com/apache/unomi/pull/756#discussion_r3254127792


##########
extensions/router/router-api/src/main/java/org/apache/unomi/router/api/ProfileToImport.java:
##########
@@ -22,56 +22,118 @@
 import java.util.List;
 
 /**
- * An extension of {@link Profile} to handle merge strategy and deletion when importing profiles
+ * A specialized Profile class designed for import operations in Apache Unomi.
+ * This class extends the standard {@link Profile} with additional properties and behaviors
+ * specifically needed during the profile import process.
+ *
+ * <p>Key features:
+ * <ul>
+ *   <li>Controls which properties should be overwritten during import</li>
+ *   <li>Specifies the property used for merging with existing profiles</li>
+ *   <li>Handles profile deletion flags</li>
+ *   <li>Controls overwrite behavior for existing profiles</li>
+ * </ul>
+ * </p>
+ *
+ * <p>Usage in Unomi:
+ * <ul>
+ *   <li>Used by import processors to handle profile data</li>
+ *   <li>Consumed by ProfileImportService for import operations</li>
+ *   <li>Supports different import strategies (merge/overwrite/delete)</li>
+ * </ul>
+ * </p>
+ *
+ * @see Profile
+ * @see org.apache.unomi.router.api.services.ProfileImportService
+ * @since 1.0
  */
 public class ProfileToImport extends Profile {
 
+    /** List of property names that should be overwritten during import */
     private List<String> propertiesToOverwrite;
+
+    /** Property used to identify existing profiles for merging */
     private String mergingProperty;
+
+    /** Flag indicating if this profile should be deleted */
     private boolean profileToDelete;
-    private boolean overwriteExistingProfiles;
 
+    /** Flag controlling whether to overwrite existing profile data */
+    private boolean overwriteExistingProfiles;
 
+    /**
+     * Gets the list of properties that should be overwritten during import.
+     * These properties will be updated even if they already exist in the target profile.
+     *
+     * @return list of property names to overwrite
+     */
     public List<String> getPropertiesToOverwrite() {
         return this.propertiesToOverwrite;
     }
 
+    /**
+     * Sets the list of properties that should be overwritten during import.
+     *
+     * @param propertiesToOverwrite list of property names that should be overwritten
+     */
     public void setPropertiesToOverwrite(List<String> propertiesToOverwrite) {
         this.propertiesToOverwrite = propertiesToOverwrite;
     }
 
+    /**
+     * Checks if this profile is marked for deletion.
+     * When true, the matching profile in the system will be deleted rather than updated.
+     *
+     * @return true if the profile should be deleted, false otherwise
+     */
     public boolean isProfileToDelete() {
         return this.profileToDelete;
     }
 
+    /**
+     * Sets whether this profile should be deleted during import.
+     *
+     * @param profileToDelete true to mark the profile for deletion, false otherwise
+     */
     public void setProfileToDelete(boolean profileToDelete) {
         this.profileToDelete = profileToDelete;
     }
 
+    /**
+     * Checks if existing profiles should be overwritten during import.
+     * When true, all properties of existing profiles will be overwritten with imported data.
+     *
+     * @return true if existing profiles should be overwritten, false for selective updates
+     */
     public boolean isOverwriteExistingProfiles() {
         return this.overwriteExistingProfiles;
     }
 
     /**
-     * Sets the overwriteExistingProfiles flag.
-     * @param overwriteExistingProfiles flag used to specify if we want to overwrite existing profiles
+     * Sets whether existing profiles should be completely overwritten during import.
+     *
+     * @param overwriteExistingProfiles true to overwrite all properties, false for selective updates
      */

Review Comment:
   Test reply endpoint



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@unomi.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] UNOMI-888: Javadoc and API cleanup for import/export router extension [unomi]

Posted by "Copilot (via GitHub)" <gi...@apache.org>.
Copilot commented on code in PR #756:
URL: https://github.com/apache/unomi/pull/756#discussion_r3239473181


##########
extensions/router/router-api/src/main/java/org/apache/unomi/router/api/ImportExportConfiguration.java:
##########
@@ -16,15 +16,50 @@
  */
 package org.apache.unomi.router.api;
 
-        import org.apache.unomi.api.Item;
+import org.apache.unomi.api.Item;
 
-        import java.util.ArrayList;
-        import java.util.HashMap;
-        import java.util.List;
-        import java.util.Map;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
 
 /**
- * Created by amidani on 21/06/2017.
+ * Base configuration class for import and export operations in Apache Unomi.
+ * This class serves as the foundation for both ImportConfiguration and ExportConfiguration,
+ * providing common configuration properties and behaviors needed for data transfer operations.
+ *
+ * <p>Key features and responsibilities:
+ * <ul>
+ *   <li>Defines common configuration properties for import/export operations</li>
+ *   <li>Manages separators and delimiters for CSV-like file formats</li>
+ *   <li>Tracks execution status and history</li>
+ *   <li>Handles configuration activation/deactivation</li>
+ * </ul>
+ * </p>
+ *
+ * <p>Usage in Unomi:
+ * <ul>
+ *   <li>Used by ImportExportConfigurationService to manage data transfer configurations</li>
+ *   <li>Consumed by Camel routes to determine how to process data</li>
+ *   <li>Referenced by import/export processors to format data correctly</li>
+ * </ul>
+ * </p>
+ *
+ * <p>Configuration properties include:
+ * <ul>
+ *   <li>name - unique identifier for the configuration</li>

Review Comment:
   This property description is inconsistent with the model: the persisted identifier is `Item#getItemId()` (the router services generate and route by that value), while `name` is only a display name. Calling `name` a unique identifier in the public API docs can lead clients to use the wrong field for load/delete or route IDs.
   



##########
extensions/router/router-api/src/main/java/org/apache/unomi/router/api/ProfileToImport.java:
##########
@@ -22,56 +22,118 @@
 import java.util.List;
 
 /**
- * An extension of {@link Profile} to handle merge strategy and deletion when importing profiles
+ * A specialized Profile class designed for import operations in Apache Unomi.
+ * This class extends the standard {@link Profile} with additional properties and behaviors
+ * specifically needed during the profile import process.
+ *
+ * <p>Key features:
+ * <ul>
+ *   <li>Controls which properties should be overwritten during import</li>
+ *   <li>Specifies the property used for merging with existing profiles</li>
+ *   <li>Handles profile deletion flags</li>
+ *   <li>Controls overwrite behavior for existing profiles</li>
+ * </ul>
+ * </p>
+ *
+ * <p>Usage in Unomi:
+ * <ul>
+ *   <li>Used by import processors to handle profile data</li>
+ *   <li>Consumed by ProfileImportService for import operations</li>
+ *   <li>Supports different import strategies (merge/overwrite/delete)</li>
+ * </ul>
+ * </p>
+ *
+ * @see Profile
+ * @see org.apache.unomi.router.api.services.ProfileImportService
+ * @since 1.0
  */
 public class ProfileToImport extends Profile {
 
+    /** List of property names that should be overwritten during import */
     private List<String> propertiesToOverwrite;
+
+    /** Property used to identify existing profiles for merging */
     private String mergingProperty;
+
+    /** Flag indicating if this profile should be deleted */
     private boolean profileToDelete;
-    private boolean overwriteExistingProfiles;
 
+    /** Flag controlling whether to overwrite existing profile data */
+    private boolean overwriteExistingProfiles;
 
+    /**
+     * Gets the list of properties that should be overwritten during import.
+     * These properties will be updated even if they already exist in the target profile.
+     *
+     * @return list of property names to overwrite
+     */
     public List<String> getPropertiesToOverwrite() {
         return this.propertiesToOverwrite;
     }
 
+    /**
+     * Sets the list of properties that should be overwritten during import.
+     *
+     * @param propertiesToOverwrite list of property names that should be overwritten
+     */
     public void setPropertiesToOverwrite(List<String> propertiesToOverwrite) {
         this.propertiesToOverwrite = propertiesToOverwrite;
     }
 
+    /**
+     * Checks if this profile is marked for deletion.
+     * When true, the matching profile in the system will be deleted rather than updated.
+     *
+     * @return true if the profile should be deleted, false otherwise
+     */
     public boolean isProfileToDelete() {
         return this.profileToDelete;
     }
 
+    /**
+     * Sets whether this profile should be deleted during import.
+     *
+     * @param profileToDelete true to mark the profile for deletion, false otherwise
+     */
     public void setProfileToDelete(boolean profileToDelete) {
         this.profileToDelete = profileToDelete;
     }
 
+    /**
+     * Checks if existing profiles should be overwritten during import.
+     * When true, all properties of existing profiles will be overwritten with imported data.
+     *
+     * @return true if existing profiles should be overwritten, false for selective updates
+     */
     public boolean isOverwriteExistingProfiles() {
         return this.overwriteExistingProfiles;
     }
 
     /**
-     * Sets the overwriteExistingProfiles flag.
-     * @param overwriteExistingProfiles flag used to specify if we want to overwrite existing profiles
+     * Sets whether existing profiles should be completely overwritten during import.
+     *
+     * @param overwriteExistingProfiles true to overwrite all properties, false for selective updates
      */

Review Comment:
   This Javadoc does not match the current merge implementation: ProfileImportServiceImpl only applies `propertiesToOverwrite` when `overwriteExistingProfiles` is true and the list is non-empty; otherwise it replaces the whole properties map. Describing `false` as "selective updates" and `true` as "all properties" will mislead API consumers configuring imports.



##########
extensions/router/router-api/src/main/java/org/apache/unomi/router/api/ImportExportConfiguration.java:
##########
@@ -53,43 +88,49 @@ public void setProperty(String name, Object value) {
     }
 
     /**
-     * Retrieves the name of the import configuration
-     * @return the name of the import configuration
+     * Retrieves the display name of this configuration.
+     *
+     * @return the name of this configuration
      */
     public String getName() { return this.name; }
 
     /**
-     * Sets the name of the import configuration
-     * @param name the name of the import configuration
+     * Sets the display name of this configuration.
+     *
+     * @param name the name of this configuration
      */
     public void setName(String name) {
         this.name = name;
     }
 
     /**
-     * Retrieves the description of the import configuration
-     * @return the description of the import configuration
+     * Retrieves the human-readable description of this configuration.
+     *
+     * @return the description of this configuration
      */
     public String getDescription() { return this.description; }
 
     /**
-     * Sets the description of the import configuration
-     * @param description the description of the import configuration
+     * Sets the human-readable description of this configuration.
+     *
+     * @param description the description of this configuration
      */
     public void setDescription(String description) {
         this.description = description;
     }
 
 
     /**
-     * Retrieves the config type of the import configuration
-     * @return the config type of the import configuration
+     * Retrieves the configuration type (for example import vs export semantics used by the router).
+     *
+     * @return the config type of this configuration
      */
     public String getConfigType() { return this.configType; }
 
     /**
-     * Sets the config type of the import configuration
-     * @param configType the config type of the import configuration
+     * Sets the configuration type.
+     *
+     * @param configType the config type for this configuration
      */

Review Comment:
   This getter/setter Javadoc describes `configType` as import/export semantics, but the router uses this field for scheduling mode (`recurrent`/`oneshot`, see `RouterConstants.IMPORT_EXPORT_CONFIG_TYPE_*` and route builders filtering on `recurrent`). The public Javadoc should not suggest import/export values because those would not activate the expected routes.



##########
extensions/router/router-api/src/main/java/org/apache/unomi/router/api/ImportExportConfiguration.java:
##########
@@ -159,11 +200,12 @@ public String getColumnSeparator() {
     }
 
     /**
-     * Sets the column separator.
-     * @param columnSeparator property used to specify a line separator. Defaults to ','
+     * Sets the column separator used when reading or writing delimited text (typically CSV).
+     *
+     * @param columnSeparator the column delimiter; defaults to {@code ","} when not overridden
      */
     public void setColumnSeparator(String columnSeparator) {
-        if(this.columnSeparator !=null) {
+        if (columnSeparator != null) {

Review Comment:
   The setter still accepts empty or multi-character separators. Imports later use only `columnSeparator.charAt(0)` while exports write the full string, so `""` can fail at runtime and values like `"||"` are parsed and emitted inconsistently. Validate that the separator is exactly one character when accepting a non-null value.
   



##########
extensions/router/router-api/src/main/java/org/apache/unomi/router/api/IRouterCamelContext.java:
##########
@@ -17,15 +17,78 @@
 package org.apache.unomi.router.api;
 
 /**
- * Created by amidani on 18/10/2017.
+ * Facade for the Apache Camel runtime used by the Unomi Router extension.
+ * Implementations manage dynamic routes for profile import (from sources such as Kafka or files)
+ * and profile export (collection and producer pipelines), and expose a minimal API so callers do not
+ * depend on Camel types unless they choose to.
+ *
+ * <p>Key responsibilities:
+ * <ul>
+ *   <li>Removing obsolete Camel route definitions when configurations change or are deleted</li>
+ *   <li>Rebuilding import reader routes after an {@link org.apache.unomi.router.api.ImportConfiguration} update</li>
+ *   <li>Rebuilding export reader routes after an {@link org.apache.unomi.router.api.ExportConfiguration} update</li>
+ *   <li>Optional Camel tracing for troubleshooting route execution</li>
+ * </ul>
+ * </p>
+ *
+ * <p>Typical usage:
+ * <ul>
+ *   <li>Management services call update methods when import/export configuration documents change</li>
+ *   <li>Cleanup paths call {@link #killExistingRoute(String, boolean)} to drop routes whose configs were removed</li>
+ * </ul>
+ * </p>
+ *
+ * @see org.apache.unomi.router.core.context.RouterCamelContext
+ * @since 1.0
  */
 public interface IRouterCamelContext {
 
+    /**
+     * Stops and removes an existing Camel route by id, if it is currently registered in the context.
+     *
+     * @param routeId   Camel route identifier (usually aligned with import/export configuration id)
+     * @param fireEvent when {@code true}, signals that router lifecycle events may be emitted; the concrete
+     *                  implementation defines whether events are fired (reserved hook for observability)
+     * @throws Exception if Camel fails to remove the route definition
+     */
     void killExistingRoute(String routeId, boolean fireEvent) throws Exception;
 
+    /**
+     * Refreshes the profile import reader route for the given configuration: removes any existing route with the
+     * same id, loads the {@link org.apache.unomi.router.api.ImportConfiguration}, and—for recurrent configs—
+     * registers a new route built from current settings.
+     *
+     * @param configId  identifier of the import configuration whose reader route should be updated
+     * @param fireEvent when {@code true}, signals that router lifecycle events may be emitted after the update
+     * @throws Exception if route removal or registration fails
+     */
     void updateProfileImportReaderRoute(String configId, boolean fireEvent) throws Exception;
 
+    /**
+     * Refreshes the profile export reader (collect) route for the given configuration: removes any existing route
+     * with the same id, loads the {@link org.apache.unomi.router.api.ExportConfiguration}, and—for recurrent
+     * configs—registers a new collect route built from current settings.
+     *
+     * @param configId  identifier of the export configuration whose reader route should be updated
+     * @param fireEvent when {@code true}, signals that router lifecycle events may be emitted after the update
+     * @throws Exception if route removal or registration fails
+     */
     void updateProfileExportReaderRoute(String configId, boolean fireEvent) throws Exception;
 
+    /**
+     * Enables or disables Camel route tracing on the underlying {@code CamelContext} for debugging (message flow,
+     * exchanges). Intended for diagnostics in development or incident analysis; may have performance impact when on.
+     *
+     * @param tracing {@code true} to enable Camel tracing, {@code false} to disable
+     */
     void setTracing(boolean tracing);
+
+    /**
+     * Returns the underlying Camel context instance.
+     * The API uses {@link Object} so consumers of this module are not required to depend on Camel at compile time.
+     * Callers that ship Camel may cast to {@code org.apache.camel.CamelContext}.
+     *
+     * @return the Camel context instance, or {@code null} if not initialized
+     */
+    Object getCamelContext();

Review Comment:
   Adding this as a new abstract method to the public router API is source-incompatible for any existing third-party `IRouterCamelContext` implementation; older implementations would also fail if clients call it. If raw Camel access is optional, consider a default method or a separate extension interface so existing providers remain compatible.
   



##########
extensions/router/router-api/src/main/java/org/apache/unomi/router/api/IRouterCamelContext.java:
##########
@@ -17,15 +17,78 @@
 package org.apache.unomi.router.api;
 
 /**
- * Created by amidani on 18/10/2017.
+ * Facade for the Apache Camel runtime used by the Unomi Router extension.
+ * Implementations manage dynamic routes for profile import (from sources such as Kafka or files)
+ * and profile export (collection and producer pipelines), and expose a minimal API so callers do not
+ * depend on Camel types unless they choose to.
+ *
+ * <p>Key responsibilities:
+ * <ul>
+ *   <li>Removing obsolete Camel route definitions when configurations change or are deleted</li>
+ *   <li>Rebuilding import reader routes after an {@link org.apache.unomi.router.api.ImportConfiguration} update</li>
+ *   <li>Rebuilding export reader routes after an {@link org.apache.unomi.router.api.ExportConfiguration} update</li>
+ *   <li>Optional Camel tracing for troubleshooting route execution</li>
+ * </ul>
+ * </p>
+ *
+ * <p>Typical usage:
+ * <ul>
+ *   <li>Management services call update methods when import/export configuration documents change</li>
+ *   <li>Cleanup paths call {@link #killExistingRoute(String, boolean)} to drop routes whose configs were removed</li>
+ * </ul>
+ * </p>
+ *
+ * @see org.apache.unomi.router.core.context.RouterCamelContext

Review Comment:
   This API module does not depend on `router-core`, so this `@see` points at a class that is not on the router-api Javadoc classpath and also creates a reverse reference from the API layer to its implementation module. Prefer keeping the API docs implementation-neutral or linking only types available to router-api.
   



##########
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/route/ProfileExportProducerRouteBuilder.java:
##########
@@ -29,24 +29,67 @@
 import java.util.Map;
 
 /**
- * Created by amidani on 28/06/2017.
+ * A Camel route builder that handles the production of export data from collected profiles.
+ * This route builder creates routes that process collected profiles and formats them
+ * for export to the configured destination.
+ *
+ * <p>Features:
+ * <ul>
+ *   <li>Profile data transformation to export format</li>
+ *   <li>Line-by-line processing with aggregation</li>
+ *   <li>Support for multiple export destinations</li>
+ *   <li>Completion handling and status updates</li>
+ *   <li>Support for both Kafka and direct endpoints</li>
+ * </ul>
+ * </p>
+ *
+ * @since 1.0
  */
 public class ProfileExportProducerRouteBuilder extends RouterAbstractRouteBuilder {
 
     private static final Logger LOGGER = LoggerFactory.getLogger(ProfileExportProducerRouteBuilder.class);
 
+    /** Processor for handling export completion */
     private ExportRouteCompletionProcessor exportRouteCompletionProcessor;
 
+    /** Service for profile export operations */
     private ProfileExportService profileExportService;
 
+    /**
+     * Constructs a new route builder with Kafka configuration.
+     *
+     * @param kafkaProps map containing Kafka configuration properties
+     * @param configType the type of configuration (kafka/direct)

Review Comment:
   The documented values for this router `configType` do not match the code/configuration constants: the supported configuration values are `kafka` and `nobroker`; `direct` is only the endpoint style used when not in Kafka mode. Please document the actual values to avoid misconfiguration.
   



##########
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/route/RouterAbstractRouteBuilder.java:
##########
@@ -28,26 +28,66 @@
 import java.util.Map;
 
 /**
- * Created by amidani on 13/06/2017.
+ * Abstract base class for all Unomi router route builders.
+ * This class provides common functionality and configuration for both import
+ * and export routes, supporting both Kafka and direct endpoint configurations.
+ *
+ * <p>Features:
+ * <ul>
+ *   <li>Common Kafka configuration handling</li>
+ *   <li>Endpoint URI generation for both Kafka and direct modes</li>
+ *   <li>Shared configuration for JSON data format</li>
+ *   <li>Profile service integration</li>
+ *   <li>Endpoint security through allowlist</li>
+ * </ul>
+ * </p>
+ *
+ * @since 1.0
  */
 public abstract class RouterAbstractRouteBuilder extends RouteBuilder {
 
+    /** JSON data format configuration */
     protected JacksonDataFormat jacksonDataFormat;
 
+    /** Kafka broker host */
     protected String kafkaHost;
+
+    /** Kafka broker port */
     protected String kafkaPort;
+
+    /** Topic for import operations */
     protected String kafkaImportTopic;
+
+    /** Topic for export operations */
     protected String kafkaExportTopic;
+
+    /** Consumer group ID for import operations */
     protected String kafkaImportGroupId;
+
+    /** Consumer group ID for export operations */
     protected String kafkaExportGroupId;
+
+    /** Number of Kafka consumers */
     protected String kafkaConsumerCount;
+
+    /** Auto-commit configuration for Kafka */
     protected String kafkaAutoCommit;
 
+    /** Configuration type (kafka/direct) */
     protected String configType;
+
+    /** List of allowed endpoint schemes */
     protected String allowedEndpoints;
 
+    /** Service for profile operations */
     protected ProfileService profileService;
 
+    /**
+     * Constructs a new route builder with Kafka configuration.
+     *
+     * @param kafkaProps map containing Kafka configuration properties
+     * @param configType the type of configuration (kafka/direct)

Review Comment:
   The documented values for this router `configType` do not match the code/configuration constants: the supported configuration values are `kafka` and `nobroker` (`RouterConstants.CONFIG_TYPE_*` and `org.apache.unomi.router.cfg`), while `direct` is only the endpoint style used when not in Kafka mode. Please document the actual values to avoid misconfiguration.



##########
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/route/ProfileExportCollectRouteBuilder.java:
##########
@@ -31,19 +31,58 @@
 import java.util.Map;
 
 /**
- * Created by amidani on 27/06/2017.
+ * A Camel route builder that handles the collection of profiles for export.
+ * This route builder creates routes that periodically collect profiles based on
+ * segment criteria and prepare them for export processing.
+ *
+ * <p>Features:
+ * <ul>
+ *   <li>Timer-based profile collection</li>
+ *   <li>Segment-based profile filtering</li>
+ *   <li>Support for multiple export configurations</li>
+ *   <li>Configurable collection intervals</li>
+ *   <li>Security through endpoint allowlist</li>
+ *   <li>Support for both Kafka and direct endpoints</li>
+ * </ul>
+ * </p>
+ *
+ * @since 1.0
  */
 public class ProfileExportCollectRouteBuilder extends RouterAbstractRouteBuilder {
 
     private static final Logger LOGGER = LoggerFactory.getLogger(ProfileExportCollectRouteBuilder.class);
 
+    /** List of export configurations to process */
     private List<ExportConfiguration> exportConfigurationList;
+
+    /** Service for persisting and retrieving data */
     private PersistenceService persistenceService;
 
+    /**
+     * Constructs a new route builder with Kafka configuration.
+     *
+     * @param kafkaProps map containing Kafka configuration properties
+     * @param configType the type of configuration (kafka/direct)

Review Comment:
   The documented values for this router `configType` do not match the code/configuration constants: the supported configuration values are `kafka` and `nobroker`; `direct` is only the endpoint style used when not in Kafka mode. Please document the actual values to avoid misconfiguration.
   



##########
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/processor/ImportRouteCompletionProcessor.java:
##########
@@ -26,15 +26,51 @@
 import java.util.*;
 
 /**
- * Created by amidani on 14/06/2017.
+ * A Camel processor that handles the completion of profile import routes.
+ * This processor manages the final stage of import operations, collecting statistics,
+ * handling errors, and updating the import configuration with execution results.
+ *
+ * <p>The processor performs the following operations:
+ * <ul>
+ *   <li>Collects import statistics (success, failure, ignore counts)</li>
+ *   <li>Manages error reporting with configurable limits</li>

Review Comment:
   This says the processor collects ignore counts, but `ignoreCount` is only incremented locally and is never written to the execution record or status. Either document only the persisted statistics or include the ignore count in the execution data so the Javadoc matches behavior.



##########
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/route/ProfileImportOneShotRouteBuilder.java:
##########
@@ -30,18 +30,59 @@
 import java.util.Map;
 
 /**
- * Created by amidani on 22/05/2017.
+ * A Camel route builder that handles one-time profile imports from files.
+ * This route builder creates routes that process CSV files dropped into a
+ * monitored directory for one-time import operations.
+ *
+ * <p>Features:
+ * <ul>
+ *   <li>File-based import processing</li>
+ *   <li>Configuration lookup from filename</li>
+ *   <li>CSV file processing with error handling</li>
+ *   <li>Support for both Kafka and direct endpoints</li>
+ *   <li>Automatic file movement after processing</li>
+ *   <li>Error reporting and failed file handling</li>
+ * </ul>
+ * </p>
+ *
+ * @since 1.0
  */
 public class ProfileImportOneShotRouteBuilder extends RouterAbstractRouteBuilder {
 
     private static final Logger LOGGER = LoggerFactory.getLogger(ProfileImportOneShotRouteBuilder.class.getName());
+
+    /** Processor for extracting import configuration from filenames */
     private ImportConfigByFileNameProcessor importConfigByFileNameProcessor;
+
+    /** Directory to monitor for import files */
     private String uploadDir;
 
+    /**
+     * Constructs a new route builder with Kafka configuration.
+     *
+     * @param kafkaProps map containing Kafka configuration properties
+     * @param configType the type of configuration (kafka/direct)

Review Comment:
   The documented values for this router `configType` do not match the code/configuration constants: the supported configuration values are `kafka` and `nobroker`; `direct` is only the endpoint style used when not in Kafka mode. Please document the actual values to avoid misconfiguration.
   



##########
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/bean/CollectProfileBean.java:
##########
@@ -22,17 +22,43 @@
 import java.util.List;
 
 /**
- * Created by amidani on 28/06/2017.
+ * A bean that handles the collection of profiles based on segment criteria.
+ * This class provides functionality to extract profiles from Unomi's persistence
+ * layer based on segment membership.
+ *
+ * <p>Features:
+ * <ul>
+ *   <li>Segment-based profile extraction</li>
+ *   <li>Integration with Unomi's persistence service</li>
+ *   <li>Batch profile retrieval capabilities</li>

Review Comment:
   This feature list says the bean has batch retrieval capabilities, but the only method delegates to `persistenceService.query(...)` and the new note below explicitly says it may load a large result set into memory. Calling this batch-capable overstates the implementation and can mislead callers about its scalability.
   



##########
extensions/router/router-api/src/main/java/org/apache/unomi/router/api/services/ProfileImportService.java:
##########
@@ -21,9 +21,54 @@
 import java.lang.reflect.InvocationTargetException;
 
 /**
- * Created by amidani on 20/05/2017.
+ * Service interface for handling the import of individual profiles into Apache Unomi.
+ * This service is responsible for the actual processing and storage of imported profile data,
+ * including merging with existing profiles or creating new ones as needed.
+ *
+ * <p>Key responsibilities:
+ * <ul>
+ *   <li>Processing individual profile imports</li>
+ *   <li>Merging imported data with existing profiles</li>
+ *   <li>Handling profile creation for new imports</li>
+ *   <li>Managing profile deletion when specified</li>
+ * </ul>
+ * </p>
+ *
+ * <p>Usage in Unomi:
+ * <ul>
+ *   <li>Called by import route processors to handle individual profile data</li>
+ *   <li>Used during batch import operations</li>
+ *   <li>Integrated with Unomi's profile management system</li>
+ * </ul>
+ * </p>
+ *
+ * <p>Implementation considerations:
+ * <ul>
+ *   <li>Must handle profile merging strategies</li>
+ *   <li>Should implement proper error handling</li>
+ *   <li>Must maintain data consistency</li>
+ *   <li>Should handle property type conversions</li>
+ * </ul>

Review Comment:
   Property type conversion is performed before this service is called (for example by `LineSplitProcessor` when building `ProfileToImport`); the current service implementation only merges/deletes/saves the prepared profile. Listing type conversion as an implementation responsibility for this interface can lead duplicate or inconsistent conversion logic in service implementations.



##########
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/context/RouterCamelContext.java:
##########
@@ -49,7 +49,25 @@
 import java.util.concurrent.TimeUnit;
 
 /**
- * Created by amidani on 04/05/2017.
+ * The main Camel context manager for the Unomi Router component.
+ * This class manages the lifecycle of all import and export routes,
+ * handles route configuration updates, and maintains the Camel context.
+ *
+ * <p>Features:
+ * <ul>
+ *   <li>Initializes and manages the Camel context</li>
+ *   <li>Sets up import and export routes</li>
+ *   <li>Handles route configuration updates</li>
+ *   <li>Manages route lifecycle (start/stop/update)</li>
+ *   <li>Provides monitoring through event notifications</li>

Review Comment:
   The class does not currently publish any router event notifications; `fireEvent` is unused and the event constants are only reserved. Advertising monitoring through event notifications in the feature list overstates the actual behavior.
   



##########
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/context/RouterCamelContext.java:
##########
@@ -79,8 +97,11 @@ public class RouterCamelContext implements IRouterCamelContext {
     private Integer configsRefreshInterval = 1000;
     private ScheduledFuture<?> scheduledFuture;
 
+    /** Event topic fired when a router configuration or route is removed (reserved for integrations). */

Review Comment:
   This topic is described as fired when routes/configurations are removed, but the current implementation never publishes an event for it (the `fireEvent` parameter is ignored). Please either document it as reserved/unused or implement the event emission.
   



##########
extensions/router/router-api/src/main/java/org/apache/unomi/router/api/services/ProfileExportService.java:
##########
@@ -23,12 +23,67 @@
 import java.util.Collection;
 
 /**
- * Created by amidani on 30/06/2017.
+ * Service interface for handling the export of profiles from Apache Unomi.
+ * This service is responsible for extracting profiles based on segment criteria
+ * and converting them into the appropriate export format (e.g., CSV).
+ *
+ * <p>Key responsibilities:
+ * <ul>
+ *   <li>Extracting profiles based on segment criteria</li>
+ *   <li>Converting profiles to export format</li>
+ *   <li>Handling data formatting and transformation</li>
+ *   <li>Managing export file generation</li>
+ * </ul>
+ * </p>
+ *
+ * <p>Usage in Unomi:
+ * <ul>
+ *   <li>Called by export route processors to handle profile extraction</li>
+ *   <li>Used during scheduled export operations</li>
+ *   <li>Integrated with Unomi's segmentation system</li>
+ * </ul>
+ * </p>
+ *
+ * <p>Implementation considerations:
+ * <ul>
+ *   <li>Must handle large data sets efficiently</li>
+ *   <li>Should implement proper error handling</li>
+ *   <li>Must respect profile property formatting</li>
+ *   <li>Should handle multi-valued properties</li>
+ * </ul>
+ * </p>
+ *
+ * @see Profile
+ * @see ExportConfiguration
+ * @see PropertyType
+ * @since 1.0
  */
 public interface ProfileExportService {
 
+    /**
+     * Extracts profiles belonging to a specified segment and formats them for export.
+     * This method handles the bulk export operation, including:
+     * - Querying profiles based on segment criteria
+     * - Formatting profiles according to export configuration
+     * - Generating the export content
+     *
+     * @param exportConfiguration the configuration specifying export parameters and format

Review Comment:
   The current implementation of `extractProfilesBySegment` also records an execution entry and saves the export configuration, but this public method Javadoc describes it as a pure extract/format operation. Please document the persistence side effect so callers are not surprised by invoking an export read updating configuration history.
   



##########
extensions/router/router-api/src/main/java/org/apache/unomi/router/api/services/ProfileExportService.java:
##########
@@ -23,12 +23,67 @@
 import java.util.Collection;
 
 /**
- * Created by amidani on 30/06/2017.
+ * Service interface for handling the export of profiles from Apache Unomi.
+ * This service is responsible for extracting profiles based on segment criteria
+ * and converting them into the appropriate export format (e.g., CSV).
+ *
+ * <p>Key responsibilities:
+ * <ul>
+ *   <li>Extracting profiles based on segment criteria</li>
+ *   <li>Converting profiles to export format</li>
+ *   <li>Handling data formatting and transformation</li>
+ *   <li>Managing export file generation</li>
+ * </ul>
+ * </p>
+ *
+ * <p>Usage in Unomi:
+ * <ul>
+ *   <li>Called by export route processors to handle profile extraction</li>
+ *   <li>Used during scheduled export operations</li>
+ *   <li>Integrated with Unomi's segmentation system</li>
+ * </ul>
+ * </p>
+ *
+ * <p>Implementation considerations:
+ * <ul>
+ *   <li>Must handle large data sets efficiently</li>
+ *   <li>Should implement proper error handling</li>
+ *   <li>Must respect profile property formatting</li>
+ *   <li>Should handle multi-valued properties</li>
+ * </ul>
+ * </p>
+ *
+ * @see Profile
+ * @see ExportConfiguration
+ * @see PropertyType
+ * @since 1.0
  */
 public interface ProfileExportService {
 
+    /**
+     * Extracts profiles belonging to a specified segment and formats them for export.
+     * This method handles the bulk export operation, including:
+     * - Querying profiles based on segment criteria
+     * - Formatting profiles according to export configuration
+     * - Generating the export content
+     *
+     * @param exportConfiguration the configuration specifying export parameters and format
+     * @return a String containing the formatted export data
+     */
     String extractProfilesBySegment(ExportConfiguration exportConfiguration);
 
+    /**
+     * Converts a single profile to a CSV line format according to the export configuration.
+     * This method handles the formatting of individual profiles, including:
+     * - Property selection and ordering
+     * - Value formatting
+     * - Multi-value handling
+     * - Line separator management
+     *
+     * @param profile the profile to convert
+     * @param exportConfiguration the configuration specifying the export format
+     * @return a String containing the CSV-formatted profile data

Review Comment:
   `convertProfileToCSVLine` does not manage line separators; the current implementation returns a single row and the export route/aggregation adds separators between rows. Keeping this bullet in the public API docs can make implementers add separators here and produce double-separated output.
   



##########
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/route/ProfileImportFromSourceRouteBuilder.java:
##########
@@ -37,20 +37,59 @@
 import java.util.Map;
 
 /**
- * Created by amidani on 26/04/2017.
+ * A Camel route builder that handles the import of profiles from configured sources.
+ * This route builder creates routes that process incoming profile data from various
+ * sources and prepares it for import into Unomi.
+ *
+ * <p>Features:
+ * <ul>
+ *   <li>Support for multiple import configurations</li>
+ *   <li>Line-by-line processing of import data</li>
+ *   <li>Error handling and failure reporting</li>
+ *   <li>Configuration validation and status updates</li>
+ *   <li>Support for both Kafka and direct endpoints</li>
+ *   <li>Graceful shutdown handling</li>
+ * </ul>
+ * </p>
+ *
+ * @since 1.0
  */
-
 public class ProfileImportFromSourceRouteBuilder extends RouterAbstractRouteBuilder {
 
     private static final Logger LOGGER = LoggerFactory.getLogger(ProfileImportFromSourceRouteBuilder.class.getName());
 
+    /** List of import configurations to process */
     private List<ImportConfiguration> importConfigurationList;
+
+    /** Service for managing import configurations */
     private ImportExportConfigurationService<ImportConfiguration> importConfigurationService;
 
+    /**
+     * Constructs a new route builder with Kafka configuration.
+     *
+     * @param kafkaProps map containing Kafka configuration properties
+     * @param configType the type of configuration (kafka/direct)

Review Comment:
   The documented values for this router `configType` do not match the code/configuration constants: the supported configuration values are `kafka` and `nobroker`; `direct` is only the endpoint style used when not in Kafka mode. Please document the actual values to avoid misconfiguration.
   



##########
extensions/router/router-core/src/main/java/org/apache/unomi/router/core/route/ProfileImportToUnomiRouteBuilder.java:
##########
@@ -29,19 +29,56 @@
 import java.util.Map;
 
 /**
- * Created by amidani on 26/04/2017.
+ * A Camel route builder that handles the final stage of profile imports by storing
+ * processed profile data into Apache Unomi's storage system.
+ *
+ * <p>Features:
+ * <ul>
+ *   <li>Final processing of imported profiles</li>
+ *   <li>Integration with Unomi's storage system</li>
+ *   <li>Support for both Kafka and direct endpoints</li>
+ *   <li>Import completion handling</li>
+ *   <li>Error handling and reporting</li>
+ * </ul>
+ * </p>
+ *
+ * @since 1.0
  */
 public class ProfileImportToUnomiRouteBuilder extends RouterAbstractRouteBuilder {
 
     private static final Logger LOGGER = LoggerFactory.getLogger(ProfileImportToUnomiRouteBuilder.class.getName());
 
+    /** Processor for storing profiles in Unomi */
     private UnomiStorageProcessor unomiStorageProcessor;
+
+    /** Processor for handling import completion */
     private ImportRouteCompletionProcessor importRouteCompletionProcessor;
 
+    /**
+     * Constructs a new route builder with Kafka configuration.
+     *
+     * @param kafkaProps map containing Kafka configuration properties
+     * @param configType the type of configuration (kafka/direct)

Review Comment:
   The documented values for this router `configType` do not match the code/configuration constants: the supported configuration values are `kafka` and `nobroker`; `direct` is only the endpoint style used when not in Kafka mode. Please document the actual values to avoid misconfiguration.
   



##########
extensions/router/router-api/src/main/java/org/apache/unomi/router/api/exceptions/BadProfileDataFormatException.java:
##########
@@ -17,18 +17,57 @@
 package org.apache.unomi.router.api.exceptions;
 
 /**
- * Created by amidani on 13/06/2017.
+ * Exception thrown when profile data cannot be properly parsed or formatted during import/export operations.
+ * This exception indicates issues with the structure or content of profile data that prevent it from being
+ * properly processed by the Unomi router.
+ *
+ * <p>Common scenarios where this exception is thrown:
+ * <ul>
+ *   <li>Invalid CSV format in import files</li>
+ *   <li>Missing required profile fields</li>
+ *   <li>Incorrect data types for profile properties</li>
+ *   <li>Malformed multi-value fields</li>
+ *   <li>Invalid date formats</li>

Review Comment:
   This scenario is not currently detected by the import processor: date properties are handled in the same branch as strings and are not parsed or format-validated before being stored. Listing invalid date formats as a reason for this exception will mislead users about the validation they can expect.
   



##########
extensions/router/router-api/src/main/java/org/apache/unomi/router/api/exceptions/BadProfileDataFormatException.java:
##########
@@ -17,18 +17,57 @@
 package org.apache.unomi.router.api.exceptions;
 
 /**
- * Created by amidani on 13/06/2017.
+ * Exception thrown when profile data cannot be properly parsed or formatted during import/export operations.
+ * This exception indicates issues with the structure or content of profile data that prevent it from being
+ * properly processed by the Unomi router.

Review Comment:
   This exception is only thrown from import line processing and handled by import routes; the export path does not throw or catch it. Describing it as an import/export exception overstates its scope in the public API docs.
   



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@unomi.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] UNOMI-888: Javadoc and API cleanup for import/export router extension [unomi]

Posted by "sergehuber (via GitHub)" <gi...@apache.org>.
sergehuber commented on code in PR #756:
URL: https://github.com/apache/unomi/pull/756#discussion_r3254127792


##########
extensions/router/router-api/src/main/java/org/apache/unomi/router/api/ProfileToImport.java:
##########
@@ -22,56 +22,118 @@
 import java.util.List;
 
 /**
- * An extension of {@link Profile} to handle merge strategy and deletion when importing profiles
+ * A specialized Profile class designed for import operations in Apache Unomi.
+ * This class extends the standard {@link Profile} with additional properties and behaviors
+ * specifically needed during the profile import process.
+ *
+ * <p>Key features:
+ * <ul>
+ *   <li>Controls which properties should be overwritten during import</li>
+ *   <li>Specifies the property used for merging with existing profiles</li>
+ *   <li>Handles profile deletion flags</li>
+ *   <li>Controls overwrite behavior for existing profiles</li>
+ * </ul>
+ * </p>
+ *
+ * <p>Usage in Unomi:
+ * <ul>
+ *   <li>Used by import processors to handle profile data</li>
+ *   <li>Consumed by ProfileImportService for import operations</li>
+ *   <li>Supports different import strategies (merge/overwrite/delete)</li>
+ * </ul>
+ * </p>
+ *
+ * @see Profile
+ * @see org.apache.unomi.router.api.services.ProfileImportService
+ * @since 1.0
  */
 public class ProfileToImport extends Profile {
 
+    /** List of property names that should be overwritten during import */
     private List<String> propertiesToOverwrite;
+
+    /** Property used to identify existing profiles for merging */
     private String mergingProperty;
+
+    /** Flag indicating if this profile should be deleted */
     private boolean profileToDelete;
-    private boolean overwriteExistingProfiles;
 
+    /** Flag controlling whether to overwrite existing profile data */
+    private boolean overwriteExistingProfiles;
 
+    /**
+     * Gets the list of properties that should be overwritten during import.
+     * These properties will be updated even if they already exist in the target profile.
+     *
+     * @return list of property names to overwrite
+     */
     public List<String> getPropertiesToOverwrite() {
         return this.propertiesToOverwrite;
     }
 
+    /**
+     * Sets the list of properties that should be overwritten during import.
+     *
+     * @param propertiesToOverwrite list of property names that should be overwritten
+     */
     public void setPropertiesToOverwrite(List<String> propertiesToOverwrite) {
         this.propertiesToOverwrite = propertiesToOverwrite;
     }
 
+    /**
+     * Checks if this profile is marked for deletion.
+     * When true, the matching profile in the system will be deleted rather than updated.
+     *
+     * @return true if the profile should be deleted, false otherwise
+     */
     public boolean isProfileToDelete() {
         return this.profileToDelete;
     }
 
+    /**
+     * Sets whether this profile should be deleted during import.
+     *
+     * @param profileToDelete true to mark the profile for deletion, false otherwise
+     */
     public void setProfileToDelete(boolean profileToDelete) {
         this.profileToDelete = profileToDelete;
     }
 
+    /**
+     * Checks if existing profiles should be overwritten during import.
+     * When true, all properties of existing profiles will be overwritten with imported data.
+     *
+     * @return true if existing profiles should be overwritten, false for selective updates
+     */
     public boolean isOverwriteExistingProfiles() {
         return this.overwriteExistingProfiles;
     }
 
     /**
-     * Sets the overwriteExistingProfiles flag.
-     * @param overwriteExistingProfiles flag used to specify if we want to overwrite existing profiles
+     * Sets whether existing profiles should be completely overwritten during import.
+     *
+     * @param overwriteExistingProfiles true to overwrite all properties, false for selective updates
      */

Review Comment:
   Test reply endpoint



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@unomi.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org