First pass on stage channels

src/main/java/net/dv8tion/jda/api/JDA.java

@@ -58,6 +58,7 @@
 import java.util.function.BooleanSupplier;
 import java.util.function.Consumer;
 import java.util.regex.Matcher;
+import java.util.stream.Collectors;
 
 /**
  * The core of JDA. Acts as a registry system of JDA. All parts of the the API can be accessed starting from this class.
@@ -1164,6 +1165,8 @@ default GuildChannel getGuildChannelById(@Nonnull ChannelType type, long id)
             return getTextChannelById(id);
         case VOICE:
             return getVoiceChannelById(id);
+        case STAGE:
+            return getStageChannelById(id);
         case STORE:
             return getStoreChannelById(id);
         case CATEGORY:
@@ -1172,6 +1175,29 @@ default GuildChannel getGuildChannelById(@Nonnull ChannelType type, long id)
         return null;
     }
 
+    @Nonnull
+    default List<StageChannel> getStageChannelsByName(@Nonnull String name, boolean ignoreCase)
+    {
+        return getVoiceChannelsByName(name, ignoreCase)
+                .stream()
+                .filter(StageChannel.class::isInstance)
+                .map(StageChannel.class::cast)
+                .collect(Collectors.toList());
+    }
+
+    @Nullable
+    default StageChannel getStageChannelById(@Nonnull String id)
+    {
+        return getStageChannelById(MiscUtil.parseSnowflake(id));
+    }
+
+    @Nullable
+    default StageChannel getStageChannelById(long id)
+    {
+        VoiceChannel channel = getVoiceChannelById(id);
+        return channel instanceof StageChannel ? (StageChannel) channel : null;
+    }
+
     /**
      * {@link net.dv8tion.jda.api.utils.cache.SnowflakeCacheView SnowflakeCacheView} of
      * all cached {@link net.dv8tion.jda.api.entities.Category Categories} visible to this JDA session.

src/main/java/net/dv8tion/jda/api/Permission.java

@@ -71,6 +71,8 @@ public enum Permission
     MANAGE_WEBHOOKS(   29, true, true, "Manage Webhooks"),
     MANAGE_EMOTES(     30, true, false, "Manage Emojis"),
 
+    REQUEST_TO_SPEAK(  32, true, true, "Request to Speak"),
+
     UNKNOWN(-1, false, false, "Unknown");
 
     /**
@@ -109,7 +111,7 @@ public enum Permission
      */
     public static final long ALL_VOICE_PERMISSIONS
             = Permission.getRaw(VOICE_STREAM, VOICE_CONNECT, VOICE_SPEAK, VOICE_MUTE_OTHERS,
-                                VOICE_DEAF_OTHERS, VOICE_MOVE_OTHERS, VOICE_USE_VAD);
+                                VOICE_DEAF_OTHERS, VOICE_MOVE_OTHERS, VOICE_USE_VAD, REQUEST_TO_SPEAK);
 
     private final int offset;
     private final long raw;

src/main/java/net/dv8tion/jda/api/entities/Category.java

@@ -159,6 +159,43 @@ public interface Category extends GuildChannel
     @CheckReturnValue
     ChannelAction<VoiceChannel> createVoiceChannel(@Nonnull String name);
 
