Refactor for 2.1 release#3
Merged
poikilotherm merged 55 commits intomainfrom Apr 3, 2026
Merged
Conversation
… pattern and add validation tests Replaces the mutable `ExportDataContext` implementation with an immutable design using a builder pattern, adds input validation for `offset` and `length`, and includes corresponding unit tests for negative values.
…instead of `IOException` We need a way to throw an unchecked exception from the core back to the plugin. IOException is a checked exception. With unchecked exceptions, we don't need to declare them on methods (which we didn't so far) and it makes more sense to describe them in the Javadocs for the data provider.
…etrieval methods and deprecations Revamp `ExportDataProvider` to provide context-sensitive methods for dataset metadata retrieval, improve documentation with detailed annotations, and deprecate older, less flexible methods. This keeps the old contract alive but encourages upgrading to the new style. The no-args methods can be removed at a later point in time.
Add foundational plugin infrastructure, including `PluginLoader`, `Plugin`, `CoreProvider`, and related exception handling (`LoaderException`, `LoaderProblem`). Setup API for plugin discovery, API level compatibility checks, and isolated class loading. Includes initial implementation of `TestPlugin` and `TestProvider` with unit tests.
…and compatibility target This defaults to 11 per GDCC Maven Parent
… clarity and adherence to interfaces
… reflecting the semantics in the name
…d file metadata shaping Introduce `DatasetMetadataPredicates`, `FileMetadataPredicates`, and their respective builders (`DatasetExportQuery`, `FileExportQuery`) to provide flexible and conflict-validated metadata shaping options for export operations. Includes unit tests for predicate conflict validation.
Introduce the `PageRequest` class to define pagination parameters for data retrieval. Includes methods for creating paged and unpaged requests, validation for offset and limit values, and utility methods. Add corresponding unit tests to ensure behavior correctness.
…y` and `FileExportQuery` Refactor `ExportDataProvider` to use `DatasetExportQuery` and `FileExportQuery` for metadata retrieval. Update affected method signatures, improve documentation, and introduce overloads for better flexibility and stream handling. Keep deprecation of methods with no parameters.
…aProvider` as it duplicates existing functionality
…icated submodule Migrate `export`-related classes to a dedicated `export` Maven submodule to improve modularity and maintainability. Add POM configuration, adjust imports, and update related tests accordingly.
… Maven submodule, migrate to annotation-based plugin contracts Replace `CoreProvider` and `Plugin` interfaces with annotation-based plugin contract definitions (`@PluginContract` and `@DataversePlugin`). Introduce `PluginContractProcessor` for build-time metadata generation, ensuring contract validation and compatibility checks. Update supporting infrastructure to reflect the annotation-based approach.
… and coverage Extend `PluginContractProcessor` to enforce stricter project-wide validation rules for plugin interfaces and implementations. Update processor logic to ensure idempotency during compilation rounds. Add unit tests to validate edge cases for plugin and provider contracts, such as missing annotations, duplicate registrations, and hierarchical type inspections.
… only Add validation logic in `PluginContractProcessor` to ensure `@PluginContract` is declared exclusively on interfaces. Update processor tests to cover invalid scenarios and verify compilation failures with meaningful diagnostics.
…interfaces Add new validation logic in `PluginContractProcessor` to prohibit direct implementations of `Plugin` and `CoreProvider` base interfaces. Update diagnostics for clearer error reporting and enhance processor tests for comprehensive coverage.
…lugin metadata management Introduce classes for in-memory representation (`PluginDescriptor`) and serialization/deserialization of plugin metadata (`PluginDescriptorFormat`). Add comprehensive unit tests to verify metadata handling and ensure round-trip consistency.
…oved clarity Update all references in annotations, related models, and processors to reflect the new terminology. Adjust validation logic, error messages, and unit tests accordingly.
…ency Simplify class names to improve clarity and ensure alignment with metadata terminology. Update related references, serialization logic, and unit tests accordingly.
…ance error message in `PluginContractProcessor` Clean up unused field to improve code maintainability. Clarify error messaging by including the fully qualified name of the `Plugin` interface for better developer guidance.
…plugin interfaces Validate that `@PluginContract` cannot be applied to interfaces that do not extend `Plugin`. Ensure meaningful diagnostics on compilation failure.
… handling Replace redundant calls to `Class::getCanonicalName` across the `DescriptorFormat` class with `transformClassName` method to align serialization logic and handle inner class naming consistently.
…plugin metadata representation Add `PluginDescriptor` for runtime-facing metadata of plugins and `SourcedDescriptor` for combining plugin information with source paths. Ensure immutability, validation, and equality consistency in both classes.
…n directories and JARs Implement `DescriptorScanner` to locate and parse plugin descriptors from specified directories or JAR files. Include unit tests to validate functionality for various scenarios, including edge cases and error handling.
…module version synchronization
…criptorBuilder` utilities Add foundational components for plugin loading and validation: - `LoaderHelper` provides internal utility methods for plugin handling like validation, class loading, and conversion. - `LoaderConfiguration` defines loader behavior options. - `DescriptorBuilder` offers a fluent API for creating plugin descriptors (during testing). Includes PluginHandle and PluginValidationResult as data transfer objects. Includes (initial) unit tests for functionality verification.
…options, add `SourceScanner` Extend `PluginLoader` with new constructors, `preloadPlugins` logic, and enhanced validation for class collisions, implementation checks, and API compatibility. Introduce the `SourceScanner` functional interface for custom filesystem scanning of plugin descriptors (especially during testing). Add nested unit tests for new functionality.
Shipping an all-in-one package for users makes using the SPI API much easier.
Switch parent packaging to POM, define modular structure, and introduce dependency management for streamlined versioning and future extensibility.
Extract repeated strings and constants from `PluginContractProcessor` to a new `ProcessorConstants` class for improved maintainability and consistency. Update the (core) `LoaderHelper` to reuse the centralized `API_LEVEL_FIELD_NAME`, coordinating the field name between processor (plugin compile time) and loader (plugin runtime).
…ntations Add comprehensive Javadoc for SPI annotations, including `PluginContract`, `DataversePlugin`, and the new `package-info.java`. Clarify roles, rules, and examples for authoring and implementing Dataverse plugins.
…ssor` Add comprehensive validation rules for plugin contract hierarchies, ensuring compliance with `Base` and `Capability` roles. Includes safeguards for `@PluginContract` usage, required contracts implementation, and package locality constraints. Allow base contract extension by a capability contract when it is required. Extend Javadoc and restructure the processor for improved readability and future maintainability.
…essor` compliance Refactor and organize tests for improved readability and coverage. Add new validation scenarios, including public and abstract implementation checks, base/capability contract rules, and descriptor generation validation.
- Configure Maven Shade Plugin in API module for packaging adjustments. - Set SLF4J dependency scope to "provided" in Core module to exclude it from the shading process (no need to redistribute)
…uginContractProcessor` - Validate compilation when base and capability contracts extend unrelated intermediate interfaces. - Ensure compliance with `@PluginContract` rules under complex interface hierarchies. This seems to be an unlikely scenario, but for the sake of completeness, we still cover it. As the processor is only about the metadata for plugins, unrelated interfaces don't bother us.
… to Exporter interfaces - Annotate `Exporter`, `XMLExporter`, and `ExportDataProvider` with `@PluginContract` for role and provider definitions. - Define `API_LEVEL` constant in each interface to enforce versioning and compatibility. - Extend `ExportDataProvider` to implement `CoreProvider`.
Provide a default implementation for `identity()` returning `getFormatName()` to avoid boilerplate code and enhance backward compatibility.
…eneration - Validate proper descriptor generation for `Exporter` and `XMLExporter` implementations. - Ensure service file creation for base contracts and absence for capability contracts. - Expand coverage with stub classes for JSON and DDI exporters.
- Introduce structured documentation for the Dataverse SPI Plugin API, including index, examples, and modules pages. - Add custom styles, site branding, and navigation for improved developer experience. - Configure Maven Site Plugin and reporting tools for streamlined site generation. - Include GitHub Actions workflow for automated site deployment to GitHub Pages.
…ment - Add `docs.site.base` property to `pom.xml` for customizable site base URL. - Update workflow and site templates to utilize the parameter for better flexibility in local development and deployment scenarios.
…narios - Adjust test case naming for clarity in `PluginLoaderTest`. - Add comments to explain intentional bypass of annotation processor in test setup. - Expand interface validation tests to cover runtime checks for invalid cases. - Ensure compatibility with `PluginContract` roles and `Plugin` extensions.
…tProcessor` - Ensure compilation fails when `CoreProvider`-extending or `Plugin`-extending interfaces are not public. - Add corresponding test cases to verify error reporting for non-public interfaces.
Correct scanning logic to handle directories and jar files separately. Also, update exception message for null path validation for better clarity. (The scanner no longer takes a set of paths, but a single path.)
…gin loading tests - Implement `LoaderTestEnvironment` and related builder to enable dynamic compilation and runtime class loading of test plugins. - Add `PluginLoaderIntegrationTest` to validate API level compatibility during plugin loading. - Include utility classes `TestJavaCompiler` and `TestCompilation` for handling source compilation and classpath setups during tests.
…tionTest` - Replace hardcoded API level test case with `@ParameterizedTest` using `@CsvSource` for dynamic API level scenarios. - Add a test to validate plugins compiled against matching API levels.
- Implement `verifyServiceProviderRecords()` in `LoaderHelper` for validating SPI service provider records in plugin descriptors. - Add `hasServiceProviderInterfaceRecord()` to `DescriptorScanner` to check for SPI records in directory and JAR sources. - Extend `LoaderProblem` to include `MissingServiceProviderRecord` for improved error reporting. - Add comprehensive unit tests in `LoaderHelperTest` and `DescriptorScannerTest` to verify validation logic.
…lues - Enforce validation in `DescriptorFormat` to reject negative values for plugin and provider levels. - Add unit tests to ensure proper error handling for invalid level values.
- Introduce `determineCoreApiLevel_providerClass` test in `LoaderHelperTest` to validate API level extraction for `TestProvider`. - Include `TestProvider` test interface with a defined `API_LEVEL`. - Update exception messages in `LoaderHelper` for improved clarity and consistency.
- Implement `verifyProviderApiLevels` in `LoaderHelper` to validate required provider API levels against core system levels. - Update `PluginLoader` to incorporate provider API level validation during plugin preloading. - Extend `LoaderProblem` with `ProviderApiLevelMismatch` and `ProviderClassUnsupported` for detailed error reporting. - Add comprehensive unit tests in `LoaderHelperTest` for provider level validation, covering various edge cases.
- Replace `LoaderConfiguration` record with a class for immutability and extendability. - Introduce `defaults()` and `permissive()` factory methods for common configurations. - Replace direct configuration instantiation in tests with factory methods to simplify setup. - Update all references to deprecated methods and fields with new getters.
Un-comment `branches: main` and `workflow_dispatch` triggers in `site.yml` to activate the workflow trigger for the `main` branch only
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
1 participant
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.
Closes #1