aspectran / aspectran / #5127

push

github

feat(core): implement advanced hint mechanism with frame-based isolation

This commit introduces a sophisticated Hint mechanism that allows business
logic to convey execution "intents" to underlying framework modules via
metadata, ensuring proper isolation and propagation across call frames.

Key features and enhancements:

- **Frame-based Isolation**: Implemented a logical "call frame" structure
  within the hint stack using `ArrayStack` and `null` as boundary markers.
  This ensures zero-allocation overhead for creating frame boundaries.
- **Propagation Control**: Added a `propagated` attribute to `@Hint` to
  strictly control whether a hint is visible to nested method calls.
- **Intelligent Peeking**: `peekHint` now respects frame boundaries,
  allowing only propagated hints from parent frames while always
  honoring hints within the current frame.
- **Architecture Refactoring**:
    - Extracted scanning logic into `ProxyHintScanner`.
    - Separated `SuperInvoker` into a standalone interface.
    - Decoupled `JdkBeanProxy` and `JavassistBeanProxy` from initialization
      details by injecting scanned hints during proxy creation.
- **API Robustness**: Enhanced `Activity` and `Translet` interfaces with
  count-based `popHint` and list-based `pushHint` to ensure stack
  integrity and prevent imbalance.
- **Comprehensive Documentation**: Updated Javadocs across the core
  interfaces to explain the frame isolation and propagation mechanism.
- **Extensive Testing**: Added diverse test scenarios in `HintTest` to
  verify basic functionality, propagation, and strict isolation.

Example:
  @Hint(type="tx", value="readOnly: true", propagated=false)
  public void serviceMethod() { ... }

70 of 86 new or added lines in 5 files covered. (81.4%)

18422 of 43042 relevant lines covered (42.8%)

0.43 hits per line