Skip to content

v3.0.0.M1

Pre-release
Pre-release

Choose a tag to compare

View all tags
@david-waltermire david-waltermire released this 14 Dec 18:56
· 93 commits to main since this release
v3.0.0.M1
1a75306

This is the first milestone release toward v3.0.0. It focuses on architectural improvements, enhanced testability, and significant code quality investments. As a pre-release, APIs may continue to evolve before the final v3.0.0 release.

✨ Highlights

  • XMLBeans Removed from Core: The core module no longer depends on XMLBeans. Module and constraint loading now uses the databind module's format-agnostic loaders.
  • Metapath Exception Hierarchy Refactored: Exception classes reorganized into StaticMetapathError (compilation) and DynamicMetapathError (execution) branches for clearer error handling.
  • Programmatic Module & Constraint Construction: New builder APIs enable construction of modules and constraint sets in code, eliminating XML parsing dependencies for testing.
  • Comprehensive Documentation: Added Javadoc to 99 files and 43 package-info.java files, with a formal style guide for contributors.
  • Concurrency Fixes: Resolved class initialization deadlocks that could occur during parallel test execution.

⚠️ Breaking Changes

XMLBeans Removed from Core Module (#529)

The ModuleLoader and XmlConstraintLoader classes have been removed from the core module. Applications should migrate to the databind module's loaders:

Old (core) New (databind)
ModuleLoader BindingModuleLoader
XmlConstraintLoader BindingConstraintLoader

The databind loaders support XML, JSON, and YAML formats.

Relocated Constants

XmlModuleConstants has been replaced by MetaschemaModelConstants in the gov.nist.secauto.metaschema.core.model package.

Metapath Exception Hierarchy Refactored

The Metapath exception hierarchy has been significantly restructured:

  • StaticMetapathError: For compilation-time errors (parsing, type checking)
  • DynamicMetapathError: For runtime errors (evaluation, context issues)
    • ContextAbsentDynamicMetapathException: When required context is missing
    • InvalidTreatTypeDynamicMetapathException: For type treatment failures
  • ArrayMetapathException: New sub-exceptions for array handling errors
    • IndexOutOfBoundsArrayMetapathException
    • NegativeLengthArrayMetapathException
  • FunctionMetapathError: Function-related exceptions moved to dedicated branch

Applications catching specific Metapath exceptions may need to update their exception handling.

✨ New Features

Constraint Validation Exception Support

New ValidationFeature.THROW_EXCEPTION_ON_ERROR option allows constraint validation errors to be thrown as exceptions instead of collected:

IBindingContext context = IBindingContext.builder()
    .validationFeature(ValidationFeature.THROW_EXCEPTION_ON_ERROR, true)
    .build();

This also improves error logging by including the full Metapath expression causing evaluation errors.

Programmatic Builder APIs

New builder interfaces enable test fixtures without file parsing:

  • IModuleBuilder (#530): Fluent API for creating mock IModule instances with assemblies, fields, and flags
  • IConstraintSetBuilder (#532): Fluent API for creating constraint sets programmatically

Example:

IModule module = MockedModelTestSupport.module()
    .namespace("http://example.com/ns")
    .assembly(asm -> asm
        .name("root")
        .flag(flag -> flag.name("id").datatype(IStringItem.type()))
        .field(field -> field.name("value")))
    .build();

📚 Documentation Improvements

  • Javadoc Style Guide (#522): Comprehensive style guide based on Checkstyle configuration
  • Core Module Documentation (#544): Added Javadoc to 99 files, created/enhanced 43 package-info.java files
  • Progressive Documentation Policy: New code requires 100% Javadoc coverage; modified code should improve surrounding documentation

🔧 Build & CI Improvements

  • Ubuntu 24.04: CI workflows upgraded from Ubuntu 20.04 to 24.04
  • Nightly Builds (#548): Scheduled builds at 2:00 AM UTC with concurrency controls
  • Workflow Concurrency: In-progress runs are cancelled when new commits are pushed
  • Javadoc Encoding Fix: Resolved UTF-8 encoding issues on Windows with JDK 17

🐛 Bug Fixes

  • Class Initialization Deadlock (#517, #545): Fixed deadlocks in AbstractArrayItem, AbstractMapItem, and sequence classes that occurred during parallel test execution with JUnit 5's SEPARATE_THREAD timeout mode
  • Constraint Namespace Handling (#529): Fixed BindingConstraintLoader to properly apply StaticContext configuration for wildcard namespace matching
  • Root Path Error Code: Fixed root paths to raise the correct MPDY0050 error when a node without a document ancestor is used in context

🧪 Test Coverage

  • FunctionServiceTest: Comprehensive tests for function registration, lookup, and execution
  • ErrorHandlingTest: Tests for metapath parsing errors, type errors, and exception propagation
  • NodeItemTraversalTest: Tests for node item creation, navigation, and metapath generation
  • OperationFunctionsTest: Added modulo division by zero error handling tests

What's Changed

Core Changes

Exception Refactoring

  • Refactored Metapath exception hierarchy with StaticMetapathError and DynamicMetapathError branches
  • Added sub-exceptions for array handling (IndexOutOfBoundsArrayMetapathException, NegativeLengthArrayMetapathException)
  • Added ValidationFeature.THROW_EXCEPTION_ON_ERROR for constraint validation
  • Added absent dynamic context sub-exception
  • Improved Metapath expression logging in error messages

Documentation & Code Quality

Build & CI

Full Changelog: v2.2.0...v3.0.0.M1

📦 Dependency Updates

Java Libraries

  • com.fasterxml.jackson:jackson-bom: 2.18.3 → 2.20.1 (#540)
  • commons-cli:commons-cli: 1.9.0 → 1.11.0 (#534)
  • commons-codec:commons-codec: 1.18.0 → 1.20.0 (#542)
  • commons-io:commons-io: 2.18.0 → 2.21.0 (#525)
  • org.apache.commons:commons-lang3: 3.17.0 → 3.20.0 (#484)
  • org.apache.logging.log4j:log4j-bom: 2.24.3 → 2.25.2 (#527)
  • org.mockito:mockito-core: 5.17.0 → 5.21.0 (#508, #543)
  • net.sf.saxon:Saxon-HE: 12.5 → 12.9 (#481)
  • dev.harrel:json-schema: 1.8.1 → 1.9.0 (#524)
  • com.github.ben-manes.caffeine:caffeine: 3.2.0 → 3.2.3 (#509)
  • com.xmlcalabash:xmlcalabash: 1.5.7-120 → 3.0.31 (#496, #535)
  • org.xmlresolver:xmlresolver: 6.0.14 → 6.0.19 (#456)
  • io.github.hakky54:logcaptor: 2.10.2 → 2.12.1 (#526)
  • nl.talsmasoftware:lazy4j: 2.0.0 → 2.0.3 (#507)
  • net.openhft:compiler: 2.27ea1 → 2.27ea3 (#499)
  • org.eclipse.persistence:org.eclipse.persistence.moxy: 4.0.5 → 4.0.6 (#528)
  • org.eclipse.jdt:org.eclipse.jdt.annotation: 2.3.100 → 2.4.100 (#506, #541)
  • com.github.javaparser:javaparser-symbol-solver-core: 3.26.4 → 3.26.5 (#539)

Maven Plugins

  • org.sonatype.central:central-publishing-maven-plugin: 0.7.0 → 0.8.1 (#536)
  • org.codehaus.mojo:license-maven-plugin: 2.5.0 → 2.7.0 (#510)
  • org.apache.maven.plugins:maven-plugin-report-plugin: 3.15.1 → 3.16.1 (#537)

GitHub Actions

  • actions/checkout: 4.2.2 → 6.0.1 (#501)
  • actions/setup-java: 4.7.0 → 5.0.0
  • actions/upload-artifact: 4.6.2 → 6.0.0 (#503, #547)
  • actions/github-script: 7.0.1 → 8.0.0
  • github/codeql-action: 3.28.13 → 4.31.8 (#502, #505, #546)
  • lycheeverse/lychee-action: 2.4.0 → 2.7.0
  • peter-evans/create-issue-from-file: 5.0.1 → 6.0.0 (#500)

Contributors

component, Inject, and david-waltermire
Assets 2
Loading