Package net.ygbstudio.jbrave.api.builders

Class BraveNewsQuery

java.lang.Object
net.ygbstudio.jbrave.core.builders.AbstractQueryUrlBuilder<BraveNewsQuery>
net.ygbstudio.jbrave.api.builders.BraveNewsQuery
All Implemented Interfaces:
BraveQueryBuilder<BraveNewsQuery,NewsSearchApiResponse>
public final class BraveNewsQuery extends AbstractQueryUrlBuilder<BraveNewsQuery> implements BraveQueryBuilder<BraveNewsQuery,NewsSearchApiResponse>
A builder for constructing Brave News API queries.

The builder is not thread-safe and is intended for single-threaded use. It is stateful and reusable: call reset() to clear its internal state before reusing it.

Builders are not intended to be instantiated directly; use the builder() factory method to create a new instance.

  • Method Details

    • builder

      public static BraveNewsQuery builder()
      Creates a new instance of BraveNewsQuery.
      Returns:
      a new instance of BraveNewsQuery

    • query

      public BraveNewsQuery query(String queryTerm)
      Adds a search term to the URL query. Maximum of 400 characters and 50 words.

      If a query is already present, subsequent calls are ignored. Only one query term is supported per search request.

      Parameters:
      queryTerm - the search term to add
      Returns:
      the current instance of the builder

    • language

      public <T extends LanguageIdentifier> BraveNewsQuery language(@NotNull T searchLanguage)
      Adds the search language option to the URL query.
      Type Parameters:
      T - the search language type
      Parameters:
      searchLanguage - the search language to set
      Returns:
      the current instance of the builder
      See Also:

    • market

      public <T extends RegionLocaleIdentifier> BraveNewsQuery market(@NotNull T uiLanguage)
      Adds the market option to the URL query.
      Type Parameters:
      T - the market locale type
      Parameters:
      uiLanguage - the market locale to set
      Returns:
      the current instance of the builder
      See Also:

    • safeSearch

      public BraveNewsQuery 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 the builder

    • count

      public BraveNewsQuery 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 BraveNewsQuery 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

    • spellcheck

      public BraveNewsQuery spellcheck(boolean spellcheck)
      Adds the spell check option to the URL query.
      Parameters:
      spellcheck - whether to enable spellcheck
      Returns:
      the current instance of the builder

    • freshness

      public BraveNewsQuery freshness(LocalDate startDate, LocalDate endDate)
      Adds a freshness option to the URL query representing a date range between the given start and end dates.
      Parameters:
      startDate - the start date of the freshness constraint
      endDate - the end date of the freshness constraint
      Returns:
      the current instance of the builder
      See Also:

    • freshness

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

    • extraSnippets

      public BraveNewsQuery 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

    • goggles

      public BraveNewsQuery 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 BraveNewsQuery

    • includeFetchMetadata

      public BraveNewsQuery 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

    • enableOperators

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

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

      Parameters:
      enableOperators - whether to enable the operators option
      Returns:
      the current instance of the builder

    • withSearchOperators

      @Contract("_ -> this") public BraveNewsQuery withSearchOperators(@NotNull @NotNull Consumer<SearchOperatorBuilder> operators)
      Adds search operations to the query term for advanced result filtering.

      Make sure to include the enableOperators(boolean) method to tell the API that you will be including operators in your query.

      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

    • withToken

      @Contract("_ -> this") public BraveNewsQuery 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 BraveNewsQuery

    • withHeaders

      @Contract("_ -> this") public BraveNewsQuery withHeaders(@NotNull @NotNull Consumer<VerticalHeaderBuilder<BraveVerticalRequest>> headers)
      Sets the request headers using the provided consumer.
      Parameters:
      headers - a consumer that receives a VerticalHeaderBuilder and applies the request's headers to it
      Returns:
      the current instance of BraveNewsQuery

    • withRetries

      public BraveNewsQuery 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 BraveNewsQuery

    • execute

      public BraveNewsQuery 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 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<BraveNewsQuery,NewsSearchApiResponse>
      Returns:
      the current builder instance

    • hasExecuted

      public 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.
      Specified by:
      hasExecuted in interface BraveQueryBuilder<BraveNewsQuery,NewsSearchApiResponse>
      Returns:
      true if the request has been executed, false otherwise

    • toHttpRequest

      public HttpRequest toHttpRequest()
      Converts the current query to an HttpRequest instance.
      Specified by:
      toHttpRequest in interface BraveQueryBuilder<BraveNewsQuery,NewsSearchApiResponse>
      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<BraveNewsQuery,NewsSearchApiResponse>
      Returns:
      an Optional containing the current HTTP response.

    • getResponseType

      public Class<NewsSearchApiResponse> 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<BraveNewsQuery,NewsSearchApiResponse>
      Returns:
      the class of the API response

    • reset

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