Package org.mockserver.mock.breakpoint

Class BreakpointMatcher

java.lang.Object
org.mockserver.mock.breakpoint.BreakpointMatcher
public class BreakpointMatcher extends Object
A registered breakpoint: a request matcher + set of phases at which matching forwarded exchanges should be paused for interactive inspection/modification.

The prebuilt HttpRequestMatcher is created once at registration time (via MatcherBuilder.transformsToMatcher(RequestDefinition)) and reused for every findMatch call — no allocation on the hot path.

The clientId identifies the owning callback WebSocket client. It is required -- matched exchanges are always dispatched over the callback WebSocket to the owning client for interactive resolution.

Conditional (Nth-hit / skip-count) breakpoints: an optional skipCount delays the first pause. The matcher still matches normally on every hit, but only pauses once it has been hit more than skipCount times. With skipCount = 2 the breakpoint does NOT pause on hits 1 and 2 and DOES pause from hit 3 onward. When skipCount is null (the default) the breakpoint pauses on every hit (legacy behaviour). The per-matcher hit counter (hitCount) is incremented atomically by shouldPause(), so the decision is thread-safe under concurrent matching.

Response-content conditional breakpoints: optional response conditions (responseStatusCodeMin/responseStatusCodeMax for an inclusive status-code range, and responseBodyContains for a regex searched within the response body) gate whether a RESPONSE-phase breakpoint pauses. They are only evaluated at the response phase (the response is not yet known at the request phase). When set, the breakpoint pauses only when the response satisfies all configured conditions (in addition to the request matcher and any skip-count). When all are null (the default) the breakpoint pauses regardless of response content (legacy behaviour). The responseBodyContains pattern is compiled once at registration (find semantics — pauses if the body contains a match).

One-shot / bounded (maxHits) breakpoints: an optional maxHits bounds how many times the breakpoint may pause before it auto-deregisters. Each actual pause increments the pauseCount; once it reaches maxHits the breakpoint is exhausted and is removed from the BreakpointMatcherRegistry — subsequent matching requests are no longer intercepted. maxHits = 1 is the common "pause once then stop" one-shot breakpoint. When maxHits is null (the default) the breakpoint never auto-deregisters (legacy behaviour). Skipped hits (within a skipCount window) do NOT count against maxHits — only real pauses do.

Value-equality is on id only (UUID assigned at registration).

  • Constructor Details

  • Method Details

    • getId

      public String getId()

    • getRequestMatcher

      public RequestDefinition getRequestMatcher()

    • getPhases

      public Set<BreakpointPhase> getPhases()

    • getPrebuiltMatcher

      public HttpRequestMatcher getPrebuiltMatcher()

    • getClientId

      public String getClientId()
      The callback WebSocket client id that owns this breakpoint (required).

    • getSkipCount

      public Integer getSkipCount()
      The optional skip-count: the number of matching hits to skip before the breakpoint starts pausing. null (the default) means pause on every hit. A value of n means do not pause on the first n hits and pause from hit n + 1 onward.

    • getResponseStatusCodeMin

      public Integer getResponseStatusCodeMin()
      Lower bound (inclusive) of the optional response status-code condition, or null if no lower bound is configured.

    • getResponseStatusCodeMax

      public Integer getResponseStatusCodeMax()
      Upper bound (inclusive) of the optional response status-code condition, or null if no upper bound is configured.

    • getResponseBodyContains

      public String getResponseBodyContains()
      The optional regular expression searched (find semantics) within the response body, or null if no body condition is configured.

    • hasResponseCondition

      public boolean hasResponseCondition()
      Whether this breakpoint has any response-content condition (status-code range or body pattern) that must be satisfied for it to pause at the RESPONSE phase.

    • responseConditionMatches

      public boolean responseConditionMatches(HttpResponse response)
      Evaluates the optional response-content conditions against the given response.

      Returns true when the response satisfies all configured conditions (status-code within the inclusive [min, max] range, and the body matches the responseBodyContains regex via find semantics). When no conditions are configured this returns true (the legacy behaviour: pause regardless of response content). A null response or null status code fails any configured status-code condition; a null/empty body fails any configured body condition.

      Parameters:
      response - the response about to be written to the downstream client
      Returns:
      true if the response satisfies all configured conditions

    • getMaxHits

      public Integer getMaxHits()
      The optional maximum number of times this breakpoint may pause before it auto-deregisters, or null if the breakpoint never auto-deregisters. A value of 1 is a one-shot breakpoint.

    • getHitCount

      public long getHitCount()
      The number of times this breakpoint has matched (for diagnostics / tests).

    • getPauseCount

      public long getPauseCount()
      The number of pauses attempted past the skip window (as opposed to merely matched). Differs from getHitCount() when a skipCount window suppressed some early pauses. Used to evaluate isExhausted().

      Note: this counts pause attempts, not pauses that returned true. Under concurrent access it may exceed maxHits — a caller that races past the budget still increments this counter but shouldPause() returns false for it, so at most maxHits exchanges actually pause.

    • isExhausted

      public boolean isExhausted()
      Whether this breakpoint has reached its maxHits pause budget and should be removed from the registry. Always false when maxHits is null (the breakpoint never auto-deregisters).

    • shouldPause

      public boolean shouldPause()
      Records a matching hit and decides whether this hit should actually pause.

      Called exactly once per matching exchange/phase (from BreakpointMatcherRegistry.findMatch(org.mockserver.model.RequestDefinition, org.mockserver.mock.breakpoint.BreakpointPhase)). Increments the per-matcher counter atomically and returns true if the breakpoint should pause for this hit, false if the hit falls within the configured skip-count window. When skipCount is null this always returns true (pause every time).

      When a maxHits budget is configured, only the first maxHits real pauses return true; once the budget is spent this returns false (and isExhausted() becomes true, so the registry removes the breakpoint). Skipped hits do not consume the budget.

      Returns:
      true to pause this hit, false to skip it

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object