Improve usability of AudioChannel (#2252)

* Add AudioChannelUnion
* Make AudioChannel extend StandardGuildChannel

src/main/java/net/dv8tion/jda/api/audio/factory/IPacketProvider.java

@@ -49,7 +49,7 @@ public interface IPacketProvider
     /**
      * Provides the current channel that this connection is transmitting to.
      *
-     * @return The {@link net.dv8tion.jda.api.entities.channel.middleman.AudioChannel AudioChannel} that this connection is sending to.
+     * @return The {@link AudioChannel} that this connection is sending to.
      */
     @Nonnull
     AudioChannel getConnectedChannel();

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

@@ -20,6 +20,7 @@
 import net.dv8tion.jda.api.entities.channel.concrete.StageChannel;
 import net.dv8tion.jda.api.entities.channel.concrete.VoiceChannel;
 import net.dv8tion.jda.api.entities.channel.middleman.AudioChannel;
+import net.dv8tion.jda.api.entities.channel.unions.AudioChannelUnion;
 import net.dv8tion.jda.api.requests.RestAction;
 
 import javax.annotation.CheckReturnValue;
@@ -117,18 +118,16 @@ public interface GuildVoiceState extends ISnowflake
     boolean isSendingVideo();
 
     /**
-     * Returns the current {@link net.dv8tion.jda.api.entities.channel.middleman.AudioChannel AudioChannel} that the {@link net.dv8tion.jda.api.entities.Member Member}
-     * is in. If the {@link net.dv8tion.jda.api.entities.Member Member} is currently not in a
-     * {@link net.dv8tion.jda.api.entities.channel.middleman.AudioChannel AudioChannel}, this returns null.
+     * Returns the current {@link AudioChannelUnion} that the {@link Member} is in.
+     * If the {@link Member} is currently not connected to a {@link AudioChannel}, this returns null.
      *
-     * @return The AudioChannel that the Member is in, or null.
+     * @return The AudioChannelUnion that the Member is connected to, or null.
      */
     @Nullable
-    AudioChannel getChannel();
+    AudioChannelUnion getChannel();
 
     /**
-     * Returns the {@link net.dv8tion.jda.api.entities.Guild Guild} for the {@link net.dv8tion.jda.api.entities.Member Member}
-     * that this {@link GuildVoiceState GuildVoiceState} belongs to. (BackReference)
+     * Returns the {@link Guild} for the {@link Member} that this GuildVoiceState belongs to.
      *
      * @return the Member's Guild
      */
@@ -145,12 +144,11 @@ public interface GuildVoiceState extends ISnowflake
     Member getMember();
 
     /**
-     * Used to determine if the {@link net.dv8tion.jda.api.entities.Member Member} is currently in an {@link net.dv8tion.jda.api.entities.channel.middleman.AudioChannel AudioChannel}
-     * in the {@link net.dv8tion.jda.api.entities.Guild Guild} returned from {@link #getGuild() getGuild()}.<br>
-     * If this is {@code false}, {@link #getChannel() getChannel()} will return {@code null}.
+     * Used to determine if the {@link Member} is currently connected to an {@link AudioChannel}
+     * in the {@link Guild} returned from {@link #getGuild()}.
+     * <br>If this is {@code false}, {@link #getChannel()} will return {@code null}.
      *
-     * @return True, if the {@link net.dv8tion.jda.api.entities.Member Member} is currently in a {@link net.dv8tion.jda.api.entities.channel.middleman.AudioChannel AudioChannel}
-     *         in this {@link net.dv8tion.jda.api.entities.Guild Guild}.
+     * @return True, if the {@link Member} is currently connected to an {@link AudioChannel} in this {@link Guild}
      */
     boolean inAudioChannel();
 

src/main/java/net/dv8tion/jda/api/entities/channel/middleman/AudioChannel.java

@@ -16,9 +16,9 @@
 
 package net.dv8tion.jda.api.entities.channel.middleman;
 
+import net.dv8tion.jda.api.JDA;
 import net.dv8tion.jda.api.Region;
 import net.dv8tion.jda.api.entities.Guild;
-import net.dv8tion.jda.api.entities.channel.attribute.IMemberContainer;
 import net.dv8tion.jda.api.entities.channel.concrete.StageChannel;
 import net.dv8tion.jda.api.entities.channel.concrete.VoiceChannel;
 import net.dv8tion.jda.api.managers.channel.middleman.AudioChannelManager;
@@ -28,25 +28,25 @@
 
 /**
  * Represents a Guild Channel that is capable of handling audio.
- * <br>This is a {@link GuildChannel GuildChannel} that contains additional methods present for audio channels
+ * <br>This is a {@link StandardGuildChannel} that contains additional methods present for audio channels
  *
  * @see VoiceChannel
  * @see StageChannel
  *
- * @see   Guild#getVoiceChannelCache()
- * @see   Guild#getVoiceChannels()
- * @see   Guild#getVoiceChannelsByName(String, boolean)
- * @see   Guild#getVoiceChannelById(long)
+ * @see Guild#getVoiceChannelCache()
+ * @see Guild#getVoiceChannels()
+ * @see Guild#getVoiceChannelsByName(String, boolean)
+ * @see Guild#getVoiceChannelById(long)
  *
- * @see   Guild#getStageChannelCache()
- * @see   Guild#getStageChannels()
- * @see   Guild#getStageChannelsByName(String, boolean)
- * @see   Guild#getStageChannelById(long)
+ * @see Guild#getStageChannelCache()
+ * @see Guild#getStageChannels()
+ * @see Guild#getStageChannelsByName(String, boolean)
+ * @see Guild#getStageChannelById(long)
  *
- * @see net.dv8tion.jda.api.JDA#getVoiceChannelById(long)
- * @see net.dv8tion.jda.api.JDA#getStageChannelById(long)
+ * @see JDA#getVoiceChannelById(long)
+ * @see JDA#getStageChannelById(long)
  */
-public interface AudioChannel extends GuildChannel, IMemberContainer
+public interface AudioChannel extends StandardGuildChannel
 {
     //TODO-v5: Docs
     @Override
@@ -63,10 +63,10 @@ public interface AudioChannel extends GuildChannel, IMemberContainer
     int getBitrate();
 
     /**
-     * The {@link net.dv8tion.jda.api.Region Region} of this {@link AudioChannel AudioChannel}.
+     * The {@link Region} of this channel.
      * <br>This will return {@link Region#AUTOMATIC} if the region of this channel is set to Automatic.
      *
-     * @return the {@link net.dv8tion.jda.api.Region Region} of this channel.
+     * @return the {@link Region} of this channel.
      */
     @Nonnull
     default Region getRegion()
@@ -75,10 +75,10 @@ default Region getRegion()
     }
 
     /**
-     * The raw region name for this {@link AudioChannel AudioChannel}.
-     * This will return null if the region is set to Automatic.
+     * The raw region name for this channel.
+     * <br>This will return null if the region is set to Automatic.
      *
-     * @return Raw region name
+     * @return Raw region name, or {@code null} if the region is set to automatic.
      */
     @Nullable
     String getRegionRaw();

src/main/java/net/dv8tion/jda/api/entities/channel/middleman/StandardGuildChannel.java

@@ -30,9 +30,12 @@
 
 /**
  * Represents a standard {@link GuildChannel} which are the "<i>normal</i>" channels that are present in the channel sidebar.
- * They include functionality "expected" of normal Discord channels like {@link net.dv8tion.jda.api.entities.channel.attribute.IPermissionContainer permissions},
- * {@link net.dv8tion.jda.api.entities.channel.attribute.IInviteContainer invite support}, {@link IPositionableChannel positioning}, the ability
- * {@link net.dv8tion.jda.api.entities.channel.attribute.ICategorizableChannel to be categorized}, and more.
+ * <br>They include functionality "expected" of normal Discord channels like
+ * {@link IPermissionContainer permissions},
+ * {@link IInviteContainer invite support},
+ * {@link IPositionableChannel positioning},
+ * the ability {@link ICategorizableChannel to be categorized},
+ * and more.
  *
  * @see GuildMessageChannel
  * @see TextChannel

src/main/java/net/dv8tion/jda/api/entities/channel/unions/AudioChannelUnion.java

@@ -0,0 +1,82 @@
+/*
+ * 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.channel.unions;
+
+import net.dv8tion.jda.api.entities.channel.ChannelType;
+import net.dv8tion.jda.api.entities.channel.concrete.StageChannel;
+import net.dv8tion.jda.api.entities.channel.concrete.VoiceChannel;
+import net.dv8tion.jda.api.entities.channel.middleman.AudioChannel;
+
+import javax.annotation.Nonnull;
+
+/**
+ * A union representing all channel types that implement {@link AudioChannel}.
+ * <br>This class extends {@link AudioChannel} and primarily acts as a discovery tool for
+ * developers to discover some common interfaces that a {@link AudioChannel} could be cast to.
+ *
+ * <br>This interface represents the follow concrete channel types:
+ * <ul>
+ *     <li>{@link VoiceChannel}</li>
+ *     <li>{@link StageChannel}</li>
+ * </ul>
+ */
+public interface AudioChannelUnion extends AudioChannel
+{
+    /**
+     * Casts this union to a {@link VoiceChannel}.
+     * <br>This method exists for developer discoverability.
+     *
+     * <p>Note: This is effectively equivalent to using the cast operator:
+     * <pre>{@code
+     * //These are the same!
+     * VoiceChannel channel = union.asVoiceChannel();
+     * VoiceChannel channel2 = (VoiceChannel) union;
+     * }</pre>
+     *
+     * You can use {@link #getType()} to see if the channel is of type {@link ChannelType#VOICE} to validate
+     * whether you can call this method in addition to normal instanceof checks: {@code channel instanceof VoiceChannel}
+     *
+     * @throws IllegalStateException
+     *         If the channel represented by this union is not actually a {@link VoiceChannel}.
+     *
+     * @return The channel as a {@link VoiceChannel}
+     */
+    @Nonnull
+    VoiceChannel asVoiceChannel();
+
+    /**
+     * Casts this union to a {@link StageChannel}.
+     * <br>This method exists for developer discoverability.
+     *
+     * <p>Note: This is effectively equivalent to using the cast operator:
+     * <pre>{@code
+     * //These are the same!
+     * StageChannel channel = union.asStageChannel();
+     * StageChannel channel2 = (StageChannel) union;
+     * }</pre>
+     *
+     * You can use {@link #getType()} to see if the channel is of type {@link ChannelType#STAGE} to validate
+     * whether you can call this method in addition to normal instanceof checks: {@code channel instanceof StageChannel}
+     *
+     * @throws IllegalStateException
+     *         If the channel represented by this union is not actually a {@link StageChannel}.
+     *
+     * @return The channel as a {@link StageChannel}
+     */
+    @Nonnull
+    StageChannel asStageChannel();
+}

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

@@ -19,6 +19,7 @@
 import net.dv8tion.jda.api.JDA;
 import net.dv8tion.jda.api.entities.Member;
 import net.dv8tion.jda.api.entities.channel.middleman.AudioChannel;
+import net.dv8tion.jda.api.entities.channel.unions.AudioChannelUnion;
 
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
@@ -50,16 +51,16 @@ public GenericGuildVoiceUpdateEvent(
 
     @Nullable
     @Override
-    public AudioChannel getChannelLeft()
+    public AudioChannelUnion getChannelLeft()
     {
-        return left;
+        return (AudioChannelUnion) left;
     }
 
     @Nullable
     @Override
-    public AudioChannel getChannelJoined()
+    public AudioChannelUnion getChannelJoined()
     {
-        return joined;
+        return (AudioChannelUnion) joined;
     }
 
     @Nonnull

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

@@ -19,6 +19,7 @@
 import net.dv8tion.jda.api.JDA;
 import net.dv8tion.jda.api.entities.Member;
 import net.dv8tion.jda.api.entities.channel.middleman.AudioChannel;
+import net.dv8tion.jda.api.entities.channel.unions.AudioChannelUnion;
 
 import javax.annotation.Nonnull;
 
@@ -50,7 +51,7 @@ public GuildVoiceJoinEvent(@Nonnull JDA api, long responseNumber, @Nonnull Membe
 
     @Nonnull
     @Override
-    public AudioChannel getChannelJoined()
+    public AudioChannelUnion getChannelJoined()
     {
         return super.getChannelJoined();
     }

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

@@ -19,6 +19,7 @@
 import net.dv8tion.jda.api.JDA;
 import net.dv8tion.jda.api.entities.Member;
 import net.dv8tion.jda.api.entities.channel.middleman.AudioChannel;
+import net.dv8tion.jda.api.entities.channel.unions.AudioChannelUnion;
 
 import javax.annotation.Nonnull;
 
@@ -52,7 +53,7 @@ public GuildVoiceLeaveEvent(@Nonnull JDA api, long responseNumber, @Nonnull Memb
 
     @Nonnull
     @Override
-    public AudioChannel getChannelLeft()
+    public AudioChannelUnion getChannelLeft()
     {
         return super.getChannelLeft();
     }

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

@@ -19,6 +19,7 @@
 import net.dv8tion.jda.api.JDA;
 import net.dv8tion.jda.api.entities.Member;
 import net.dv8tion.jda.api.entities.channel.middleman.AudioChannel;
+import net.dv8tion.jda.api.entities.channel.unions.AudioChannelUnion;
 
 import javax.annotation.Nonnull;
 
@@ -52,14 +53,14 @@ public GuildVoiceMoveEvent(@Nonnull JDA api, long responseNumber, @Nonnull Membe
 
     @Nonnull
     @Override
-    public AudioChannel getChannelLeft()
+    public AudioChannelUnion getChannelLeft()
     {
         return super.getChannelLeft();
     }
 
     @Nonnull
     @Override
-    public AudioChannel getChannelJoined()
+    public AudioChannelUnion getChannelJoined()
     {
         return super.getChannelJoined();
     }

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

@@ -19,6 +19,7 @@
 import net.dv8tion.jda.api.entities.Guild;
 import net.dv8tion.jda.api.entities.Member;
 import net.dv8tion.jda.api.entities.channel.middleman.AudioChannel;
+import net.dv8tion.jda.api.entities.channel.unions.AudioChannelUnion;
 import net.dv8tion.jda.api.events.UpdateEvent;
 
 import javax.annotation.Nonnull;
@@ -68,18 +69,18 @@ public interface GuildVoiceUpdateEvent extends UpdateEvent<Member, AudioChannel>
     Guild getGuild();
 
     /**
-     * The {@link net.dv8tion.jda.api.entities.channel.middleman.AudioChannel AudioChannel} that the {@link net.dv8tion.jda.api.entities.Member Member} is moved from
+     * The {@link AudioChannelUnion} that the {@link Member} is moved from
      *
-     * @return The {@link net.dv8tion.jda.api.entities.channel.middleman.AudioChannel}
+     * @return The {@link AudioChannelUnion}, or {@code null} if the member was not connected to a channel before
      */
     @Nullable
-    AudioChannel getChannelLeft();
+    AudioChannelUnion getChannelLeft();
 
     /**
-     * The {@link net.dv8tion.jda.api.entities.channel.middleman.AudioChannel AudioChannel} that was joined
+     * The {@link AudioChannelUnion} that was joined
      *
-     * @return The {@link net.dv8tion.jda.api.entities.channel.middleman.AudioChannel AudioChannel}
+     * @return The {@link AudioChannelUnion}, or {@code null} if the member has disconnected
      */
     @Nullable
-    AudioChannel getChannelJoined();
+    AudioChannelUnion getChannelJoined();
 }

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

@@ -26,6 +26,7 @@
 import net.dv8tion.jda.api.entities.Guild;
 import net.dv8tion.jda.api.entities.channel.concrete.VoiceChannel;
 import net.dv8tion.jda.api.entities.channel.middleman.AudioChannel;
+import net.dv8tion.jda.api.entities.channel.unions.AudioChannelUnion;
 import net.dv8tion.jda.internal.utils.Checks;
 import net.dv8tion.jda.internal.utils.JDALogger;
 import org.slf4j.Logger;
@@ -176,15 +177,13 @@ default void setSpeakingMode(@Nonnull SpeakingMode... mode)
     Guild getGuild();
 
     /**
-     * The {@link net.dv8tion.jda.api.entities.channel.middleman.AudioChannel AudioChannel} that JDA currently has an audio connection
-     * to. If JDA currently doesn't have an audio connection to an {@link net.dv8tion.jda.api.entities.channel.middleman.AudioChannel AudioChannel}
-     * this will return {@code null}.
+     * The {@link AudioChannelUnion} that JDA currently has an audio connection to.
+     * <br>If JDA currently doesn't have an active audio connection, this will return {@code null}.
      *
-     * @return The {@link net.dv8tion.jda.api.entities.channel.middleman.AudioChannel AudioChannel} the audio connection is connected to
-     *         or {@code null} if not connected.
+     * @return The {@link AudioChannelUnion} the audio connection is connected to, or {@code null} if not connected.
      */
     @Nullable
-    AudioChannel getConnectedChannel();
+    AudioChannelUnion getConnectedChannel();
 
     /**
      * This can be used to find out if JDA currently has an active audio connection with a

src/main/java/net/dv8tion/jda/api/managers/channel/middleman/AudioChannelManager.java

@@ -21,13 +21,12 @@
 import net.dv8tion.jda.api.entities.channel.ChannelType;
 import net.dv8tion.jda.api.entities.channel.concrete.VoiceChannel;
 import net.dv8tion.jda.api.entities.channel.middleman.AudioChannel;
-import net.dv8tion.jda.api.managers.channel.ChannelManager;
 
 import javax.annotation.CheckReturnValue;
 import javax.annotation.Nonnull;
 
 //todo-v5: Docs
-public interface AudioChannelManager<T extends AudioChannel, M extends AudioChannelManager<T, M>> extends ChannelManager<T, M>
+public interface AudioChannelManager<T extends AudioChannel, M extends AudioChannelManager<T, M>> extends StandardGuildChannelManager<T, M>
 {
     /**
      * Sets the <b><u>bitrate</u></b> of the selected {@link VoiceChannel VoiceChannel}.