Package net.ygbstudio.jbrave.api.builders

Class BraveSuggestQuery

java.lang.Object

net.ygbstudio.jbrave.core.builders.AbstractQueryUrlBuilder<BraveSuggestQuery>

net.ygbstudio.jbrave.api.builders.BraveSuggestQuery

All Implemented Interfaces:

BraveQueryBuilder<BraveSuggestQuery,SuggestSearchApiResponse>

public final class BraveSuggestQuery
extends AbstractQueryUrlBuilder<BraveSuggestQuery>
implements BraveQueryBuilder<BraveSuggestQuery,SuggestSearchApiResponse>

A builder for constructing Brave Suggest 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.

Field Summary

Fields inherited from class net.ygbstudio.jbrave.core.builders.AbstractQueryUrlBuilder

delayedOperators, optionTracker, QUERY_PROMPT, urlEnd, urlStart

Method Summary

Modifier and Type	Method	Description
static BraveSuggestQuery	builder()	Creates a new instance of BraveSuggestQuery.
BraveSuggestQuery	count(int count)	Adds the count option to the URL query.
<T extends CountryIdentifier> BraveSuggestQuery	country(T country)	Adds the country option to the URL query.
BraveSuggestQuery	execute()	Executes the request and stores the response.
@NotNull Optional<HttpResponse<String>>	getHttpResponse()	Returns the current HTTP response as an Optional.
Class<SuggestSearchApiResponse>	getResponseType()	Returns the type of the API response.
boolean	hasExecuted()	Checks if the request has been executed.
<T extends LanguageIdentifier> BraveSuggestQuery	language(T searchLanguage)	Adds the search language option to the URL query.
BraveSuggestQuery	query(String queryTerm)	Adds a search term to the URL query.
BraveSuggestQuery	reset()	Clears the current instance of BraveSuggestQuery by resetting its state to its initial values.
BraveSuggestQuery	rich(boolean rich)	Adds the rich option to the URL query.
HttpRequest	toHttpRequest()	Converts the current query to an HttpRequest instance.
BraveSuggestQuery	withHeaders(@NotNull Consumer<VerticalHeaderBuilder<BraveVerticalRequest>> headers)	Sets the request headers using the provided consumer.
BraveSuggestQuery	withRetries(int maxRetries)	Sets the maximum number of retry attempts for rate-limited (HTTP 429) responses.
BraveSuggestQuery	withToken(@NotNull ClientInfo clientInfo)	Sets the subscription token header using the provided ClientInfo instance.

Methods inherited from class net.ygbstudio.jbrave.core.builders.AbstractQueryUrlBuilder

addInstanceVertical, addOption, addOptionCarrier, addQueryTerm, build, clear, isValidQuery, optionMissing, queryMissing, self, toURI

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface net.ygbstudio.jbrave.api.builders.BraveQueryBuilder

getEitherPOJO, getErrorPOJO, getPOJO, getRateLimitPolicy, getRateLimitRemaining, getRateLimits, toURI

Method Details

builder

public static BraveSuggestQuery builder()

Creates a new instance of BraveSuggestQuery.

Returns:

a new instance of BraveSuggestQuery

query

public BraveSuggestQuery 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>
BraveSuggestQuery 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:

• SearchLanguage

country

public <T extends CountryIdentifier>
BraveSuggestQuery country(@NotNull
 T country)

Adds the country option to the URL query.

Type Parameters:

T - the country type

Parameters:

country - the country identifier to set

Returns:

the current instance of the builder

See Also:

• Country

rich

public BraveSuggestQuery rich(boolean rich)

Adds the rich option to the URL query.

Parameters:

rich - whether to enable rich results

Returns:

the current instance of the builder

count

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

withToken

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

withHeaders

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

withRetries

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

execute

public BraveSuggestQuery 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<BraveSuggestQuery,SuggestSearchApiResponse>

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<BraveSuggestQuery,SuggestSearchApiResponse>

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<BraveSuggestQuery,SuggestSearchApiResponse>

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<BraveSuggestQuery,SuggestSearchApiResponse>

Returns:

an Optional containing the current HTTP response.

getResponseType

public Class<SuggestSearchApiResponse> 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<BraveSuggestQuery,SuggestSearchApiResponse>

Returns:

the class of the API response

reset

public BraveSuggestQuery reset()

Clears the current instance of BraveSuggestQuery by resetting its state to its initial values.

Specified by:

reset in interface BraveQueryBuilder<BraveSuggestQuery,SuggestSearchApiResponse>

Returns:

the current instance of BraveSuggestQuery