Package org.botblock.javabotblockapi.requests

## Class GetListAction

- java.lang.Object
- - org.botblock.javabotblockapi.requests.GetListAction

-     public class GetListAction
      extends Object

  Class used to perform GET actions on the `/api/lists` and `/api/lists/:id` endpoints.

  GET requests are cached for 2 minutes unless disabled through `GetListAction(true)`.

  Since:
    5.0.0

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `GetListAction.ApiField` | Enum containing the different API fields a bot list may have.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `GetListAction()` | Deprecated. This Constructor can no longer be used and will throw an `IllegalStateException` when used.
    `GetListAction​(boolean disableCache)` | Deprecated. This Constructor can no longer be used and will throw an `IllegalStateException` when used.
    `GetListAction​(boolean disableCache, String id)` | Constructor to get an instance of GetListAction.
    `GetListAction​(boolean disableCache, String userAgent, String id)` | Constructor to get the instance of GetListAction.
    `GetListAction​(String id)` | Constructor to get an instance of GetListAction.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `@Nullable String` | `getApiField​(String id, String site, GetListAction.ApiField field)` | Gets the name of the specified field.
    `@Nullable String` | `getApiField​(String id, Site site, GetListAction.ApiField field)` | Gets the name of the specified field.
    `@Nullable String` | `getBotWidgetUrl​(String id, String site)` | Gets the URL used to display a widget (custom image) of the bot.
    `@Nullable String` | `getBotWidgetUrl​(String id, Site site)` | Gets the URL used to display a widget (custom image) of the bot.
    `@Nullable String` | `getDescription​(String id, String site)` | Gets the description of the bot list.
    `@Nullable String` | `getDescription​(String id, Site site)` | Gets the description of the bot list.
    `@Nullable String` | `getDiscordInvite​(String id, String site)` | Gets the invite to the Discord of the bot list.
    `@Nullable String` | `getDiscordInvite​(String id, Site site)` | Gets the invite to the Discord of the bot list.
    `JSONArray` | `getFeatures​(String id, String site)` | Gets the features of the bot list.
    `JSONArray` | `getFeatures​(String id, Site site)` | Gets the features of the bot list.
    `JSONObject` | `getFilteredLists​(String id)` | Returns the filtered JSON of bot lists.
    `@Nullable String` | `getIcon​(String id, String site)` | Gets the URL displaying the current Icon of the bot list.
    `@Nullable String` | `getIcon​(String id, Site site)` | Gets the URL displaying the current Icon of the bot list.
    `String` | `getId​(String id, String site)` | Gets the id of the bot list.
    `String` | `getId​(String id, Site site)` | Gets the id of the bot list.
    `String` | `getLanguage​(String id, String site)` | Gets the primary language of the bot list.
    `String` | `getLanguage​(String id, Site site)` | Gets the primary language of the bot list.
    `JSONObject` | `getList​(String id, String site)` | Gets the information of a specific bot list.
    `JSONObject` | `getList​(String id, Site site)` | Gets the information of a specific bot list.
    `JSONObject` | `getLists​(String id)` | Gets the information about all the currently listed bot lists.
    `String` | `getName​(String id, String site)` | Gets the name of the bot list.
    `String` | `getName​(String id, Site site)` | Gets the name of the bot list.
    `@Nullable String` | `getOwners​(String id, String site)` | Gets the owners of a bot list.
    `@Nullable String` | `getOwners​(String id, Site site)` | Gets the owners of a bot list.
    `Integer` | `getTimeAdded​(String id, String site)` | Gets the UNIX timestamp of when the bot list was added to BotBlock as Integer.
    `Integer` | `getTimeAdded​(String id, Site site)` | Gets the UNIX timestamp of when the bot list was added to BotBlock as Integer.
    `String` | `getUrl​(String id, String site)` | Gets the URL for the bot list's website.
    `String` | `getUrl​(String id, Site site)` | Gets the URL for the bot list's website.
    `boolean` | `isDefunct​(String id, String site)` | Returns if the bot list is defunct.
    `boolean` | `isDefunct​(String id, Site site)` | Returns if the bot list is defunct.
    `boolean` | `isDiscordOnly​(String id, String site)` | Returns if the bot list is only for Discord bots.
    `boolean` | `isDiscordOnly​(String id, Site site)` | Returns if the bot list is only for Discord bots.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### GetListAction

          @Deprecated
          @DeprecatedSince(version="5.2.0")
          @PlannedRemoval(version="5.2.3")
          public GetListAction()

      Deprecated.
      This Constructor can no longer be used and will throw an `IllegalStateException` when used.
      Constructor to get an instance of GetListAction.

    - #### GetListAction

          @Deprecated
          @DeprecatedSince(version="5.2.0",
                           replacements={"GetListAction(String)","GetListAction(boolean, String)","GetListAction(boolean, String, String)"})
          @PlannedRemoval(version="5.2.3")
          public GetListAction​(boolean disableCache)

      Deprecated.
      This Constructor can no longer be used and will throw an `IllegalStateException` when used.
      Constructor to get an instance of GetListAction.
      Use this if you want to disable the caching of the GET requests.
      We do not recommend this without own caching/ratelimiting.
      Parameters:
        `disableCache` - Whether or not to disable caching. `true` means caching gets disabled!

    - #### GetListAction

          public GetListAction​(@Nonnull
                               String id)

      Constructor to get an instance of GetListAction.

      Using this constructor will set the following default values:

      - Cache: `Enabled`
      - User-Agent: `"JavaBotBlockAPI-0000/API_VERSION (Unknown; +https://jbba.dev) DBots/{id}"`
      Parameters:
        `id` - The id of the bot. This is required for the internal User-Agent.
      Throws:
        `NullPointerException` - When the provided id is empty.

    - #### GetListAction

          public GetListAction​(boolean disableCache,
                               @Nonnull
                               String id)

      Constructor to get an instance of GetListAction.
      This constructor allows you to disable the internal caching, by providing `true` as the first argument.

      Using this constructor will set the following default values:

      - User-Agent: `"JavaBotBlockAPI-0000/API_VERSION (Unknown; +https://jbba.dev) DBots/{id}"`
      Parameters:
        `disableCache` - If the cache should be disabled.
        `true` means the cache is disabled.
        `id` - The id of the bot. This is required for the internal User-Agent.
      Throws:
        `NullPointerException` - When the provided id is empty.

    - #### GetListAction

          public GetListAction​(boolean disableCache,
                               @Nonnull
                               String userAgent,
                               @Nonnull
                               String id)

      Constructor to get the instance of GetListAction.
      This constructor allows you to disable the internal caching, by providing `true` as the first argument and also set a own User-Agent for the requests by providing any String as the second argument.

      Note that you can provide `{id}` inside the userAgent to get it replaced with the provided id.

      Parameters:
        `disableCache` - If the cache should be disabled.
        `true` means the cache is disabled.
        `userAgent` - The Name that should be used as User-Agent.
        `id` - The id of the bot. This is required for the internal User-Agent.
      Throws:
        `NullPointerException` - When the provided userAgent or id is empty.

  - ### Method Detail

    - #### getApiField

          @Nullable
          public @Nullable String getApiField​(@Nonnull
                                              String id,
                                              @Nonnull
                                              Site site,
                                              @Nonnull
                                              GetListAction.ApiField field)

      Gets the name of the specified field. The returned String can either be a URL or a field name.
      Parameters:
        `id` - The id used for the cache.
        `site` - The `site` to get information from.
        `field` - The `API field` to get the value from.
      Returns:
        Possibly-null String containing either a URL or API field name.

    - #### getApiField

          @Nullable
          public @Nullable String getApiField​(@Nonnull
                                              String id,
                                              @Nonnull
                                              String site,
                                              @Nonnull
                                              GetListAction.ApiField field)

      Gets the name of the specified field. The returned String can either be a URL or a field name.
      Parameters:
        `id` - The id used for the cache.
        `site` - The `site` to get information from.
        `field` - The `API field` to get the value from.
      Returns:
        Possibly-null String containing either a URL or API field name.

    - #### getBotWidgetUrl

          @Nullable
          public @Nullable String getBotWidgetUrl​(@Nonnull
                                                  String id,
                                                  @Nonnull
                                                  Site site)

      Gets the URL used to display a widget (custom image) of the bot.
      Parameters:
        `id` - The id used for the cache.
        `site` - The `site` to get information from.
      Returns:
        Possibly-null String containing the URL used to display a widget.

    - #### getBotWidgetUrl

          @Nullable
          public @Nullable String getBotWidgetUrl​(@Nonnull
                                                  String id,
                                                  @Nonnull
                                                  String site)

      Gets the URL used to display a widget (custom image) of the bot.
      Parameters:
        `id` - The id used for the cache.
        `site` - The `site` to get information from.
      Returns:
        Possibly-null String containing the URL used to display a widget.

    - #### getDescription

          @Nullable
          public @Nullable String getDescription​(@Nonnull
                                                 String id,
                                                 @Nonnull
                                                 Site site)

      Gets the description of the bot list.
      Parameters:
        `id` - The id used for the cache.
        `site` - The `site` to get information from.
      Returns:
        Possibly-null String containing the description/tag line of the bot list.

    - #### getDescription

          @Nullable
          public @Nullable String getDescription​(@Nonnull
                                                 String id,
                                                 @Nonnull
                                                 String site)

      Gets the description of the bot list.
      Parameters:
        `id` - The id used for the cache.
        `site` - The `site` to get information from.
      Returns:
        Possibly-null String containing the description/tag line of the bot list.

    - #### getDiscordInvite

          @Nullable
          public @Nullable String getDiscordInvite​(@Nonnull
                                                   String id,
                                                   @Nonnull
                                                   Site site)

      Gets the invite to the Discord of the bot list.
      Parameters:
        `id` - The id used for the cache.
        `site` - The `site` to get information from.
      Returns:
        Possibly-null String containing the invite to the Discord of the bot list.

    - #### getDiscordInvite

          @Nullable
          public @Nullable String getDiscordInvite​(@Nonnull
                                                   String id,
                                                   @Nonnull
                                                   String site)

      Gets the invite to the Discord of the bot list.
      Parameters:
        `id` - The id used for the cache.
        `site` - The `site` to get information from.
      Returns:
        Possibly-null String containing the invite to the Discord of the bot list.

    - #### getFeatures

          public JSONArray getFeatures​(@Nonnull
                                       String id,
                                       @Nonnull
                                       Site site)

      Gets the features of the bot list.
      The listed features can be both positive and negative.
      Parameters:
        `id` - The id used for the cache.
        `site` - The `site` to get information from.
      Returns:
        Possibly-empty `JSONArray` containing the features of the bot list.

    - #### getFeatures

          public JSONArray getFeatures​(@Nonnull
                                       String id,
                                       @Nonnull
                                       String site)

      Gets the features of the bot list.
      The listed features can be both positive and negative.
      Parameters:
        `id` - The id used for the cache.
        `site` - The `site` to get information from.
      Returns:
        Possibly-empty `JSONArray` containing the features of the bot list.

    - #### getFilteredLists

          public JSONObject getFilteredLists​(@Nonnull
                                             String id)

      Returns the filtered JSON of bot lists.
      The filtered version only contains the `API fields` of the bot lists.
      Parameters:
        `id` - The id used for the cache.
      Returns:
        `JSONObject` containing the filtered information of the bot lists.

    - #### getIcon

          @Nullable
          public @Nullable String getIcon​(@Nonnull
                                          String id,
                                          @Nonnull
                                          Site site)

      Gets the URL displaying the current Icon of the bot list.
      Parameters:
        `id` - The id used for the cache.
        `site` - The `site` to get information from.
      Returns:
        Possibly-null String containing the Icon-URL of the bot list.

    - #### getIcon

          @Nullable
          public @Nullable String getIcon​(@Nonnull
                                          String id,
                                          @Nonnull
                                          String site)

      Gets the URL displaying the current Icon of the bot list.
      Parameters:
        `id` - The id used for the cache.
        `site` - The `site` to get information from.
      Returns:
        Possibly-null String containing the Icon-URL of the bot list.

    - #### getId

          public String getId​(@Nonnull
                              String id,
                              @Nonnull
                              Site site)

      Gets the id of the bot list.
      The id is used for the `/api/count` endpoint.
      Parameters:
        `id` - The id used for the cache.
        `site` - The `site` to get information from.
      Returns:
        String containing the id of the bot list.

    - #### getId

          public String getId​(@Nonnull
                              String id,
                              @Nonnull
                              String site)

      Gets the id of the bot list.
      The id is used for the `/api/count` endpoint.
      Parameters:
        `id` - The id used for the cache.
        `site` - The `site` to get information from.
      Returns:
        String containing the id of the bot list.

    - #### getLanguage

          public String getLanguage​(@Nonnull
                                    String id,
                                    @Nonnull
                                    Site site)

      Gets the primary language of the bot list.
      Parameters:
        `id` - The id used for the cache.
        `site` - The `site` to get information from.
      Returns:
        String containing the primarily used language of the bot list.

    - #### getLanguage

          public String getLanguage​(@Nonnull
                                    String id,
                                    @Nonnull
                                    String site)

      Gets the primary language of the bot list.
      Parameters:
        `id` - The id used for the cache.
        `site` - The `site` to get information from.
      Returns:
        String containing the primarily used language of the bot list.

    - #### getList

          public JSONObject getList​(@Nonnull
                                    String id,
                                    @Nonnull
                                    Site site)

      Gets the information of a specific bot list.
      Parameters:
        `id` - The id used for the cache.
        `site` - The `site` to get information from.
      Returns:
        `JSONObject` containing information about the specified bot list.

    - #### getList

          public JSONObject getList​(@Nonnull
                                    String id,
                                    @Nonnull
                                    String site)

      Gets the information of a specific bot list.
      Parameters:
        `id` - The id used for the cache.
        `site` - The `site` to get information from.
      Returns:
        `JSONObject` containing information about the specified bot list.

    - #### getLists

          public JSONObject getLists​(@Nonnull
                                     String id)

      Gets the information about all the currently listed bot lists.
      Parameters:
        `id` - The id used for the cache.
      Returns:
        `JSONObject` containing information about all the different bot lists.

    - #### getName

          public String getName​(@Nonnull
                                String id,
                                @Nonnull
                                Site site)

      Gets the name of the bot list.
      Parameters:
        `id` - The id used for the cache.
        `site` - The `site` to get information from.
      Returns:
        String containing the name of the bot list.

    - #### getName

          public String getName​(@Nonnull
                                String id,
                                @Nonnull
                                String site)

      Gets the name of the bot list.
      Parameters:
        `id` - The id used for the cache.
        `site` - The `site` to get information from.
      Returns:
        String containing the name of the bot list.

    - #### getOwners

          @Nullable
          public @Nullable String getOwners​(@Nonnull
                                            String id,
                                            @Nonnull
                                            Site site)

      Gets the owners of a bot list.
      The pattern in which the owners are listed is `<name#discrim> (<id>), <name#discrim> (<id>), ...`
      Parameters:
        `id` - The id used for the cache.
        `site` - The `site` to get information from.
      Returns:
        Possibly-null String containing the owners of the bot list.

    - #### getOwners

          @Nullable
          public @Nullable String getOwners​(@Nonnull
                                            String id,
                                            @Nonnull
                                            String site)

      Gets the owners of a bot list.
      The pattern in which the owners are listed is `<name#discrim> (<id>), <name#discrim> (<id>), ...`
      Parameters:
        `id` - The id used for the cache.
        `site` - The `site` to get information from.
      Returns:
        Possibly-null String containing the owners of the bot list,

    - #### getTimeAdded

          public Integer getTimeAdded​(@Nonnull
                                      String id,
                                      @Nonnull
                                      Site site)

      Gets the UNIX timestamp of when the bot list was added to BotBlock as Integer.
      Parameters:
        `id` - The id used for the cache.
        `site` - The `site` to get information from.
      Returns:
        Integer displaying the UNIX time at which the bot list was added to BotBlock.

    - #### getTimeAdded

          public Integer getTimeAdded​(@Nonnull
                                      String id,
                                      @Nonnull
                                      String site)

      Gets the UNIX timestamp of when the bot list was added to BotBlock as Integer.
      Parameters:
        `id` - The id used for the cache.
        `site` - The `site` to get information from.
      Returns:
        Integer displaying the UNIX time at which the bot list was added to BotBlock.

    - #### getUrl

          public String getUrl​(@Nonnull
                               String id,
                               @Nonnull
                               Site site)

      Gets the URL for the bot list's website.
      Parameters:
        `id` - The id used for the cache.
        `site` - The `site` to get information from.
      Returns:
        String containing the URL to the bot list website.

    - #### getUrl

          public String getUrl​(@Nonnull
                               String id,
                               @Nonnull
                               String site)

      Gets the URL for the bot list's website.
      Parameters:
        `id` - The id used for the cache.
        `site` - The `site` to get information from.
      Returns:
        String containing the URL to the bot list website.

    - #### isDefunct

          public boolean isDefunct​(@Nonnull
                                   String id,
                                   @Nonnull
                                   Site site)

      Returns if the bot list is defunct.
      A defunct bot list is not displayed on the main site and is also excluded from the POST api.
      Parameters:
        `id` - The id used for the cache.
        `site` - The `site` to get information from.
      Returns:
        `true` if the bot list is defunct, `false` otherwise.

    - #### isDefunct

          public boolean isDefunct​(@Nonnull
                                   String id,
                                   @Nonnull
                                   String site)

      Returns if the bot list is defunct.
      A defunct bot list is not displayed on the main site and is also excluded from the POST api.
      Parameters:
        `id` - The id used for the cache.
        `site` - The `site` to get information from.
      Returns:
        `true` if the bot list is defunct, `false` otherwise.

    - #### isDiscordOnly

          public boolean isDiscordOnly​(@Nonnull
                                       String id,
                                       @Nonnull
                                       Site site)

      Returns if the bot list is only for Discord bots.
      Parameters:
        `id` - The id used for the cache.
        `site` - The `site` to get information from.
      Returns:
        `true` if the list is only for Discord bots, `false` otherwise.

    - #### isDiscordOnly

          public boolean isDiscordOnly​(@Nonnull
                                       String id,
                                       @Nonnull
                                       String site)

      Returns if the bot list is only for Discord bots.
      Parameters:
        `id` - The id used for the cache.
        `site` - The `site` to get information from.
      Returns:
        `true` if the list is only for Discord bots, `false` otherwise.