Package net.ygbstudio.jbrave.api.builders

Interface BraveQueryBuilder<T,E extends ApiResponse>

Type Parameters:
T - the type of the builder
E - the type of the API response
All Known Implementing Classes:
BraveImageQuery, BraveNewsQuery, BraveSpellcheckQuery, BraveSuggestQuery, BraveVideoQuery, BraveWebQuery
public sealed interface BraveQueryBuilder<T,E extends ApiResponse> permits BraveNewsQuery, BraveWebQuery, BraveImageQuery, BraveVideoQuery, BraveSuggestQuery, BraveSpellcheckQuery
An interface for Brave API query builders. The BraveQueryBuilder interface is implemented by all builders that build Brave API queries. It is parameterized by the type of the builder.

  • Method Details

    • getRateLimits

      default Optional<XRateLimit> getRateLimits()
      Returns the rate limit from the HTTP response.
      Returns:
      An optional containing the rate limit extracted from the HTTP response.

    • getRateLimitPolicy

      default Optional<XRateLimitPolicy> getRateLimitPolicy()
      Returns the rate limit policy from the HTTP response.
      Returns:
      An optional containing the rate limit policy extracted from the HTTP response.

    • getRateLimitRemaining

      default Optional<XRateLimitRemaining> getRateLimitRemaining()
      Returns the rate limit remaining from the HTTP response.
      Returns:
      An optional containing the rate limit remaining extracted from the HTTP response.

    • execute

      T execute()
      Executes the request and stores the response.

      This method is typically used to decouple request execution from response extraction.

      You can extract the response later with getHttpResponse(), getPOJO(), or getErrorPOJO().

      Note: This builder stores the response object internally and repeated calls to extraction methods will not trigger multiple requests; however, execute() will send a new request per method call.

      If the client added retries to the building chain, execute() will activate retry logic under the hood.

      By default, rate-limited (HTTP 429) responses are retried once after sleeping the server-provided rate limit reset window. Use withRetries(int) to change the policy; values less than or equal to zero retain the default (one retry).

      Returns:
      the current builder instance

    • hasExecuted

      boolean hasExecuted()
      Checks if the request has been executed. Precisely, it will tell the caller whether the builder has an existing (complete) request in it or not.
      Returns:
      true if the request has been executed, false otherwise

    • toHttpRequest

      HttpRequest toHttpRequest()
      Converts the current query to an HttpRequest instance.
      Returns:
      the HttpRequest instance representing the current query

    • getResponseType

      Class<E> getResponseType()
      Returns the type of the API response. The class returned by this method is the class of the concrete implementation of ApiResponse that this builder is expected to produce as a result of its query.
      Returns:
      the class of the API response

    • getPOJO

      default Optional<E> getPOJO()
      Converts the current response to a POJO instance of BraveQueryBuilder if the status code of the response is 200.

      If you get an empty optional with this method, it is possible that the request failed with an error code. Use getErrorPOJO() to get the error response object and use it in any error handling strategy. If you want to inspect the raw HttpResponse object, you can always use getHttpResponse().

      Note: Calling this method will execute the request and deserialize it. Once a request has been executed, this builder stores it in an internal field, so you can call this method and the ones mentioned above without having to send another request to the API.

      Returns:
      an Optional containing the current response as a POJO instance of BraveQueryBuilder, or an empty Optional if the response status code is not 200

    • getErrorPOJO

      default Optional<ErrorResponse> getErrorPOJO()
      Converts the current response to a POJO instance of ErrorResponse if the status code of the response is not 200.

      If you get an empty optional with this method, it is possible that the request was successful. Use getPOJO() to get the response object and use it in any success handling strategy. If you want to inspect the raw HttpResponse object, you can always use getHttpResponse().

      Calling this method will execute the request and deserialize it. Once a request has been executed, this builder stores it in an internal field, so you can call this method and the ones mentioned above without having to send another request to the API.

      Returns:
      an Optional containing the current response as a POJO instance of ErrorResponse, or an empty Optional if the response status code is 200

    • getEitherPOJO

      default Optional<ApiResponse> getEitherPOJO()
      Converts the current response to a POJO instance of WebSearchApiResponse if the status code of the response is 200. If the status code is not 200, it attempts to deserialize the response body into an ErrorResponse object. This is particularly useful if you want to check the success of your request with an instanceof check and then handle it as you like depending on what ApiResponse implementation you get.

      Calling this method will execute the request and deserialize it. Once a request has been executed, this builder stores it in an internal field, so you can call this method and the ones mentioned above without having to send another request to the API.

      Returns:
      an Optional containing the current response as a POJO instance of either WebSearchApiResponse or ErrorResponse, or an empty Optional if the response status code is neither 200 nor any other expected error code

    • getHttpResponse

      Optional<HttpResponse<String>> getHttpResponse()
      Returns the current HTTP response as an Optional.

      If the request has not been executed, this method will execute the request and return the HttpResponse.

      Returns:
      an Optional containing the current HTTP response.

    • toURI

      URI toURI()
      Converts the URL query to a URI.
      Returns:
      The URI representation of the URL query.

    • reset

      T reset()
      Clears the builder by resetting it to its initial state.

      This method is used to reset the builder to its initial state before adding any options.

      Returns:
      The current instance of the builder.