UNOMI-888: Javadoc and API cleanup for import/export router extension by sergehuber · Pull Request #756 · apache/unomi

sergehuber · 2026-05-06T09:21:09Z

Stacked PR (merge order)

Role	Branch
Base (merge into)	`UNOMI-879-unified-crud-shell`
Head (this PR)	`UNOMI-888-import-export-javadoc`

This PR is stacked: merge into UNOMI-879-unified-crud-shell first (after #755 is merged there, or once that line is rebased).

Summary

JIRA: 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

Local build successful
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).

@OverRide

Add and expand Javadoc across router-api and router-core: IRouterCamelContext facade, ImportExportConfiguration and services, ProfileToImport, route builders, processors, aggregation strategies, and related exceptions. Also include small behavioral and API fixes discovered during documentation: - IRouterCamelContext: document methods and add getCamelContext() returning Object to avoid a compile-time Camel dependency for API consumers - RouterCamelContext: honor setTracing(boolean) (previously always enabled tracing); add @OverRide and {@inheritdoc} for interface methods - ImportExportConfiguration: fix setColumnSeparator to null-check the parameter, consistent with setLineSeparator - LineSplitFailureHandler: add @OverRide on process(Exchange) Replaces placeholder 'Created by' class comments with module-oriented descriptions.

Copilot

Pull request overview

This PR expands Javadoc across the router import/export API and core implementation while making a few small API/behavior adjustments around Camel context access, tracing, and separator handling.

Changes:

Replaces placeholder comments with detailed Javadoc for router APIs, processors, route builders, aggregation strategies, and beans.
Adds IRouterCamelContext#getCamelContext() and updates RouterCamelContext accordingly.
Fixes RouterCamelContext#setTracing(boolean) to honor its argument and updates ImportExportConfiguration#setColumnSeparator null handling.

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 21 comments.

Show a summary per file

File	Description
`extensions/router/router-core/src/main/java/org/apache/unomi/router/core/strategy/StringLinesAggregationStrategy.java`	Documents string aggregation behavior for export lines.
`extensions/router/router-core/src/main/java/org/apache/unomi/router/core/strategy/ArrayListAggregationStrategy.java`	Documents list aggregation behavior for import results.
`extensions/router/router-core/src/main/java/org/apache/unomi/router/core/route/RouterAbstractRouteBuilder.java`	Documents shared router route-builder configuration and endpoint creation.
`extensions/router/router-core/src/main/java/org/apache/unomi/router/core/route/ProfileImportToUnomiRouteBuilder.java`	Documents final import-to-storage route setup.
`extensions/router/router-core/src/main/java/org/apache/unomi/router/core/route/ProfileImportOneShotRouteBuilder.java`	Documents one-shot file import route setup.
`extensions/router/router-core/src/main/java/org/apache/unomi/router/core/route/ProfileImportFromSourceRouteBuilder.java`	Documents recurrent import source route setup.
`extensions/router/router-core/src/main/java/org/apache/unomi/router/core/route/ProfileExportProducerRouteBuilder.java`	Documents export producer route setup.
`extensions/router/router-core/src/main/java/org/apache/unomi/router/core/route/ProfileExportCollectRouteBuilder.java`	Documents export collection route setup.
`extensions/router/router-core/src/main/java/org/apache/unomi/router/core/processor/UnomiStorageProcessor.java`	Documents imported profile persistence processing.
`extensions/router/router-core/src/main/java/org/apache/unomi/router/core/processor/LineSplitProcessor.java`	Documents CSV line parsing into profiles.
`extensions/router/router-core/src/main/java/org/apache/unomi/router/core/processor/LineSplitFailureHandler.java`	Documents import line failure handling and adds `@Override`.
`extensions/router/router-core/src/main/java/org/apache/unomi/router/core/processor/LineBuildProcessor.java`	Documents profile-to-CSV-line processing.
`extensions/router/router-core/src/main/java/org/apache/unomi/router/core/processor/ImportRouteCompletionProcessor.java`	Documents import completion statistics and status updates.
`extensions/router/router-core/src/main/java/org/apache/unomi/router/core/processor/ImportConfigByFileNameProcessor.java`	Documents one-shot config lookup by filename.
`extensions/router/router-core/src/main/java/org/apache/unomi/router/core/processor/ExportRouteCompletionProcessor.java`	Documents export completion status/history updates.
`extensions/router/router-core/src/main/java/org/apache/unomi/router/core/context/RouterCamelContext.java`	Documents router Camel context lifecycle and updates tracing/context API implementation.
`extensions/router/router-core/src/main/java/org/apache/unomi/router/core/bean/CollectProfileBean.java`	Documents segment-based profile collection.
`extensions/router/router-api/src/main/java/org/apache/unomi/router/api/services/ProfileImportService.java`	Documents profile import service responsibilities.
`extensions/router/router-api/src/main/java/org/apache/unomi/router/api/services/ProfileExportService.java`	Documents profile export service responsibilities.
`extensions/router/router-api/src/main/java/org/apache/unomi/router/api/services/ImportExportConfigurationService.java`	Documents import/export configuration service operations.
`extensions/router/router-api/src/main/java/org/apache/unomi/router/api/ProfileToImport.java`	Documents import-specific profile fields and merge/delete flags.
`extensions/router/router-api/src/main/java/org/apache/unomi/router/api/IRouterCamelContext.java`	Documents router Camel facade and adds context accessor.
`extensions/router/router-api/src/main/java/org/apache/unomi/router/api/ImportExportConfiguration.java`	Cleans imports, expands configuration docs, and fixes column-separator null handling.
`extensions/router/router-api/src/main/java/org/apache/unomi/router/api/exceptions/BadProfileDataFormatException.java`	Documents bad profile data format exception constructors and usage.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

