UNOMI-888: Javadoc and API cleanup for import/export router extension

extensions/router/router-api/src/main/java/org/apache/unomi/router/api/IRouterCamelContext.java

@@ -17,15 +17,79 @@
 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>
+ *
+ * @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 or not exposed
+     */
+    default Object getCamelContext() {
+        return null;
+    }
 }

extensions/router/router-api/src/main/java/org/apache/unomi/router/api/ImportExportConfiguration.java

@@ -16,15 +16,52 @@
  */
 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>itemId - persisted identifier used by router services and routes ({@link Item#getItemId()})</li>
+ *   <li>name - human-readable display name (not used as the route or persistence key)</li>
+ *   <li>configType - scheduling mode ({@link RouterConstants#IMPORT_EXPORT_CONFIG_TYPE_RECURRENT} or
+ *       {@link RouterConstants#IMPORT_EXPORT_CONFIG_TYPE_ONESHOT})</li>
+ *   <li>columnSeparator - character used to separate columns (default: ",")</li>
+ *   <li>lineSeparator - character used to separate lines (default: "\n")</li>
+ *   <li>multiValueSeparator - character used to separate multiple values (default: ";")</li>
+ *   <li>active - whether the configuration is currently active</li>
+ *   <li>status - current status of the configuration</li>
+ *   <li>executions - history of execution attempts</li>
+ * </ul>
+ * </p>
+ *
+ * @see org.apache.unomi.router.api.services.ImportExportConfigurationService
+ * @since 1.0
  */
 public class ImportExportConfiguration extends Item {
 
@@ -53,43 +90,51 @@ 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
+     * Returns the scheduling mode for this configuration ({@code recurrent} or {@code oneshot}).
+     *
+     * @return {@link RouterConstants#IMPORT_EXPORT_CONFIG_TYPE_RECURRENT} or
+     *         {@link RouterConstants#IMPORT_EXPORT_CONFIG_TYPE_ONESHOT}
      */
     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 scheduling mode for this configuration.
+     *
+     * @param configType {@link RouterConstants#IMPORT_EXPORT_CONFIG_TYPE_RECURRENT} or
+     *                   {@link RouterConstants#IMPORT_EXPORT_CONFIG_TYPE_ONESHOT}
      */
     public void setConfigType(String configType) {
         this.configType = configType;
@@ -106,45 +151,45 @@ public Object getProperty(String name) {
     }
 
     /**
-     * Retrieves a Map of all property name - value pairs for this import configuration.
+     * Retrieves a map of all property name/value pairs for this configuration.
      *
-     * @return a Map of all property name - value pairs for this import configuration
+     * @return a map of all property name/value pairs for this configuration
      */
     public Map<String, Object> getProperties() {
         return properties;
     }
 
     /**
-     * Retrieves the import configuration active flag.
+     * Returns whether this configuration is active (eligible for scheduled or triggered runs).
      *
-     * @return true if the import configuration is active false if not
+     * @return {@code true} if this configuration is active, {@code false} otherwise
      */
     public boolean isActive() {
         return this.active;
     }
 
     /**
-     * Sets the active flag true/false.
+     * Sets whether this configuration is active.
      *
-     * @param active a boolean to set to active or inactive the import configuration
+     * @param active {@code true} to activate, {@code false} to deactivate
      */
     public void setActive(boolean active) {
         this.active = active;
     }
 
     /**
-     * Retrieves the import configuration status for last execution.
+     * Retrieves the status of the last execution for this configuration.
      *
-     * @return status of the last execution
+     * @return status of the last execution, or {@code null} if none
      */
     public String getStatus() {
         return this.status;
     }
 
     /**
-     * Sets status of the last execution.
+     * Sets the status of the last execution for this configuration.
      *
-     * @param status of the last execution
+     * @param status the status of the last execution
      */
     public void setStatus(String status) {
         this.status = status;
@@ -159,11 +204,16 @@ 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; must be exactly one character when non-null
+     * @throws IllegalArgumentException if {@code columnSeparator} is empty or longer than one character
      */
     public void setColumnSeparator(String columnSeparator) {
-        if(this.columnSeparator !=null) {
+        if (columnSeparator != null) {
+            if (columnSeparator.length() != 1) {
+                throw new IllegalArgumentException("columnSeparator must be exactly one character");
+            }
             this.columnSeparator = columnSeparator;
         }
     }
@@ -187,9 +237,9 @@ public void setLineSeparator(String lineSeparator) {
     }
 
     /**
-     * Gets the multi value separator.
+     * Returns the separator used between multiple values within a single field.
      *
-     * @return  multiValueSeparator multi value separator
+     * @return the multi-value separator (often {@code ";"})
      */
     public String getMultiValueSeparator() {
         return this.multiValueSeparator;
@@ -206,9 +256,9 @@ public void setMultiValueSeparator(String multiValueSeparator) {
     }
 
     /**
-     * Gets the multi value delimiter.
+     * Returns the delimiter wrapping multi-valued fields when serialized.
      *
-     * @return multiValueDelimiter multi value delimiter
+     * @return the multi-value delimiter (may be empty when not used)
      */
     public String getMultiValueDelimiter() {
         return this.multiValueDelimiter;
@@ -225,17 +275,19 @@ public void setMultiValueDelimiter(String multiValueDelimiter) {
     }
 
     /**
-     * Retrieves the executions
-     * @return executions
+     * Returns the history of execution records for this configuration (timestamps, counts, errors, etc.).
+     *
+     * @return the list of execution maps; may be empty
      */
     public List<Map<String, Object>> getExecutions() {
         return this.executions;
     }
 
 
     /**
-     * Sets the executions
-     * @param executions executions
+     * Replaces the execution history for this configuration.
+     *
+     * @param executions the new execution history list
      */
     public void setExecutions(List<Map<String, Object>> executions) {
         this.executions = executions;