Request Matching

/**
 * URL pattern matching methods
 */
// Exact URL matching
static UrlPattern urlEqualTo(String testUrl);

// Regex URL matching  
static UrlPattern urlMatching(String urlRegex);

// Exact URL path matching (ignores query parameters)
static UrlPattern urlPathEqualTo(String testPath);

// Regex URL path matching
static UrlPattern urlPathMatching(String urlRegex);  

// URL path template matching with parameter extraction
static UrlPattern urlPathTemplate(String pathTemplate);

// Match any URL
static UrlPattern anyUrl();

class UrlPattern {
    static UrlPattern ANY;
    boolean isRegex();
    StringValuePattern getPattern();
    PathTemplate getPathTemplate();
}

// Exact URL matching
stubFor(get(urlEqualTo("/api/users/123"))
    .willReturn(aResponse().withStatus(200)));

// Regex URL matching
stubFor(get(urlMatching("/api/users/[0-9]+"))
    .willReturn(aResponse().withStatus(200)));

// Path template with parameters
stubFor(get(urlPathTemplate("/api/users/{id}/orders/{orderId}"))
    .willReturn(aResponse().withStatus(200)));

// Path-only matching (ignores query params)
stubFor(get(urlPathEqualTo("/api/search"))
    .willReturn(aResponse().withStatus(200)));

/**
 * String value pattern matching methods
 */
// Basic String Patterns
/** Exact string equality matching */
static StringValuePattern equalTo(String value);

/** Case-insensitive equality matching */
static StringValuePattern equalToIgnoreCase(String value);

/** Substring containment matching */
static StringValuePattern containing(String value);

/** Inverted substring matching */
static StringValuePattern notContaining(String value);

/** Regular expression matching */
static StringValuePattern matching(String regex);

/** Inverted regular expression matching */
static StringValuePattern notMatching(String regex);

/** Match absent/null values */
static StringValuePattern absent();

// Logical Operators
/** Logical AND combination of patterns */
static LogicalAnd and(StringValuePattern... matchers);

/** Logical OR combination of patterns */
static LogicalOr or(StringValuePattern... matchers);

/** Logical NOT wrapper for patterns */
static NotPattern not(StringValuePattern unexpectedPattern);

abstract class StringValuePattern {
    /** Check if pattern expects value presence */
    boolean isPresent();
    
    /** Check if pattern expects value absence */
    Boolean isAbsent();
    
    /** Combine with another pattern using AND logic */
    LogicalAnd and(StringValuePattern other);
    
    /** Combine with another pattern using OR logic */
    LogicalOr or(StringValuePattern other);
}

// String pattern matching
stubFor(get(urlEqualTo("/api/search"))
    .withQueryParam("q", containing("java"))
    .withQueryParam("category", equalToIgnoreCase("programming"))
    .willReturn(aResponse().withStatus(200)));

// Logical combinations
stubFor(post(urlEqualTo("/api/users"))
    .withHeader("Content-Type", or(
        equalTo("application/json"),
        equalTo("application/vnd.api+json")
    ))
    .willReturn(aResponse().withStatus(201)));

// Regex matching
stubFor(get(urlEqualTo("/api/users"))
    .withHeader("User-Agent", matching(".*Chrome.*"))
    .withHeader("Accept-Language", not(containing("en")))
    .willReturn(aResponse().withStatus(200)));

/**
 * JSON content matching methods
 */
// JSON Equality Matching
/** Basic JSON equality */
static StringValuePattern equalToJson(String json);

/** JSON equality with comparison options */
static StringValuePattern equalToJson(String json, boolean ignoreArrayOrder, boolean ignoreExtraElements);

/** JSON equality from JsonNode */
static StringValuePattern equalToJson(JsonNode jsonNode, boolean ignoreArrayOrder, boolean ignoreExtraElements);

// JSONPath Expression Matching
/** Simple JSONPath expression matching */
static StringValuePattern matchingJsonPath(String jsonPath);

/** JSONPath with value pattern matching */
static StringValuePattern matchingJsonPath(String jsonPath, StringValuePattern valuePattern);

// JSON Schema Validation
/** JSON Schema validation */
static StringValuePattern matchingJsonSchema(String schema);

/** JSON Schema validation with specific version */
static StringValuePattern matchingJsonSchema(String schema, JsonSchemaVersion version);

// JSON equality matching
stubFor(post(urlEqualTo("/api/users"))
    .withRequestBody(equalToJson(
        "{\"name\":\"John\",\"email\":\"john@example.com\"}", 
        true, // ignore array order
        true  // ignore extra elements
    ))
    .willReturn(aResponse().withStatus(201)));

// JSONPath matching
stubFor(post(urlEqualTo("/api/orders"))
    .withRequestBody(matchingJsonPath("$.items[?(@.price > 100)]"))
    .withRequestBody(matchingJsonPath("$.customer.email", 
        matching(".*@company\\.com")))
    .willReturn(aResponse().withStatus(201)));

// JSON Schema validation
String userSchema = """
    {
      "type": "object",
      "properties": {
        "name": {"type": "string"},
        "age": {"type": "number", "minimum": 0}
      },
      "required": ["name", "age"]
    }
    """;

stubFor(post(urlEqualTo("/api/users"))
    .withRequestBody(matchingJsonSchema(userSchema))
    .willReturn(aResponse().withStatus(201)));