+    /**
+     * Creates a new {@link net.dv8tion.jda.api.entities.StageChannel VoiceChannel} with this Category as parent.
+     * For this to be successful, the logged in account has to have the
+     * {@link net.dv8tion.jda.api.Permission#MANAGE_CHANNEL MANAGE_CHANNEL} Permission in the {@link net.dv8tion.jda.api.entities.Guild Guild}.
+     *
+     * <p>This will copy all {@link net.dv8tion.jda.api.entities.PermissionOverride PermissionOverrides} of this Category!
+     * Unless the bot is unable to sync it with this category due to permission escalation.
+     * See {@link IPermissionHolder#canSync(GuildChannel, GuildChannel)} for details.
+     *
+     * <p>Possible {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} caused by
+     * the returned {@link net.dv8tion.jda.api.requests.RestAction RestAction} include the following:
+     * <ul>
+     *     <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_PERMISSIONS MISSING_PERMISSIONS}
+     *     <br>The channel could not be created due to a permission discrepancy</li>
+     *
+     *     <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_ACCESS MISSING_ACCESS}
+     *     <br>The {@link net.dv8tion.jda.api.Permission#VIEW_CHANNEL VIEW_CHANNEL} permission was removed</li>
+     *
+     *     <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#MAX_CHANNELS MAX_CHANNELS}
+     *     <br>The maximum number of channels were exceeded</li>
+     * </ul>
+     *
+     * @param  name
+     *         The name of the StageChannel to create
+     *
+     * @throws net.dv8tion.jda.api.exceptions.InsufficientPermissionException
+     *         If the logged in account does not have the {@link net.dv8tion.jda.api.Permission#MANAGE_CHANNEL} permission
+     * @throws IllegalArgumentException
+     *         If the provided name is {@code null} or empty or greater than 100 characters in length
+     *
+     * @return A specific {@link ChannelAction ChannelAction}
+     *         <br>This action allows to set fields for the new StageChannel before creating it
+     */
+    @Nonnull
+    @CheckReturnValue
+    ChannelAction<StageChannel> createStageChannel(@Nonnull String name);
+
     /**
      * Modifies the positional order of this Category's nested {@link #getTextChannels() TextChannels} and {@link #getStoreChannels() StoreChannels}.
      * <br>This uses an extension of {@link ChannelOrderAction ChannelOrderAction}

src/main/java/net/dv8tion/jda/api/entities/ChannelType.java

@@ -47,6 +47,10 @@ public enum ChannelType
      * A {@link net.dv8tion.jda.api.entities.StoreChannel StoreChannel}, Guild-Only.
      */
     STORE(6, 0, true),
