Package net.ygbstudio.jbrave.api.builders

Class BraveWebQuery

java.lang.Object
net.ygbstudio.jbrave.core.builders.AbstractQueryUrlBuilder<BraveWebQuery>
net.ygbstudio.jbrave.api.builders.BraveWebQuery
All Implemented Interfaces:
BraveQueryBuilder<BraveWebQuery,WebSearchApiResponse>
public final class BraveWebQuery extends AbstractQueryUrlBuilder<BraveWebQuery> implements BraveQueryBuilder<BraveWebQuery,WebSearchApiResponse>
A builder class for constructing Brave Web search queries.

This class provides a fluent API for constructing Brave Web search queries. The builder allows clients to specify various options such as the search term, the number of results to return, the offset, the units in which to display the results, and more.

The builder is not thread-safe and not intended to be instantiated directly, instead use the builder() method to create a new instance of the builder. Also note that this builder is a stateful, reusable builder intended for single-threaded use.

Method reset() will clear the internal state of the builder and must be called before reusing.

  • Method Details

    • builder

      @Contract(" -> new") @NotNull public static @NotNull BraveWebQuery builder()
      Creates a new instance of BraveWebQuery with an empty URL query.
      Returns:
      A new instance of BraveWebQuery.

    • query

      public BraveWebQuery query(String queryTerm)
      Adds a search term to the URL query.
      Parameters:
      queryTerm - The search term to add.
      Returns:
      The current instance of the builder.

    • count

      public BraveWebQuery count(int count)
      Adds the count option to the URL query.
      Parameters:
      count - The number of results to return.
      Returns:
      The current instance of the builder.

    • offset

      public BraveWebQuery offset(int offset)
      Adds the offset option to the URL query.
      Parameters:
      offset - The number of results to skip.
      Returns:
      The current instance of the builder.

    • textDecorations

      public BraveWebQuery textDecorations(boolean textDecorations)
      Adds the text_decorations option to the URL query.
      Parameters:
      textDecorations - Whether to include text decorations in the results.
      Returns:
      The current instance of the builder.

    • spellCheck

      public BraveWebQuery spellCheck(boolean spellCheck)
      Adds the spellcheck option to the URL query.
      Parameters:
      spellCheck - Whether to enable spellcheck.
      Returns:
      The current instance of the builder.

    • extraSnippets

      public BraveWebQuery extraSnippets(boolean extraSnippets)
      Adds the extra_snippets option to the URL query.
      Parameters:
      extraSnippets - Whether to include extra snippets in the results.
      Returns:
      The current instance of the builder.

    • summary

      public BraveWebQuery summary(boolean summary)
      Adds the summary option to the URL query.
      Parameters:
      summary - Whether to include a summary in the results.
      Returns:
      The current instance of the builder.

    • enableOperators

      public BraveWebQuery enableOperators()
      Adds the operators option to the URL query.

      This option tells the API to read search operators from the query term.

      Returns:
      The current instance of the builder.

    • withOperators

      @Contract("_ -> this") public BraveWebQuery withOperators(@NotNull @NotNull Consumer<SearchOperatorBuilder> operators)
      Adds search operations to the query term for advanced result filtering.
      Parameters:
      operators - A consumer that accepts a SearchOperatorBuilder instance and populates it with operators. The built SearchOperatorBuilder instance will be used to construct the operators string.
      Returns:
      The current instance of the builder.

    • country

      public <T extends CountryIdentifier> BraveWebQuery country(@NotNull T country)
      Adds the country option to the URL query.
      Parameters:
      country - The country identifier to set.
      Returns:
      The current instance of the builder.
      See Also:

    • market

      public <T extends RegionLocaleIdentifier> BraveWebQuery market(@NotNull T regionLocale)
      Adds the market option to the URL query.
      Parameters:
      regionLocale - The region locale identifier to set.
      Returns:
      The current instance of the builder.
      See Also:

    • language

      public <T extends LanguageIdentifier> BraveWebQuery language(@NotNull T languageIdentifier)
      Adds the language option to the URL query.
      Parameters:
      languageIdentifier - The language identifier to set.
      Returns:
      The current instance of the builder.
      See Also:

    • enableRichCallback

      public BraveWebQuery enableRichCallback(boolean enableRichCallback)
      Adds the enable_rich_callback option to the URL query.
      Parameters:
      enableRichCallback - Whether to enable rich callback.
      Returns:
      The current instance of the builder.

    • units

      public BraveWebQuery units(@NotNull @NotNull Units units)
      Adds the units option to the URL query.
      Parameters:
      units - The units to set.
      Returns:
      The current instance of the builder.
      See Also:

    • freshness

      public BraveWebQuery freshness(@NotNull @NotNull Freshness freshness)
      Adds a freshness option to the URL query using an existing Freshness instance.
      Parameters:
      freshness - a Freshness describing the freshness constraint
      Returns:
      the current instance of BraveWebQuery
      See Also:

    • freshness

      public BraveWebQuery freshness(LocalDate startDate, LocalDate endDate)
      Adds a freshness option to the URL query representing a date range.
      Parameters:
      startDate - the start date of the freshness range
      endDate - the end date of the freshness range
      Returns:
      the current instance of BraveWebQuery
      See Also:

    • safeSearch

      public BraveWebQuery safeSearch(@NotNull @NotNull SafeSearch safeSearch)
      Adds a safe search option to the URL query.
      Parameters:
      safeSearch - a SafeSearch enum value specifying the safe search level
      Returns:
      the current instance of BraveWebQuery
      See Also:

    • resultFilters

      public BraveWebQuery resultFilters(Set<ResultFilter> resultFilterList)
      Adds result filters to the URL query.
      Parameters:
      resultFilterList - a set of ResultFilter elements to apply; may be empty but not null
      Returns:
      the current instance of BraveWebQuery
      See Also:

    • goggles

      public BraveWebQuery goggles(URI gogglesUri)
      Adds a goggles URL option to the URL query.
      Parameters:
      gogglesUri - the URI pointing to a goggles resource to use for the query
      Returns:
      the current instance of BraveWebQuery

    • includeFetchMetadata

      public BraveWebQuery includeFetchMetadata(boolean includeFetchMetadata)
      Adds the include_fetch_metadata option to the URL query.
      Parameters:
      includeFetchMetadata - Whether to include fetch metadata in the results.
      Returns:
      the current instance of the builder

    • withToken

      @Contract("_ -> this") public BraveWebQuery withToken(@NotNull @NotNull ClientInfo clientInfo)
      Sets the subscription token header using the provided ClientInfo instance.
      Parameters:
      clientInfo - the ClientInfo instance containing the subscription token
      Returns:
      the current instance of BraveWebQuery

    • withHeaders

      @Contract("_ -> this") public BraveWebQuery withHeaders(@NotNull @NotNull Consumer<BraveWebQuery.BraveRequestBuilder> headers)
      Sets the request headers using the provided consumer.
      Parameters:
      headers - a consumer that accepts an inner request builder instance and applies preconfigured headers to it via helper methods.
      Returns:
      the current instance of BraveWebQuery

    • withRetries

      public BraveWebQuery withRetries(int maxRetries)
      Sets the maximum number of retry attempts for rate-limited (HTTP 429) responses.

      Values less than or equal to zero fall back to the default retry policy (one retry). Retries sleep for the server-provided rate limit reset window before each attempt.

      Parameters:
      maxRetries - the maximum number of retry attempts for rate-limited responses
      Returns:
      the current instance of BraveWebQuery

    • execute

      public BraveWebQuery execute()
      Description copied from interface: BraveQueryBuilder
      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 BraveQueryBuilder.getHttpResponse(), BraveQueryBuilder.getPOJO(), or BraveQueryBuilder.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).

      Specified by:
      execute in interface BraveQueryBuilder<BraveWebQuery,WebSearchApiResponse>
      Returns:
      the current builder instance

    • hasExecuted

      public boolean hasExecuted()
      Description copied from interface: BraveQueryBuilder
      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.
      Specified by:
      hasExecuted in interface BraveQueryBuilder<BraveWebQuery,WebSearchApiResponse>
      Returns:
      true if the request has been executed, false otherwise

    • toHttpRequest

      public HttpRequest toHttpRequest()
      Description copied from interface: BraveQueryBuilder
      Converts the current query to an HttpRequest instance.
      Specified by:
      toHttpRequest in interface BraveQueryBuilder<BraveWebQuery,WebSearchApiResponse>
      Returns:
      the HttpRequest instance representing the current query

    • getHttpResponse

      @NotNull public @NotNull 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.

      Specified by:
      getHttpResponse in interface BraveQueryBuilder<BraveWebQuery,WebSearchApiResponse>
      Returns:
      an Optional containing the current HTTP response.

    • getResponseType

      public Class<WebSearchApiResponse> getResponseType()
      Description copied from interface: BraveQueryBuilder
      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.
      Specified by:
      getResponseType in interface BraveQueryBuilder<BraveWebQuery,WebSearchApiResponse>
      Returns:
      the class of the API response

    • reset

      public BraveWebQuery reset()
      Clears the current instance of BraveWebQuery by resetting its state to its initial values.
      Specified by:
      reset in interface BraveQueryBuilder<BraveWebQuery,WebSearchApiResponse>
      Returns:
      the current instance of BraveWebQuery