net.dv8tion.jda.api.utils.WidgetUtil Maven / Gradle / Ivy
Show all versions of JDA Show documentation
/*
* Copyright 2015 Austin Keener, Michael Ritter, Florian Spieß, and the JDA contributors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package net.dv8tion.jda.api.utils;
import net.dv8tion.jda.api.entities.Guild;
import net.dv8tion.jda.api.entities.Widget;
import net.dv8tion.jda.api.exceptions.RateLimitedException;
import net.dv8tion.jda.api.requests.RestConfig;
import net.dv8tion.jda.api.utils.data.DataObject;
import net.dv8tion.jda.internal.entities.WidgetImpl;
import net.dv8tion.jda.internal.utils.Checks;
import net.dv8tion.jda.internal.utils.Helpers;
import net.dv8tion.jda.internal.utils.IOUtil;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import java.io.IOException;
import java.io.InputStream;
import java.io.UncheckedIOException;
import java.net.HttpURLConnection;
/**
* The WidgetUtil is a class for interacting with various facets of Discord's
* guild widgets
*
* @since 3.0
* @author John A. Grosh
*/
public class WidgetUtil
{
public static final String WIDGET_PNG = RestConfig.DEFAULT_BASE_URL + "guilds/%s/widget.png?style=%s";
public static final String WIDGET_URL = RestConfig.DEFAULT_BASE_URL + "guilds/%s/widget.json";
public static final String WIDGET_HTML = "";
/**
* Gets the banner image for the specified guild of the specified type.
*
This banner will only be available if the guild in question has the
* Widget enabled.
*
* @param guild
* The guild
* @param type
* The type (visual style) of the banner
*
* @return A String containing the URL of the banner image
*/
@Nonnull
public static String getWidgetBanner(@Nonnull Guild guild, @Nonnull BannerType type)
{
Checks.notNull(guild, "Guild");
return getWidgetBanner(guild.getId(), type);
}
/**
* Gets the banner image for the specified guild of the specified type.
*
This banner will only be available if the guild in question has the
* Widget enabled. Additionally, this method can be used independently of
* being on the guild in question.
*
* @param guildId
* the guild ID
* @param type
* The type (visual style) of the banner
*
* @return A String containing the URL of the banner image
*/
@Nonnull
public static String getWidgetBanner(@Nonnull String guildId, @Nonnull BannerType type)
{
Checks.notNull(guildId, "GuildId");
Checks.notNull(type, "BannerType");
return String.format(WIDGET_PNG, guildId, type.name().toLowerCase());
}
/**
* Gets the pre-made HTML Widget for the specified guild using the specified
* settings. The widget will only display correctly if the guild in question
* has the Widget enabled.
*
* @param guild
* the guild
* @param theme
* the theme, light or dark
* @param width
* the width of the widget
* @param height
* the height of the widget
*
* @return a String containing the pre-made widget with the supplied settings
*/
@Nonnull
public static String getPremadeWidgetHtml(@Nonnull Guild guild, @Nonnull WidgetTheme theme, int width, int height)
{
Checks.notNull(guild, "Guild");
return getPremadeWidgetHtml(guild.getId(), theme, width, height);
}
/**
* Gets the pre-made HTML Widget for the specified guild using the specified
* settings. The widget will only display correctly if the guild in question
* has the Widget enabled. Additionally, this method can be used independently
* of being on the guild in question.
*
* @param guildId
* the guild ID
* @param theme
* the theme, light or dark
* @param width
* the width of the widget
* @param height
* the height of the widget
*
* @return a String containing the pre-made widget with the supplied settings
*/
@Nonnull
public static String getPremadeWidgetHtml(@Nonnull String guildId, @Nonnull WidgetTheme theme, int width, int height)
{
Checks.notNull(guildId, "GuildId");
Checks.notNull(theme, "WidgetTheme");
Checks.notNegative(width, "Width");
Checks.notNegative(height, "Height");
return Helpers.format(WIDGET_HTML, guildId, theme.name().toLowerCase(), width, height);
}
/**
* Makes a GET request to get the information for a Guild's widget. This
* widget (if available) contains information about the guild, including the
* Guild's name, an invite code (if set), a list of voice channels, and a
* list of online members (plus the voice states of any members in voice
* channels).
*
* This Widget can be obtained from any valid guild ID that has
* it enabled; no accounts need to be on the server to access this information.
*
* @param guildId
* The id of the Guild
*
* @throws net.dv8tion.jda.api.exceptions.RateLimitedException
* If the request was rate limited, respect the timeout!
* @throws java.lang.NumberFormatException
* If the provided {@code guildId} cannot be parsed by {@link Long#parseLong(String)}
*
* @return {@code null} if the provided guild ID is not a valid Discord guild ID
*
a Widget object with null fields and isAvailable() returning
* false if the guild ID is valid but the guild in question does not
* have the widget enabled
*
a filled-in Widget object if the guild ID is valid and the guild
* in question has the widget enabled.
*/
@Nullable
public static Widget getWidget(@Nonnull String guildId) throws RateLimitedException
{
return getWidget(MiscUtil.parseSnowflake(guildId));
}
/**
* Makes a GET request to get the information for a Guild's widget. This
* widget (if available) contains information about the guild, including the
* Guild's name, an invite code (if set), a list of voice channels, and a
* list of online members (plus the voice states of any members in voice
* channels).
*
*
This Widget can be obtained from any valid guild ID that has
* it enabled; no accounts need to be on the server to access this information.
*
* @param guildId
* The id of the Guild
*
* @throws java.io.UncheckedIOException
* If an I/O error occurs
* @throws net.dv8tion.jda.api.exceptions.RateLimitedException
* If the request was rate limited, respect the timeout!
*
* @return {@code null} if the provided guild ID is not a valid Discord guild ID
*
a Widget object with null fields and isAvailable() returning
* false if the guild ID is valid but the guild in question does not
* have the widget enabled
*
a filled-in Widget object if the guild ID is valid and the guild
* in question has the widget enabled.
*/
@Nullable
public static Widget getWidget(long guildId) throws RateLimitedException
{
Checks.notNull(guildId, "GuildId");
HttpURLConnection connection;
OkHttpClient client = new OkHttpClient.Builder().build();
Request request = new Request.Builder()
.url(String.format(WIDGET_URL, guildId))
.method("GET", null)
.header("user-agent", RestConfig.USER_AGENT)
.header("accept-encoding", "gzip")
.build();
try (Response response = client.newCall(request).execute())
{
final int code = response.code();
InputStream data = IOUtil.getBody(response);
switch (code)
{
case 200: // ok
{
try (InputStream stream = data)
{
return new WidgetImpl(DataObject.fromJson(stream));
}
catch (IOException e)
{
throw new UncheckedIOException(e);
}
}
case 400: // not valid snowflake
case 404: // guild not found
return null;
case 403: // widget disabled
return new WidgetImpl(guildId);
case 429: // ratelimited
{
long retryAfter;
try (InputStream stream = data)
{
retryAfter = DataObject.fromJson(stream).getLong("retry_after");
}
catch (Exception e)
{
retryAfter = 0;
}
throw new RateLimitedException(WIDGET_URL, retryAfter);
}
default:
throw new IllegalStateException("An unknown status was returned: " + code + " " + response.message());
}
}
catch (IOException e)
{
throw new UncheckedIOException(e);
}
}
/**
* Represents the available banner types
*
Each of these has a different appearance:
*
*
*
Shield - tiny, only contains Discord logo and online count
*
Banner1 - medium, contains server name, icon, and online count, and a "Powered by Discord" bar on the bottom
*
Banner2 - small, contains server name, icon, and online count, and a Discord logo on the side
*
Banner3 - medium, contains server name, icon, and online count, and a Discord logo with a "Chat Now" bar on the bottom
*
Banner4 - large, contains a very big Discord logo, server name, icon, and online count, and a big "Join My Server" button
*/
public enum BannerType
{
SHIELD, BANNER1, BANNER2, BANNER3, BANNER4
}
/**
* Represents the color scheme of the widget
*
These color themes match Discord's dark and light themes
*/
public enum WidgetTheme
{
LIGHT, DARK
}
}