Package net.ygbstudio.jbrave.api.builders

Class BraveVideoQuery

java.lang.Object
net.ygbstudio.jbrave.core.builders.AbstractQueryUrlBuilder<BraveVideoQuery>
net.ygbstudio.jbrave.api.builders.BraveVideoQuery
All Implemented Interfaces:
BraveQueryBuilder<BraveVideoQuery,VideoSearchApiResponse>
public final class BraveVideoQuery extends AbstractQueryUrlBuilder<BraveVideoQuery> implements BraveQueryBuilder<BraveVideoQuery,VideoSearchApiResponse>
A builder class for building Brave Video API queries.

This class is not intended to be instantiated directly, instead use the builder() method to create a new instance of the builder.

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

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

    • query

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

    • language

      public <T extends LanguageIdentifier> BraveVideoQuery language(@NotNull T searchLanguage)
      Adds the search language option 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:
      searchLanguage - the search language to set
      Returns:
      the current instance of the builder
      See Also:

    • market

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

    • safeSearch

      public BraveVideoQuery 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
      See Also:

    • count

      public BraveVideoQuery 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 BraveVideoQuery 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 BraveVideoQuery 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 BraveVideoQuery 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 BraveVideoQuery
      See Also:

    • freshness

      public BraveVideoQuery 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 BraveVideoQuery
      See Also:

    • includeFetchMetadata

      public BraveVideoQuery 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 BraveVideoQuery 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.

    • withToken

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

    • withHeaders

      @Contract("_ -> this") public BraveVideoQuery withHeaders(@NotNull @NotNull Consumer<BraveVideoQuery.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 BraveVideoQuery

    • withOperators

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

    • withRetries

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

    • execute

      public BraveVideoQuery execute()
      Executes the request and returns response of string.
      Specified by:
      execute in interface BraveQueryBuilder<BraveVideoQuery,VideoSearchApiResponse>
      Returns:
      an optional response to the request

    • 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<BraveVideoQuery,VideoSearchApiResponse>
      Returns:
      true if the request has been executed, false otherwise

    • getResponseType

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

    • toHttpRequest

      public HttpRequest toHttpRequest()
      Converts the current query to an HttpRequest instance.
      Specified by:
      toHttpRequest in interface BraveQueryBuilder<BraveVideoQuery,VideoSearchApiResponse>
      Returns:
      the HttpRequest instance representing the current query

    • getHttpResponse

      @NotNull public @NotNull Optional<HttpResponse<String>> getHttpResponse()
      Returns the current HTTP response as an Optional.
      Specified by:
      getHttpResponse in interface BraveQueryBuilder<BraveVideoQuery,VideoSearchApiResponse>
      Returns:
      an Optional containing the current HTTP response, or an empty Optional if there is no current response.

    • reset

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