+    /**
+     * A {@link StageChannel StageChannel}, Guild-Only.
+     */
+    STAGE(13, 1, true),
     /**
      * Unknown Discord channel type. Should never happen and would only possibly happen if Discord implemented a new
      * channel type and JDA had yet to implement support for it.

src/main/java/net/dv8tion/jda/api/entities/Guild.java

@@ -56,6 +56,7 @@
 import java.util.concurrent.Future;
 import java.util.function.Consumer;
 import java.util.function.Predicate;
+import java.util.stream.Collectors;
 
 /**
  * Represents a Discord {@link net.dv8tion.jda.api.entities.Guild Guild}.
@@ -1147,6 +1148,8 @@ default GuildChannel getGuildChannelById(@Nonnull ChannelType type, long id)
                 return getTextChannelById(id);
             case VOICE:
                 return getVoiceChannelById(id);
+            case STAGE:
+                return getStageChannelById(id);
             case STORE:
                 return getStoreChannelById(id);
             case CATEGORY:
@@ -1155,6 +1158,29 @@ default GuildChannel getGuildChannelById(@Nonnull ChannelType type, long id)
         return null;
     }
 
+    @Nonnull
+    default List<StageChannel> getStageChannelsByName(@Nonnull String name, boolean ignoreCase)
+    {
+        return getVoiceChannelsByName(name, ignoreCase)
+                .stream()
+                .filter(StageChannel.class::isInstance)
+                .map(StageChannel.class::cast)
+                .collect(Collectors.toList());
+    }
+
+    @Nullable
+    default StageChannel getStageChannelById(@Nonnull String id)
+    {
+        return getStageChannelById(MiscUtil.parseSnowflake(id));
+    }
+
+    @Nullable
+    default StageChannel getStageChannelById(long id)
+    {
+        VoiceChannel channel = getVoiceChannelById(id);
+        return channel instanceof StageChannel ? (StageChannel) channel : null;
+    }
+
     /**
      * Gets the {@link net.dv8tion.jda.api.entities.Category Category} from this guild that matches the provided id.
      * This method is similar to {@link net.dv8tion.jda.api.JDA#getCategoryById(String)}, but it only checks in this
@@ -2253,6 +2279,10 @@ default RestAction<Ban> retrieveBan(@Nonnull User bannedUser)
     @Nonnull
     AudioManager getAudioManager();
 
+    @Nonnull
+    @CheckReturnValue
+    RestAction<Void> requestToSpeak();
+
     /**
      * Returns the {@link net.dv8tion.jda.api.JDA JDA} instance of this Guild
      *
@@ -4609,6 +4639,70 @@ default ChannelAction<VoiceChannel> createVoiceChannel(@Nonnull String name)
     @CheckReturnValue
     ChannelAction<VoiceChannel> createVoiceChannel(@Nonnull String name, @Nullable Category parent);
 
+    /**
+     * Creates a new {@link net.dv8tion.jda.api.entities.StageChannel VoiceChannel} in this Guild.
+     * For this to be successful, the logged in account has to have the {@link net.dv8tion.jda.api.Permission#MANAGE_CHANNEL MANAGE_CHANNEL} Permission.
+     *
+     * <p>Possible {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} caused by
+     * the returned {@link net.dv8tion.jda.api.requests.RestAction RestAction} include the following:
+     * <ul>
+     *     <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_PERMISSIONS MISSING_PERMISSIONS}
+     *     <br>The channel could not be created due to a permission discrepancy</li>
+     *
+     *     <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#MAX_CHANNELS MAX_CHANNELS}
+     *     <br>The maximum number of channels were exceeded</li>
+     * </ul>
+     *
+     * @param  name
+     *         The name of the StageChannel to create
+     *
+     * @throws net.dv8tion.jda.api.exceptions.InsufficientPermissionException
+     *         If the logged in account does not have the {@link net.dv8tion.jda.api.Permission#MANAGE_CHANNEL} permission
+     * @throws IllegalArgumentException
+     *         If the provided name is {@code null} or empty or greater than 100 characters in length
+     *
+     * @return A specific {@link ChannelAction ChannelAction}
+     *         <br>This action allows to set fields for the new StageChannel before creating it
+     */
+    @Nonnull
+    @CheckReturnValue
+    default ChannelAction<StageChannel> createStageChannel(@Nonnull String name)
+    {
+        return createStageChannel(name, null);
+    }
+
+    /**
+     * Creates a new {@link net.dv8tion.jda.api.entities.StageChannel VoiceChannel} in this Guild.
+     * For this to be successful, the logged in account has to have the {@link net.dv8tion.jda.api.Permission#MANAGE_CHANNEL MANAGE_CHANNEL} Permission.
+     *
+     * <p>Possible {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} caused by
+     * the returned {@link net.dv8tion.jda.api.requests.RestAction RestAction} include the following:
+     * <ul>
+     *     <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#MISSING_PERMISSIONS MISSING_PERMISSIONS}
+     *     <br>The channel could not be created due to a permission discrepancy</li>
+     *
+     *     <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#MAX_CHANNELS MAX_CHANNELS}
+     *     <br>The maximum number of channels were exceeded</li>
+     * </ul>
+     *
+     * @param  name
+     *         The name of the StageChannel to create
+     * @param  parent
+     *         The optional parent category for this channel, or null
+     *
+     * @throws net.dv8tion.jda.api.exceptions.InsufficientPermissionException
+     *         If the logged in account does not have the {@link net.dv8tion.jda.api.Permission#MANAGE_CHANNEL} permission
+     * @throws IllegalArgumentException
+     *         If the provided name is {@code null} or empty or greater than 100 characters in length;
+     *         or the provided parent is not in the same guild.
+     *
+     * @return A specific {@link ChannelAction ChannelAction}
+     *         <br>This action allows to set fields for the new StageChannel before creating it
+     */
+    @Nonnull
+    @CheckReturnValue
+    ChannelAction<StageChannel> createStageChannel(@Nonnull String name, @Nullable Category parent);
+
     /**
      * Creates a new {@link net.dv8tion.jda.api.entities.Category Category} in this Guild.
      * For this to be successful, the logged in account has to have the {@link net.dv8tion.jda.api.Permission#MANAGE_CHANNEL MANAGE_CHANNEL} Permission.

src/main/java/net/dv8tion/jda/api/entities/IPermissionHolder.java

@@ -173,7 +173,7 @@ public interface IPermissionHolder extends ISnowflake
     default boolean hasAccess(@Nonnull GuildChannel channel)
     {
         Checks.notNull(channel, "Channel");
-        return channel.getType() == ChannelType.VOICE
+        return channel.getType() == ChannelType.VOICE || channel.getType() == ChannelType.STAGE
                 ? hasPermission(channel, Permission.VOICE_CONNECT, Permission.VIEW_CHANNEL)
                 : hasPermission(channel, Permission.VIEW_CHANNEL);
     }

src/main/java/net/dv8tion/jda/api/entities/StageChannel.java

@@ -0,0 +1,36 @@
+/*
+ * 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.entities;
+
+import javax.annotation.Nonnull;
+
+/**
+ * Represents a Stage Channel, also known as Radio Channel.
+ *
+ * <p>This is a more advanced version of a {@link VoiceChannel}
+ * that can be used to host events with speakers and listeners.
+ */
+public interface StageChannel extends VoiceChannel
+{
+    /**
+     * The topic of a stage channel.
+     *
+     * @return The topic
+     */
+    @Nonnull
+    String getTopic();
+}

src/main/java/net/dv8tion/jda/api/events/guild/invite/GenericGuildInviteEvent.java

