gnodet opened a new issue, #13943:
URL: https://github.com/apache/maven/issues/13943

   ## Context
   
   The Maven 4 API has ~34 services extending the `Service` marker interface. 
These services fall into two fundamentally different categories, but the type 
hierarchy doesn't distinguish them:
   
   **Operation services** — perform significant work: I/O, side effects, 
measurable duration. They use the `Request`/`Result` pattern and are worth 
observing (logging, auditing, tracing).
   
   Examples: `DependencyResolver`, `ProjectBuilder`, `ModelBuilder`, 
`ArtifactResolver`, `SettingsBuilder`, `ArtifactInstaller`, `ArtifactDeployer`
   
   **Utility services** — pure transformations, factories, lookups. Stateless, 
fast, called at high frequency. They use direct parameters and should not fire 
events.
   
   Examples: `ArtifactFactory`, `ArtifactCoordinatesFactory`, 
`DependencyCoordinatesFactory`, `Interpolator`, `VersionParser`, `OsService`, 
`TempFileService`, `PathMatcherFactory`, `MessageBuilderFactory`
   
   This matters for #13646 (generic `RequestEvent` for service call lifecycle). 
Without a type-level distinction, every `Request`/`Result` service would need 
to individually decide whether to fire events. The factory services 
(`ArtifactFactory`, `ArtifactCoordinatesFactory`, 
`DependencyCoordinatesFactory`) currently use `Request`/`Result` objects but 
are really just typed constructors — firing `RequestEvent` for every coordinate 
creation would add overhead and noise for zero observability value.
   
   ## Proposal
   
   ### 1. Introduce `OperationService` marker
   
   ```java
   @Experimental
   @ThreadSafe
   public interface OperationService extends Service {
       // Marker: calls to implementations of this service fire RequestEvent
   }
   ```
   
   ### 2. Classify existing services
   
   ```
   Service (marker — base for all)
   ├── ArtifactFactory              — utility, direct params
   ├── ArtifactCoordinatesFactory   — utility, direct params
   ├── DependencyCoordinatesFactory — utility, direct params
   ├── Interpolator                 — utility, direct params
   ├── VersionParser                — utility, direct params
   ├── OsService                    — utility, direct params
   ├── TempFileService              — utility, direct params
   ├── PathMatcherFactory           — utility, direct params
   ├── MessageBuilderFactory        — utility, direct params
   ├── ArtifactManager              — utility, direct params
   ├── ProjectManager               — utility, direct params
   ├── ChecksumAlgorithmService     — utility, direct params
   ├── Lookup                       — utility, direct params
   ├── Prompter                     — utility, direct params
   └── OperationService (marker — fires RequestEvent)
       ├── DependencyResolver       — Request/Result
       ├── ArtifactResolver         — Request/Result
       ├── ProjectBuilder           — Request/Result
       ├── ModelBuilder             — Request/Result
       ├── SettingsBuilder          — Request/Result
       ├── ToolchainsBuilder        — Request/Result
       ├── ArtifactInstaller        — Request/Result
       ├── ArtifactDeployer         — Request/Result
       ├── VersionResolver          — Request/Result
       ├── VersionRangeResolver     — Request/Result
       ├── TransportProvider        — Request/Result
       └── PluginManager            — Request/Result
   ```
   
   ### 3. Migrate factory services off Request/Result
   
   The factory services (`ArtifactFactory`, `ArtifactCoordinatesFactory`, 
`DependencyCoordinatesFactory`) already have convenience overloads with direct 
parameters — those are what callers actually use. The `Request`-based methods 
are implementation extension points, but for pure constructors there is nothing 
meaningful to extend. These services should drop their `Request` types and take 
direct parameters only, like `TempFileService` and `Interpolator` already do.
   
   This is a separate cleanup that can be done incrementally.
   
   ### Benefits
   
   - **Clean rule for #13646**: `RequestEvent` fires for every 
`OperationService` call — no exceptions, no opt-in/opt-out ambiguity, no 
per-service convention.
   - **Self-documenting API**: if a service extends `OperationService`, callers 
know its calls are observable; if it extends `Service`, they know it's a 
lightweight utility.
   - **Performance safety**: high-frequency factory/utility services are 
structurally excluded from event dispatch overhead.
   - **Guides new service design**: authors of new services (e.g., 
`ProcessExecutionService` from #13895) choose which interface to extend, and 
the observability behavior follows from the type.
   
   ## Related
   
   - #13646 — Generic `RequestEvent` for service call lifecycle (depends on 
this)
   - #13895 — Process execution service (new `OperationService`)
   - #13562 — Extend v4 Event hierarchy
   
   _Fully automatic review from Claude Code_


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: [email protected]

For queries about this service, please contact Infrastructure at:
[email protected]

Reply via email to