Module agentforge4j.tools.http
Package com.agentforge4j.tools.http

Class HttpEndpointDefinition.Builder

java.lang.Object
com.agentforge4j.tools.http.HttpEndpointDefinition.Builder
Enclosing class:
HttpEndpointDefinition
public static final class HttpEndpointDefinition.Builder extends Object
Fluent builder for HttpEndpointDefinition. Each with* method sets exactly one field, so adjacent same-typed fields (the several String and Map components) can no longer transpose silently at a call site the way they can with the 16-argument positional constructor. Validation is deferred to build(), which delegates to the canonical constructor.

  • Method Details

    • withCapability

      public HttpEndpointDefinition.Builder withCapability(String capability)
      Sets the logical capability id.
      Parameters:
      capability - <domain>.<verb_object> id, lowercase snake_case; required
      Returns:
      this builder

    • withDisplayName

      public HttpEndpointDefinition.Builder withDisplayName(String displayName)
      Sets the human-readable display name.
      Parameters:
      displayName - display name, or null
      Returns:
      this builder

    • withDescription

      public HttpEndpointDefinition.Builder withDescription(String description)
      Sets the human-readable description.
      Parameters:
      description - description, or null
      Returns:
      this builder

    • withMutating

      public HttpEndpointDefinition.Builder withMutating(boolean mutating)
      Sets whether invoking this endpoint may mutate remote state. Never calling this method leaves mutating at its default, true — the highest safe risk — matching the wire default an HTTP_TOOL integration config applies when it omits the field.
      Parameters:
      mutating - mutating signal; required, no "unset" value exists at this API surface
      Returns:
      this builder

    • withMethod

      public HttpEndpointDefinition.Builder withMethod(HttpMethod method)
      Sets the HTTP method.
      Parameters:
      method - HTTP method; required
      Returns:
      this builder

    • withUrlTemplate

      public HttpEndpointDefinition.Builder withUrlTemplate(String urlTemplate)
      Sets the absolute URL template.
      Parameters:
      urlTemplate - absolute http/https URL with {name} placeholders; required
      Returns:
      this builder

    • withInputSchema

      public HttpEndpointDefinition.Builder withInputSchema(com.fasterxml.jackson.databind.JsonNode inputSchema)
      Sets the JSON Schema for the arguments.
      Parameters:
      inputSchema - input JSON Schema; required
      Returns:
      this builder

    • withOutputSchema

      public HttpEndpointDefinition.Builder withOutputSchema(com.fasterxml.jackson.databind.JsonNode outputSchema)
      Sets the JSON Schema for the result.
      Parameters:
      outputSchema - output JSON Schema, or null if unknown
      Returns:
      this builder

    • withQueryArgs

      public HttpEndpointDefinition.Builder withQueryArgs(Set<String> queryArgs)
      Sets the argument names routed to the query string.
      Parameters:
      queryArgs - query argument names; null (or never calling this method) becomes empty
      Returns:
      this builder

    • withBodyMode

      public HttpEndpointDefinition.Builder withBodyMode(BodyMode bodyMode)
      Sets how the request body is formed from the leftover arguments.
      Parameters:
      bodyMode - body mode; required
      Returns:
      this builder

    • withStaticHeaders

      public HttpEndpointDefinition.Builder withStaticHeaders(Map<String,String> staticHeaders)
      Sets the fixed, non-secret headers.
      Parameters:
      staticHeaders - static headers; null (or never calling this method) becomes empty
      Returns:
      this builder

    • withSecretHeaders

      public HttpEndpointDefinition.Builder withSecretHeaders(Map<String,String> secretHeaders)
      Sets the header name to secret-reference key mapping.
      Parameters:
      secretHeaders - secret headers; null (or never calling this method) becomes empty
      Returns:
      this builder

    • withTimeout

      public HttpEndpointDefinition.Builder withTimeout(Duration timeout)
      Sets the endpoint-level timeout ceiling.
      Parameters:
      timeout - timeout ceiling, or null; restricts, never expands
      Returns:
      this builder

    • withMaxRetries

      public HttpEndpointDefinition.Builder withMaxRetries(Integer maxRetries)
      Sets the endpoint-level retry cap. Never calling this method leaves maxRetries null (unset).
      Parameters:
      maxRetries - retry cap, or null for unset; must be >= 0 when set, restricts, never expands
      Returns:
      this builder

    • withRetryNonIdempotent

      public HttpEndpointDefinition.Builder withRetryNonIdempotent(boolean retryNonIdempotent)
      Sets whether to opt in to retrying POST/PATCH.
      Parameters:
      retryNonIdempotent - opt-in flag; meaningless on other methods
      Returns:
      this builder

    • withMaxResponseBytes

      public HttpEndpointDefinition.Builder withMaxResponseBytes(Long maxResponseBytes)
      Sets the response body read cap.
      Parameters:
      maxResponseBytes - read cap, or null to use the provider default
      Returns:
      this builder

    • build

      public HttpEndpointDefinition build()
      Builds the validated HttpEndpointDefinition.
      Returns:
      immutable endpoint definition; never null
      Throws:
      IllegalArgumentException - if a required field was not set, or a set field is invalid