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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
