Package net.ygbstudio.jbrave.core.builders

Class AbstractQueryUrlBuilder<T extends AbstractQueryUrlBuilder<T>>

java.lang.Object
net.ygbstudio.jbrave.core.builders.AbstractQueryUrlBuilder<T>
Type Parameters:
T - The concrete builder class.
Direct Known Subclasses:
BraveImageQuery, BraveNewsQuery, BraveSpellcheckQuery, BraveSuggestQuery, BraveVideoQuery, BraveWebQuery
public abstract class AbstractQueryUrlBuilder<T extends AbstractQueryUrlBuilder<T>> extends Object
Abstract base class for building Brave API queries.

Implementations of this class should call addInstanceVertical(SearchVertical) before building, and initialize the builder with clear() before adding options.

The builder will throw AbsentSearchVerticalException if the vertical is not added before building. The builder will also throw UninitializedBuilderException if the builder is not cleared before adding options.

Suggested implementation of factory method: 

    public static BraveWebQuery builder() {
    return new BraveWebQuery().addInstanceVertical(BraveResource.WEB).clear();
  }

The builder will throw AbsentSearchQueryException if the query string is not present in the URL query.

Note: This builder enforces strict URI construction invariants. Subclasses must not override core lifecycle methods. Extension is intended via additional fluent APIs only.

  • Field Details

  • Constructor Details

    • AbstractQueryUrlBuilder

      public AbstractQueryUrlBuilder()

  • Method Details

    • self

      protected final T self()
      Returns the current instance of the builder.

      The cast is safe because subclasses follow the self-referential generic pattern used by this base class.

      Returns:
      Current instance of the builder.

    • optionMissing

      protected final boolean optionMissing(@NotNull @NotNull SearchOption option)
      Checks if the given search option is already present in the URL query.
      Parameters:
      option - The search option to check.
      Returns:
      true if the option is not already present in the URL query, false otherwise.

    • queryMissing

      protected final boolean queryMissing()
      Checks if the query prompt is already present in the URL query.

      The query prompt is the string "q=".

      Returns:
      true if the query prompt is not already present in the URL query, false otherwise.

    • isValidQuery

      protected final boolean isValidQuery(@NotNull @NotNull String queryTerm)
      Checks if the given query term is valid.

      A query term is valid if it contains fewer than or exactly 400 characters and less than 50 words. Both limits are enforced conjunctively, in accordance with the Brave Search API documentation.

      Parameters:
      queryTerm - The query term to check.
      Returns:
      true if the query term is valid, false otherwise.

    • addInstanceVertical

      protected final T addInstanceVertical(@NotNull @NotNull SearchVertical vertical)
      Adds a vertical to the current builder instance so that it can be reused.

      This method is typically called when the builder is instantiated
      since methods like clear() depend on an initialized vertical field.

      Parameters:
      vertical - The vertical of builder instance.
      Returns:
      The current instance of the builder.

    • addQueryTerm

      protected final T addQueryTerm(String queryTerm, boolean appendOperator)
      Adds a query term to the URL query and encodes it using UTF-8. If appendOperator is true, the new queryTerm will append to the existing query term in the builder as a search operator, if any.
      Parameters:
      queryTerm - The query term to add.
      appendOperator - Whether or not to interpret queryTerm as search operator and append it to the existing term or save it for later concatenation.
      Returns:
      The current instance of the builder.

    • addOption

      protected final <U> T addOption(@NotNull @NotNull SearchOption option, U value)
      Adds an option to the URL query.
      Type Parameters:
      U - The type of the option value.
      Parameters:
      option - The option to add.
      value - The value of the option.
      Returns:
      The current instance of the builder.

    • addOptionCarrier

      protected final <V> T addOptionCarrier(@NotNull @NotNull SearchOptionCarrier<V> optionCarrier)
      Adds a search option carrier to the URL query.
      Type Parameters:
      V - The type of the option value.
      Parameters:
      optionCarrier - The option carrier to add.
      Returns:
      The current instance of the builder.

    • clear

      public final T clear()
      Clears the URL query by resetting the internal builder to an empty state.
      Returns:
      The current instance of the builder.

    • build

      protected final String build()
      Builds the final URL query.
      Returns:
      The final URL query.

    • toURI

      @Contract(" -> new") @NotNull public final @NotNull URI toURI()
      Converts the URL query to a URI.
      Returns:
      The URI representation of the URL query.