apache / apache/shardingsphere
Supported boundary for test-only SQLExecutionHook providers on 5.5.3
- Dominant language
- Java
- Stars
- 20.8k
- Forks
- 6.9k
- Avg merge
- 11h 38m
- Merged PRs (30d)
- 326
Description
## Question
I maintain RouteContract, a test-only execution-contract library pinned to ShardingSphere-JDBC 5.5.3. I would like to clarify the supported boundary for an external `SQLExecutionHook` provider:
1. Is classpath registration through `META-INF/services/org.apache.shardingsphere.infra.executor.sql.hook.SQLExecutionHook` intended for external test providers? May a provider rely on a fresh instance per physical execution attempt and the same instance receiving `start` and the normal-success terminal, allowing object-local correlation? Or are these internal implementation details?
2. What compatibility expectations should a version-pinned observer have when upgrading ShardingSphere? If another documented extension point is preferred, which one?
### Reproduction and scope
[Standalone runnable probe, pinned revision](https://gist.github.com/ym0506/3d03a9d5d158c52a6a2a1848605f779b/a5b99236810f44ded981b6f340a4623345ef8fd8): Java 17, exact ShardingSphere 5.5.3, disposable MySQL containers, synchronous non-batch `PreparedStatement` reads. No RouteContract dependency, Java agent, or patched upstream classes.
After one unobserved warm-up, two equality reads and one fan-out read return the same complete synthetic row. Four start/success pairs occur on four distinct used provider objects, with no reuse or unmatched terminal. The observer ignores hook arguments. Three JUnit tests pass: one native MySQL test and two manually invoked recorder controls. A second run from the portable bundle produces the same result; both runs are my own verification. The README and POM state the exact dependencies and limitations.
This agrees with the 5.5.3 implementation in [JDBCExecutorCallback](https://github.com/apache/shardingsphere/blob/8d35894433416ef249ebb6ea21f8a8749648e9b6/infra/executor/src/main/java/org/apache/shardingsphere/infra/executor/sql/execute/engine/driver/jdbc/JDBCExecutorCallback.java#L78-L104), [SPISQLExecutionHook](https://github.com/apache/shardingsphere/blob/8d35894433416ef249ebb6ea21f8a8749648e9b6/infra/executor/src/main/java/org/apache/shardingsphere/infra/executor/sql/hook/SPISQLExecutionHook.java#L29-L45), and [RegisteredShardingSphereSPI](https://github.com/apache/shardingsphere/blob/8d35894433416ef249ebb6ea21f8a8749648e9b6/infra/spi/src/main/java/org/apache/shardingsphere/infra/spi/RegisteredShardingSphereSPI.java#L58-L68). Passing tests do not establish a supported contract; that is what I am asking about.
I searched the documentation and open/closed issues, including #26323 and the former SPI-document removal in #27596, but could not find an explicit answer. Exceptional terminal delivery in #39763 is separate and excluded here, as are batches, forced callback overlap, and arbitrary asynchronous application work.
Codex materially assisted the investigation, reproducer, and write-up. Thank you for guidance on the intended boundary.
Contributor guide
Research direction
Read JDBCExecutorCallback.java, SPISQLExecutionHook.java, and RegisteredShardingSphereSPI.java at the pinned 5.5.3 revision, then run the linked standalone probe if needed. Done means a maintainer clarifies whether external test providers may rely on the observed lifecycle and instance correlation, and documents compatibility expectations or a preferred extension point.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- databases
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100