Package net.ygbstudio.jbrave.api.builders

Class BraveImageQuery

java.lang.Object

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

net.ygbstudio.jbrave.api.builders.BraveImageQuery

All Implemented Interfaces:

BraveQueryBuilder<BraveImageQuery,ImageSearchApiResponse>

public final class BraveImageQuery
extends AbstractQueryUrlBuilder<BraveImageQuery>
implements BraveQueryBuilder<BraveImageQuery,ImageSearchApiResponse>

A builder for constructing Brave Image Search API queries.

This class is specifically designed for constructing Brave Image Search API queries, and 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 stateful, reusable builder intended for single-threaded use.

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

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	BraveImageQuery.BraveRequestBuilder

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 BraveImageQuery	builder()	Returns a new instance of BraveImageQuery
BraveImageQuery	count(int count)	Adds the count option to the URL query.
<T extends CountryIdentifier> BraveImageQuery	country(T country)	Adds the country option to the URL query.
BraveImageQuery	execute()	Executes the request and returns response of string.
@NotNull Optional<HttpResponse<String>>	getHttpResponse()	Returns the current HTTP response as an Optional.
Class<ImageSearchApiResponse>	getResponseType()	Returns the type of the API response.
boolean	hasExecuted()	Checks if the request has been executed.
<T extends LanguageIdentifier> BraveImageQuery	language(T searchLanguage)	Adds the search language option to the URL query.
BraveImageQuery	query(String queryTerm)	Adds a search term to the URL query.
BraveImageQuery	reset()	Clears the current instance of BraveImageQuery by resetting its state to its initial values.
BraveImageQuery	safeSearch(@NotNull SafeSearch safeSearch)	Adds a safe search option to the URL query.
BraveImageQuery	spellcheck(boolean spellCheck)	Adds the spell check option to the URL query.
HttpRequest	toHttpRequest()	Converts the current query to an HttpRequest instance.
BraveImageQuery	withHeaders(@NotNull Consumer<BraveImageQuery.BraveRequestBuilder> headers)	Sets the request headers using the provided consumer.
BraveImageQuery	withRetries(int maxRetries)	Sets the maximum number of retry attempts for rate-limited (HTTP 429) responses.
BraveImageQuery	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 BraveImageQuery builder()

Returns a new instance of BraveImageQuery

Returns:

a new instance of BraveImageQuery

query

public BraveImageQuery 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>
BraveImageQuery language(@NotNull
 T searchLanguage)

Adds the search language option to the URL query.

Parameters:

searchLanguage - the search language to set

Returns:

the current instance of the builder

See Also:

• SearchLanguage

safeSearch

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

country

public <T extends CountryIdentifier>
BraveImageQuery 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:

• Country

count

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

spellcheck

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

withToken

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

withHeaders

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

withRetries

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

execute

public BraveImageQuery execute()

Executes the request and returns response of string.

Specified by:

execute in interface BraveQueryBuilder<BraveImageQuery,ImageSearchApiResponse>

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<BraveImageQuery,ImageSearchApiResponse>

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<BraveImageQuery,ImageSearchApiResponse>

Returns:

the HttpRequest instance representing the current query

getResponseType

public Class<ImageSearchApiResponse> 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<BraveImageQuery,ImageSearchApiResponse>

Returns:

the class of the API response

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<BraveImageQuery,ImageSearchApiResponse>

Returns:

an Optional containing the current HTTP response.

reset

public BraveImageQuery reset()

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

Specified by:

reset in interface BraveQueryBuilder<BraveImageQuery,ImageSearchApiResponse>

Returns:

the current instance of BraveImageQuery