/**
 * XML content matching methods
 */
// XML Equality Matching
/** Basic XML equality */
static StringValuePattern equalToXml(String xml);

/** XML equality with placeholder support */
static StringValuePattern equalToXml(String xml, boolean enablePlaceholders);

// XPath Expression Matching
/** Simple XPath expression matching */
static StringValuePattern matchingXPath(String xpath);

/** XPath with value pattern matching */
static StringValuePattern matchingXPath(String xpath, StringValuePattern valuePattern);

/** XPath with namespace context */
static StringValuePattern matchingXPath(String xpath, Map<String, String> namespaces);

/** XPath with namespaces and value pattern */
static StringValuePattern matchingXPath(String xpath, Map<String, String> namespaces, StringValuePattern valuePattern);

// XML equality matching
stubFor(post(urlEqualTo("/api/soap"))
    .withRequestBody(equalToXml(
        "<soap:Envelope><soap:Body><getUserRequest><userId>123</userId></getUserRequest></soap:Body></soap:Envelope>",
        true // enable placeholders
    ))
    .willReturn(aResponse().withStatus(200)));

// XPath matching
Map<String, String> namespaces = Map.of(
    "soap", "http://schemas.xmlsoap.org/soap/envelope/",
    "usr", "http://example.com/user"
);

stubFor(post(urlEqualTo("/api/soap"))
    .withRequestBody(matchingXPath("//usr:getUserRequest/usr:userId", namespaces, matching("[0-9]+")))
    .willReturn(aResponse().withStatus(200)));

/**
 * Date and time matching methods
 */
// Exact Date Matching
/** Match exact date/time from string */
static StringValuePattern equalToDateTime(String dateTimeSpec);

/** Match exact date/time from ZonedDateTime */
static StringValuePattern equalToDateTime(ZonedDateTime dateTime);

/** Match exact date/time from LocalDateTime */
static StringValuePattern equalToDateTime(LocalDateTime dateTime);

// Before Date Matching
/** Match dates before specified time */
static StringValuePattern before(String dateTimeSpec);

/** Match dates before ZonedDateTime */
static StringValuePattern before(ZonedDateTime dateTime);

/** Match dates before LocalDateTime */
static StringValuePattern before(LocalDateTime dateTime);

/** Match dates before current time */
static StringValuePattern beforeNow();

// After Date Matching
/** Match dates after specified time */
static StringValuePattern after(String dateTimeSpec);

/** Match dates after ZonedDateTime */
static StringValuePattern after(ZonedDateTime dateTime);

/** Match dates after LocalDateTime */
static StringValuePattern after(LocalDateTime dateTime);

/** Match dates after current time */
static StringValuePattern afterNow();

// Current Time Matching
/** Match current time (within reasonable tolerance) */
static StringValuePattern isNow();

// Date/time matching in headers or body
stubFor(post(urlEqualTo("/api/bookings"))
    .withHeader("X-Booking-Date", after("2024-01-01T00:00:00Z"))
    .withHeader("X-Expiry-Date", beforeNow())
    .withRequestBody(matchingJsonPath("$.timestamp", isNow()))
    .willReturn(aResponse().withStatus(201)));

// Date range matching
stubFor(get(urlEqualTo("/api/events"))
    .withQueryParam("startDate", after("2024-01-01"))
    .withQueryParam("endDate", before("2024-12-31"))
    .willReturn(aResponse().withStatus(200)));

/**
 * Multipart request matching
 */
interface MultipartValuePatternBuilder {
    /** Set part name */
    MultipartValuePatternBuilder withName(String name);
    
    /** Set filename pattern */
    MultipartValuePatternBuilder withFileName(StringValuePattern filenamePattern);
    
    /** Add header pattern */
    MultipartValuePatternBuilder withHeader(String name, StringValuePattern headerPattern);
    
    /** Add body content pattern */
    MultipartValuePatternBuilder withBody(ContentPattern<?> bodyPattern);
    
    /** Build multipart pattern */
    MultipartValuePattern build();
}

class MultipartValuePattern {
    enum MatchingType { ALL, ANY }
    
    String getName();
    StringValuePattern getFilename();
    Map<String, MultiValuePattern> getHeaders();
    List<ContentPattern<?>> getBodyPatterns();
    MatchingType getMatchingType();
    boolean isMatchAny();
    boolean isMatchAll();
}

// Multipart file upload matching
stubFor(post(urlEqualTo("/api/upload"))
    .withMultipartRequestBody(
        aMultipart()
            .withName("file")
            .withFileName(matching(".*\\.pdf"))
            .withHeader("Content-Type", equalTo("application/pdf"))
            .withBody(binaryEqualTo(expectedFileContent))
    )
    .willReturn(aResponse().withStatus(200)));

/**
 * Custom request matching interfaces
 */
interface RequestMatcherExtension extends Extension {
    /** Match request with custom logic */
    MatchResult match(Request request, Parameters parameters);
}

abstract class RequestMatcher extends NamedValueMatcher<Request> {
    /** Constructor with matcher name */
    protected RequestMatcher(String name);
}

class CustomMatcherDefinition {
    /** Create custom matcher definition */
    CustomMatcherDefinition(String name, Parameters parameters);
    
    String getName();
    Parameters getParameters();
}