69 lines
3.1 KiB
Markdown
69 lines
3.1 KiB
Markdown
# Extended State Machine Analysis: Trigger Point Mapping
|
|
|
|
## Overview
|
|
The goal of this extension is to bridge the gap between state machine definitions and their real-world usage in application code. By identifying where events are triggered (e.g., REST endpoints, message listeners), we can provide a more holistic view of the system's behavior.
|
|
|
|
## Key Concepts
|
|
- **Trigger Point**: A location in the source code where an event is sent to a state machine (e.g., `stateMachine.sendEvent(E)`).
|
|
- **Entry Point**: A high-level application component (e.g., a REST Controller or Message Listener) that ultimately leads to a Trigger Point.
|
|
- **Event Linkage**: The process of connecting an Entry Point to one or more state machine transitions via the event that triggers them.
|
|
|
|
## Proposed Architecture
|
|
|
|
### 1. TriggerDetector
|
|
A generic interface for identifying trigger points and extracting context.
|
|
```java
|
|
public interface TriggerDetector {
|
|
List<TriggerPoint> detect(CompilationUnit cu, CodebaseContext context);
|
|
}
|
|
```
|
|
|
|
### 2. Predefined Detectors
|
|
- **SpringMvcDetector**: Looks for `@RestController` / `@Controller` and mappings like `@PostMapping`.
|
|
- **SpringWebFluxDetector**:
|
|
- **Annotation-based**: Similar to MVC but handles `Mono`/`Flux` return types.
|
|
- **Functional-based**: Scans for `RouterFunction` beans and extracts routes/handlers.
|
|
- **MessageListenerDetector**:
|
|
- **Kafka**: `@KafkaListener`.
|
|
- **RabbitMQ**: `@RabbitListener`.
|
|
- **JMS**: `@JmsListener`.
|
|
- **GenericEventDetector**: Looks for any `sendEvent` call and tries to find its context.
|
|
|
|
### 3. TriggerPoint Model
|
|
```java
|
|
public record TriggerPoint(
|
|
String className,
|
|
String methodName,
|
|
String event,
|
|
TriggerContext context
|
|
) {}
|
|
|
|
public record TriggerContext(
|
|
String type, // "REST", "KAFKA", "JMS", "GENERIC"
|
|
Map<String, String> metadata // path="/api/submit", topic="orders", etc.
|
|
) {}
|
|
```
|
|
|
|
### 4. Analysis Flow
|
|
1. **Scan Phase**: Existing `CodebaseContext.scan(root)`.
|
|
2. **Configuration Phase**: Existing `StateMachineAggregator` finds states and transitions.
|
|
3. **Trigger Discovery Phase**: New `TriggerAggregator` runs various `TriggerDetector`s over the scanned codebase.
|
|
4. **Correlation Phase**: Match `TriggerPoint.event` with `Transition.event`.
|
|
5. **Export Phase**: Enhance DOT/SCXML or generate a new "System Flow Map".
|
|
|
|
## Challenges
|
|
- **Multiple State Machines**: How to know which `StateMachine` instance is being used?
|
|
- Initial heuristic: If there's only one, assume it's that one.
|
|
- If multiple, check generic types `StateMachine<S, E>` or variable names.
|
|
- **Indirect Calls**: Method `A` (Controller) calls `B` (Service), and `B` calls `sendEvent`.
|
|
- Static analysis might need to follow call graphs.
|
|
- Use JDT's cross-reference capabilities if possible, or build a simple call graph.
|
|
- **Inheritance**:
|
|
- Controllers might extend base classes with common mappings.
|
|
- State machine configurations already handle inheritance; Trigger detection should too.
|
|
|
|
## Next Steps
|
|
1. Create a PoC `TriggerDetector` for Spring MVC.
|
|
2. Integrate `TriggerAggregator` into the main analysis pipeline.
|
|
3. Update the `Exporter` to visualize these links.
|