@@ -114,7 +114,7 @@ public TextChannel getTextChannel()
      * The {@link VoiceChannel} this invite points to.
      *
      * @throws IllegalStateException
-     *         If this did not happen in a channel of type {@link ChannelType#VOICE ChannelType.VOICE}
+     *         If this did not happen in a voice channel
      *
      * @return {@link VoiceChannel}
      *
@@ -124,11 +124,30 @@ public TextChannel getTextChannel()
     @Nonnull
     public VoiceChannel getVoiceChannel()
     {
-        if (getChannelType() != ChannelType.VOICE)
-            throw new IllegalStateException("The channel is not of type VOICE");
+        if (!(channel instanceof VoiceChannel))
+            throw new IllegalStateException("The channel is not of type VOICE or STAGE");
         return (VoiceChannel) getChannel();
     }
 
+    /**
+     * The {@link StageChannel} this invite points to.
+     *
+     * @throws IllegalStateException
+     *         If this did not happen in a channel of type {@link ChannelType#STAGE ChannelType.STAGE}
+     *
+     * @return {@link StageChannel}
+     *
+     * @see    #getChannel()
+     * @see    #getChannelType()
+     */
+    @Nonnull
+    public StageChannel getStageChannel()
+    {
+        if (getChannelType() != ChannelType.STAGE)
+            throw new IllegalStateException("The channel is not of type STAGE");
+        return (StageChannel) getChannel();
+    }
+
     /**
      * The {@link StoreChannel} this invite points to.
      *

src/main/java/net/dv8tion/jda/api/events/guild/voice/GuildVoiceUpdateEvent.java

@@ -16,10 +16,12 @@
 
 package net.dv8tion.jda.api.events.guild.voice;
 
+import net.dv8tion.jda.api.entities.Guild;
 import net.dv8tion.jda.api.entities.Member;
 import net.dv8tion.jda.api.entities.VoiceChannel;
 import net.dv8tion.jda.api.events.UpdateEvent;
 
+import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 
 /**
@@ -49,6 +51,22 @@ public interface GuildVoiceUpdateEvent extends UpdateEvent<Member, VoiceChannel>
 {
     String IDENTIFIER = "voice-channel";
 
+    /**
+     * The affected {@link net.dv8tion.jda.api.entities.Member Member}
+     *
+     * @return The affected Member
+     */
+    @Nonnull
+    Member getMember();
+
+    /**
+     * The {@link net.dv8tion.jda.api.entities.Guild Guild}
+     *
+     * @return The Guild
+     */
+    @Nonnull
+    Guild getGuild();
+
     /**
      * The {@link net.dv8tion.jda.api.entities.VoiceChannel VoiceChannel} that the {@link net.dv8tion.jda.api.entities.Member Member} is moved from
      *

src/main/java/net/dv8tion/jda/api/managers/ChannelManager.java

@@ -365,17 +365,18 @@ default ChannelManager sync()
     ChannelManager setPosition(int position);
 
     /**
-     * Sets the <b><u>topic</u></b> of the selected {@link net.dv8tion.jda.api.entities.TextChannel TextChannel}.
+     * Sets the <b><u>topic</u></b> of the selected
+     * {@link net.dv8tion.jda.api.entities.TextChannel TextChannel} or {@link StageChannel StageChannel}.
      *
      * <p>A channel topic <b>must not</b> be more than {@code 1024} characters long!
-     * <br><b>This is only available to {@link net.dv8tion.jda.api.entities.TextChannel TextChannels}</b>
+     * <br><b>This is only available to {@link net.dv8tion.jda.api.entities.TextChannel TextChannels} and {@link StageChannel StageChannels}</b>
      *
      * @param  topic
-     *         The new topic for the selected {@link net.dv8tion.jda.api.entities.TextChannel TextChannel},
+     *         The new topic for the selected channel,
      *         {@code null} or empty String to reset
      *
      * @throws UnsupportedOperationException
-     *         If the selected {@link net.dv8tion.jda.api.entities.GuildChannel GuildChannel}'s type is not {@link net.dv8tion.jda.api.entities.ChannelType#TEXT TEXT}
+     *         If the selected {@link net.dv8tion.jda.api.entities.GuildChannel GuildChannel}'s type is not {@link net.dv8tion.jda.api.entities.ChannelType#TEXT TEXT} nor {@link ChannelType#STAGE STAGE}
      * @throws IllegalArgumentException
      *         If the provided topic is greater than {@code 1024} in length
      *