Package com.tnsai.resilience

Class MeteredHandle

java.lang.Object
com.tnsai.resilience.MeteredHandle
All Implemented Interfaces:
AutoCloseable
public final class MeteredHandle extends Object implements AutoCloseable
Per-invocation handle for a @Metered action — opened by MeteredResolver.start(com.tnsai.metadata.ActionMetadata, com.tnsai.roles.Role) immediately before action dispatch and closed in a finally block. Records exactly one counter+latency entry to ResilienceMetrics per invocation.

Caller pattern (already wired in ActionExecutor): 


 MeteredHandle metered = MeteredResolver.start(action, role);
 try {
     Object result = executor.execute(...);
     metered.recordSuccess();
     return result;
 } catch (Exception e) {
     // Narrow to Exception per the codebase's no-broad-catch rule
     // — JVM-fatal Errors propagate; the close() finally still runs.
     metered.recordFailure();
     throw e;
 } finally {
     metered.close();
 }

close() is idempotent and safe to call without having recorded an outcome — in that case the call is logged as a failure (the action threw before reaching either branch) so the counter stays consistent.

The NOOP singleton is returned by MeteredResolver.start(com.tnsai.metadata.ActionMetadata, com.tnsai.roles.Role) when no @Metered annotation is present, so the calling pattern never branches.

Since:
0.5.4 (issue #173, Phase 1)

  • Field Details

    • NOOP

      public static final MeteredHandle NOOP
      No-op handle returned for actions without @Metered. All methods are cheap no-ops; the calling site uses the same try/finally shape whether metering is on or off.

  • Method Details

    • recordSuccess

      public void recordSuccess()
      Marks the action's invocation as successful. Call exactly once before close(); subsequent calls in the same handle are ignored to keep the counter consistent.

    • recordFailure

      public void recordFailure()
      Marks the action's invocation as failed. Same single-call contract as recordSuccess().

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable