UNOMI-888: Javadoc and API cleanup for import/export router extension#756
Merged
Conversation
- Add YamlUtils (SnakeYaml) with YamlConvertible, YamlMapBuilder, circular reference detection (identity-based visited sets), and recursion depth limits. - Implement YAML-backed toString()/toYaml() on core API types extending Item / MetadataItem (Condition, ConditionType, Action, ActionType, Rule, Segment, Goal, Scoring, ScoringElement, Parameter, Metadata, etc.). - Add YamlUtilsTest coverage for builder, toYamlValue, and representative rules. Build and integration alignment: - unomi-api: snakeyaml + test dependencies; manage mockito-core version in BOM. - RESTParameter: use Object for defaultValue to match Parameter#getDefaultValue(). - RulesServiceImpl: avoid NPE when tracked parameter defaultValue is null before split. - itests: override awaitility to 3.1.6 for OSGi (Hamcrest 1.3 bundle); Karaf itests common logback exclusions; hamcrest bundle scope test.
- Replace legacy per-type list/view commands with unified unomi:crud routing, shared bases (BaseCrudCommand, CrudCommand), completers, and type-specific CRUD implementations under org.apache.unomi.shell.dev. - Relocate deployment/tail/watch helpers into dev.commands package. - EventService/ProfileService: add deleteEvent/deleteSession; implementations delegate to PersistenceService.remove (aligned with unomi-3-dev). - BOM: dependency adjustments needed by shell-dev-commands build.
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.
There was a problem hiding this comment.
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 updatesRouterCamelContextaccordingly. - Fixes
RouterCamelContext#setTracing(boolean)to honor its argument and updatesImportExportConfiguration#setColumnSeparatornull 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.
Run mikepenz/action-junit-report after every integration matrix leg (if: always), with update_check and per-matrix check_name, so a green re-run replaces the stale red JUnit check. Use fail_on_failure=false and require_tests=false; continue-on-error so missing XML cannot fail the job.
…to UNOMI-879-unified-crud-shell
… into UNOMI-888-import-export-javadoc
Use identity-based visited sets for circular-reference detection, harden Condition deepCopy and parameter handling, fix Parameter max-depth YAML, wire slf4j.version in unomi-api, and expand unit test coverage.
Fix condition undeploy, rule list performance, null-safety and pagination in CRUD commands, thread-safe consent date formatting, read-only rulestats behavior, segment ID completion, and BOM httpclient dependency management.
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.
Replace the com.github.alexcojocaru:elasticsearch-maven-plugin (binary download + forked JVM) with io.fabric8:docker-maven-plugin so the elasticsearch profile of itests runs ES in a Docker container, mirroring how the opensearch profile already runs OpenSearch. itests/pom.xml (elasticsearch profile) * Add an <elasticsearch.port>9400</elasticsearch.port> property and pass it through the failsafe systemPropertyVariables so tests resolve the HTTP port from a single source. * Replace the elasticsearch-maven-plugin block with a docker-maven-plugin block that starts/stops a docker.elastic.co/elasticsearch/elasticsearch container, binds target/snapshots_repository to /tmp/snapshots_repository, and waits on the HTTP port before the integration-test phase. * Add a chmod -R ugo+rwx on snapshots_repository in the antrun unzip step: the ES container runs as UID 1000, so on Linux CI the bind-mounted snapshot repo otherwise hits access_denied during repository verify. pom.xml (root) * Declare <docker-maven-plugin.version>0.48.0</docker-maven-plugin.version> and add the pluginManagement entry so the elasticsearch profile (and any future user of the plugin) inherits a single version. This is phase A0 of the PR #757 stack split (see docs/PR-757-stack-extraction-tracker.md). It is intentionally small and self-contained: no test/code changes, only the test infrastructure switch.
1 task
…icsearch in integration tests Implements the core configuration switch from UNOMI-921: https://issues.apache.org/jira/browse/UNOMI-921 Replace the com.github.alexcojocaru:elasticsearch-maven-plugin (binary download + forked JVM) with io.fabric8:docker-maven-plugin in the elasticsearch profile of itests, mirroring how the opensearch profile already runs OpenSearch in a Docker container. itests/pom.xml (elasticsearch profile) * Add an <elasticsearch.port>9400</elasticsearch.port> property and pass it through the failsafe systemPropertyVariables so tests resolve the HTTP port from a single source (unchanged from the previous 9400). * Replace the elasticsearch-maven-plugin block with a docker-maven-plugin block that runs docker.elastic.co/elasticsearch/elasticsearch:${elasticsearch.test.version}, binds target/snapshots_repository to /tmp/snapshots_repository, and waits on the HTTP port before the integration-test phase. Heap aligned to 8GB (-Xms8g -Xmx8g) to match the OpenSearch configuration and the ES 9 recommendation. Discovery=single-node, replicas=0, xpack.ml and xpack.security disabled. * Container lifecycle matches OpenSearch exactly: pre-integration-test runs stop+remove then start (with showLogs); post-integration-test runs stop only -- container is kept around for inspection. * Add a chmod -R ugo+rwx on snapshots_repository in the antrun unzip step: the ES container runs as UID 1000, so on Linux CI the bind-mounted snapshot repo otherwise hits access_denied during repository verify. pom.xml (root) * Declare <docker-maven-plugin.version>0.48.0</docker-maven-plugin.version> and add the pluginManagement entry so the elasticsearch profile (and any future user of the plugin) inherits a single version. Scope kept minimal for the PR #757 stack split: only the test infrastructure switch lives here. The follow-up UNOMI-921 acceptance items below ship in the platform PR (P) once it lands: * Remove BaseIT.fixDefaultTemplateIfNeeded() and the call in checkSearchEngine() (no longer needed with Docker). * Migrate16xToCurrentVersionIT: replace hardcoded ES_BASE_URL = "http://localhost:9400" with dynamic getSearchPort(). * Drop the comments referring to the elasticsearch-maven-plugin template-override workaround. See docs/PR-757-stack-extraction-tracker.md for the full split plan and how this PR fits in the stack.
1 task
Non-interactive prompts when CI, GITHUB_ACTIONS, or BUILD_NON_INTERACTIVE is set. Add --ci (no Karaf, no Maven build cache) and MAVEN_EXTRA_OPTS for matrix ports.
Replace fixed sleeps in GraphQLListIT and poll after patch refresh in PatchIT.
Poll profile properties after events in PropertiesUpdateActionIT.
Align CI with local developer workflow; pass matrix ports via MAVEN_EXTRA_OPTS.
…icsearch in integration tests Implements the core configuration switch from UNOMI-921: https://issues.apache.org/jira/browse/UNOMI-921 Replace the com.github.alexcojocaru:elasticsearch-maven-plugin (binary download + forked JVM) with io.fabric8:docker-maven-plugin in the elasticsearch profile of itests, mirroring how the opensearch profile already runs OpenSearch in a Docker container. itests/pom.xml (elasticsearch profile) * Add an <elasticsearch.port>9400</elasticsearch.port> property and pass it through the failsafe systemPropertyVariables so tests resolve the HTTP port from a single source (unchanged from the previous 9400). * Replace the elasticsearch-maven-plugin block with a docker-maven-plugin block that runs docker.elastic.co/elasticsearch/elasticsearch:${elasticsearch.test.version}, binds target/snapshots_repository to /tmp/snapshots_repository, and waits on the HTTP port before the integration-test phase. Heap aligned to 8GB (-Xms8g -Xmx8g) to match the OpenSearch configuration and the ES 9 recommendation. Discovery=single-node, replicas=0, xpack.ml and xpack.security disabled. * Container lifecycle matches OpenSearch exactly: pre-integration-test runs stop+remove then start (with showLogs); post-integration-test runs stop only -- container is kept around for inspection. * Add a chmod -R ugo+rwx on snapshots_repository in the antrun unzip step: the ES container runs as UID 1000, so on Linux CI the bind-mounted snapshot repo otherwise hits access_denied during repository verify. pom.xml (root) * Declare <docker-maven-plugin.version>0.48.0</docker-maven-plugin.version> and add the pluginManagement entry so the elasticsearch profile (and any future user of the plugin) inherits a single version. Scope kept minimal for the PR #757 stack split: only the test infrastructure switch lives here. The follow-up UNOMI-921 acceptance items below ship in the platform PR (P) once it lands: * Remove BaseIT.fixDefaultTemplateIfNeeded() and the call in checkSearchEngine() (no longer needed with Docker). * Migrate16xToCurrentVersionIT: replace hardcoded ES_BASE_URL = "http://localhost:9400" with dynamic getSearchPort(). * Drop the comments referring to the elasticsearch-maven-plugin template-override workaround. See docs/PR-757-stack-extraction-tracker.md for the full split plan and how this PR fits in the stack.
…MI-921-itests-es-docker
# Conflicts: # build.sh # itests/src/test/java/org/apache/unomi/itests/PropertiesUpdateActionIT.java # itests/src/test/java/org/apache/unomi/itests/graphql/GraphQLListIT.java
# Conflicts: # api/src/main/java/org/apache/unomi/api/conditions/Condition.java # api/src/main/java/org/apache/unomi/api/services/ProfileService.java # api/src/main/java/org/apache/unomi/api/utils/YamlUtils.java # api/src/test/java/org/apache/unomi/api/conditions/ConditionTest.java # build.sh # itests/pom.xml # itests/src/test/java/org/apache/unomi/itests/PropertiesUpdateActionIT.java # itests/src/test/java/org/apache/unomi/itests/graphql/GraphQLListIT.java # tools/shell-dev-commands/src/main/java/org/apache/unomi/shell/dev/actions/UnomiCrudCommand.java # tools/shell-dev-commands/src/main/java/org/apache/unomi/shell/dev/commands/TailCommandUtils.java # tools/shell-dev-commands/src/main/java/org/apache/unomi/shell/dev/commands/UndeployDefinition.java # tools/shell-dev-commands/src/main/java/org/apache/unomi/shell/dev/commands/campaigns/CampaignCrudCommand.java # tools/shell-dev-commands/src/main/java/org/apache/unomi/shell/dev/commands/campaigns/CampaignEventCrudCommand.java # tools/shell-dev-commands/src/main/java/org/apache/unomi/shell/dev/commands/consents/ConsentCrudCommand.java # tools/shell-dev-commands/src/main/java/org/apache/unomi/shell/dev/commands/goals/GoalCrudCommand.java # tools/shell-dev-commands/src/main/java/org/apache/unomi/shell/dev/commands/profiles/ProfileAliasCrudCommand.java # tools/shell-dev-commands/src/main/java/org/apache/unomi/shell/dev/commands/profiles/ProfileCrudCommand.java # tools/shell-dev-commands/src/main/java/org/apache/unomi/shell/dev/commands/segments/SegmentCrudCommand.java # tools/shell-dev-commands/src/main/java/org/apache/unomi/shell/dev/commands/sessions/SessionCrudCommand.java # tools/shell-dev-commands/src/main/java/org/apache/unomi/shell/dev/services/BaseCrudCommand.java
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked PR (merge order)
UNOMI-879-unified-crud-shellUNOMI-888-import-export-javadocThis PR is stacked: merge into
UNOMI-879-unified-crud-shellfirst (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: AddObject 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 withsetLineSeparator).LineSplitFailureHandler:@Overrideonprocess(Exchange).Verification
(Fill in the exact Maven commands you ran, e.g. router modules compile / full
itests.)Scope
extensions/router/(commit51aa61c9f).