How schweizerischebundesbahnen/ch.sbb.polarion.extension.diff-tool works
Main Components
• Polarion Integration:
– The extension is designed to be deployed inside Polarion by copying a generated jar file to the Polarion instance.
– It makes use of Polarion’s configuration (e.g., project administration pages, sidebar extensions, and REST API interactions).
– Integration points include the addition of extra document properties pages, nodes in Polarion’s navigation tree, and administration configuration.
• Backend (Java/Maven Extension):
– Core business logic implemented in Java.
– Organized in packages such as ch.sbb.polarion.extension.diff_tool with submodules for diffing (fields, work items, collections), merging, and document copying.
– Contains controllers for REST endpoints (under …/rest/controller) and Velocity context integration for calling diff functions from templates.
– Includes service layers that perform diffing computations, merging, PDF conversion, and handling of work items (with further subdivisions into “service”, “handler”, “cleaners”, “util”, etc.).
– Supporting extensions such as web resources (plugin.xml, web.xml, velocity scripts) are located under src/main/resources.
• Frontend / UI Application:
– Located in the “ui” directory, which contains a modern JavaScript-based application.
– This component is responsible for presenting the diff and merge interfaces (diff views, merge buttons, configuration, and listing components) and interacts with the backend REST API endpoints.
– Likely built with Next.js/React, as suggested by next.config.mjs, package.json, and directory structure under ui/src.
• External Dependencies and Integration Points:
– PDF-Exporter integration (mentioned in the README, with compatibility details).
– Interaction with Polarion’s REST API for data retrieval and submission.
– Usage of Maven for build and deployment automation (Maven workflows, pom.xml, maven configuration files).
Visualizing Relationships and Data Flows
• The Frontend makes AJAX (REST) calls to the Backend REST API endpoints (controllers) to request diffing data, merge operations, and configuration data.
• The Backend processes these REST calls using various service layers that handle the core diff/merge logic.
• Some backend endpoints might also be called by Polarion’s UI through Velocity Templates, with functions like diffText and diffHtml provided via a Velocity context variable ($diffTool).
• The extension itself is integrated into the Polarion ecosystem. When the extension is installed (by copying the jar to the <polarion_home>/... directory), it “plugs in” to features such as extra document property panes and navigation topics. Data flows back and forth between the Polarion instance and the extension’s backend.
• The overall system uses Maven for building, testing (unit tests under src/test), and packaging the extension as well as automation via GitHub workflows (in .github/workflows).
Architectural Patterns and Design Principles
• Modular separation: The project is separated into distinct modules – a backend Java module (organized by functionality: controllers, models, services, utilities, etc.) and a standalone UI module.
• MVC / REST patterns: The backend uses REST controllers (and also servlet controllers for UI forms) to separate data processing from view rendering. The UI acts as a consuming client of these REST services.
• Plugin/Extension architecture: The project is designed to be “plugged” into an existing system (Polarion) with clear boundaries and prescribed integration points (configuration instructions provided in the README).