sergehuber · 2026-05-17T06:14:14Z

+    /**
+     * 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
     */


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.

sergehuber · 2026-05-17T06:14:15Z

+ *
+ * <p>Configuration properties include:
+ * <ul>
+ *   <li>name - unique identifier for the configuration</li>


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

sergehuber · 2026-05-17T06:14:16Z

    /**
-     * 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
     */


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

sergehuber · 2026-05-17T06:14:18Z

     */
    public void setColumnSeparator(String columnSeparator) {
-        if(this.columnSeparator !=null) {
+        if (columnSeparator != null) {


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

sergehuber · 2026-05-17T06:14:19Z

+ * </ul>
+ * </p>
+ *
+ * @see org.apache.unomi.router.core.context.RouterCamelContext


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

sergehuber · 2026-05-17T06:14:34Z

+ * <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>


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

sergehuber · 2026-05-17T06:14:35Z

+ * 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.


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

sergehuber · 2026-05-17T06:14:36Z

+ *   <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>


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

sergehuber · 2026-05-17T06:14:37Z

    private Integer configsRefreshInterval = 1000;
    private ScheduledFuture<?> scheduledFuture;

+    /** Event topic fired when a router configuration or route is removed (reserved for integrations). */


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.

sergehuber · 2026-05-17T06:14:38Z

+     * - Formatting profiles according to export configuration
+     * - Generating the export content
+     *
+     * @param exportConfiguration the configuration specifying export parameters and format


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.

…ort-javadoc

… into UNOMI-888-import-export-javadoc

…ort-javadoc

Align documentation with actual import/export behavior, fix configType and transport-mode wording (kafka/nobroker vs direct), validate column separator length, and make getCamelContext() a default interface method.

…ort-javadoc

sergehuber requested a review from Copilot May 14, 2026 06:09

Copilot started reviewing on behalf of sergehuber May 14, 2026 06:09 View session

Copilot AI reviewed May 14, 2026

View reviewed changes

sergehuber and others added 8 commits May 15, 2026 08:14

Add manual dispatch to CodeQL Java workflow

7261e6a

Add manual dispatch to CodeQL JavaScript workflow

624b027

Merge branch 'UNOMI-879-unified-crud-shell' into UNOMI-888-import-exp…

c0f7484

…ort-javadoc

Merge remote-tracking branch 'origin/UNOMI-888-import-export-javadoc'…

e07010d

… into UNOMI-888-import-export-javadoc

Merge branch 'UNOMI-879-unified-crud-shell' into UNOMI-888-import-exp…

ca29dab

…ort-javadoc

Merge branch 'UNOMI-879-unified-crud-shell' into UNOMI-888-import-exp…

6c4637c

…ort-javadoc

Merge branch 'UNOMI-879-unified-crud-shell' into UNOMI-888-import-exp…

4608112

…ort-javadoc

UNOMI-888: Address PR review feedback for router Javadoc

83c6a68

Align documentation with actual import/export behavior, fix configType and transport-mode wording (kafka/nobroker vs direct), validate column separator length, and make getCamelContext() a default interface method.

sergehuber mentioned this pull request May 18, 2026

UNOMI-921: Replace elasticsearch-maven-plugin with Docker-based Elasticsearch in integration tests #759

Open

1 task

sergehuber added 2 commits May 18, 2026 15:06

Merge branch 'UNOMI-879-unified-crud-shell' into UNOMI-888-import-exp…

a00a859

…ort-javadoc

Merge branch 'UNOMI-879-unified-crud-shell' into UNOMI-888-import-exp…

bd506c3

…ort-javadoc

sergehuber mentioned this pull request May 18, 2026

UNOMI-139 UNOMI-880 UNOMI-878 UNOMI-884: Multi-tenant platform core #760

Open

1 task

Merge branch 'UNOMI-879-unified-crud-shell' into UNOMI-888-import-exp…

2d6c00e

…ort-javadoc

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

UNOMI-888: Javadoc and API cleanup for import/export router extension#756
sergehuber wants to merge 12 commits into
UNOMI-879-unified-crud-shellfrom
UNOMI-888-import-export-javadoc

sergehuber commented May 6, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

sergehuber May 17, 2026

Uh oh!

sergehuber May 17, 2026

Uh oh!

sergehuber May 17, 2026

Uh oh!

sergehuber May 17, 2026

Uh oh!

sergehuber May 17, 2026

Uh oh!

sergehuber May 17, 2026

Uh oh!

sergehuber May 17, 2026

Uh oh!

sergehuber May 17, 2026

Uh oh!

sergehuber May 17, 2026

Uh oh!

sergehuber May 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

sergehuber commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Stacked PR (merge order)

Summary

What changed

Documentation

Small fixes (non-doc)

Verification

Scope

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

sergehuber commented May 6, 2026 •

edited

Loading