Introduce Channel Unions (#2138)

src/examples/java/MessageListenerExample.java

@@ -18,6 +18,7 @@
 import net.dv8tion.jda.api.JDABuilder;
 import net.dv8tion.jda.api.Permission;
 import net.dv8tion.jda.api.entities.*;
+import net.dv8tion.jda.api.entities.channel.unions.MessageChannelUnion;
 import net.dv8tion.jda.api.events.message.MessageReceivedEvent;
 import net.dv8tion.jda.api.exceptions.PermissionException;
 import net.dv8tion.jda.api.exceptions.RateLimitedException;
@@ -85,8 +86,8 @@ public void onMessageReceived(MessageReceivedEvent event)
         //Event specific information
         User author = event.getAuthor();                //The user that sent the message
         Message message = event.getMessage();           //The message that was received.
-        MessageChannel channel = event.getChannel();    //This is the MessageChannel that the message was sent to.
-                                                        //  This could be a TextChannel, PrivateChannel, or Group!
+        MessageChannelUnion channel = event.getChannel();    //This is the MessageChannel that the message was sent to.
+                                                        //  This could be a TextChannel, PrivateChannel, or more!
 
         String msg = message.getContentDisplay();              //This returns a human readable version of the Message. Similar to
                                                         // what you would see in the client.
@@ -101,7 +102,7 @@ public void onMessageReceived(MessageReceivedEvent event)
             // the message possibly not being from a Guild!
 
             Guild guild = event.getGuild();             //The Guild that this message was sent in. (note, in the API, Guilds are Servers)
-            TextChannel textChannel = event.getTextChannel(); //The TextChannel that this message was sent to.
+            TextChannel textChannel = channel.asTextChannel(); //The TextChannel that this message was sent to.
             Member member = event.getMember();          //This Member that sent the message. Contains Guild specific information about the User!
 
             String name;
@@ -120,7 +121,7 @@ else if (event.isFromType(ChannelType.PRIVATE)) //If this message was sent to a
         {
             //The message was sent in a PrivateChannel.
             //In this example we don't directly use the privateChannel, however, be sure, there are uses for it!
-            PrivateChannel privateChannel = event.getPrivateChannel();
+            PrivateChannel privateChannel = channel.asPrivateChannel();
 
             System.out.printf("[PRIV]<%s>: %s\n", author.getName(), msg);
         }

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

@@ -62,7 +62,7 @@
 import java.util.regex.Matcher;
 
 /**
- * The core of JDA. Acts as a registry system of JDA. All parts of the the API can be accessed starting from this class.
+ * The core of JDA. Acts as a registry system of JDA. All parts of the API can be accessed starting from this class.
  *
  * @see JDABuilder
  */

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

@@ -78,16 +78,16 @@ public enum ChannelField
      *
      * Limited to {@link NewsChannel NewsChannels} and {@link TextChannel TextChannels}.
      *
-     * @see BaseGuildMessageChannel#getTopic()
+     * @see StandardGuildMessageChannel#getTopic()
      */
     TOPIC("topic", AuditLogKey.CHANNEL_TOPIC),
 
     /**
      * The NSFW state of the channel.
      *
-     * Limited to {@link BaseGuildMessageChannel Base Guild Channels} (and implementations).
+     * Limited to {@link StandardGuildMessageChannel StandardGuildMessageChannels} (and implementations).
      *
-     * @see BaseGuildMessageChannel#isNSFW()
+     * @see StandardGuildMessageChannel#isNSFW()
      */
     NSFW("nsfw", AuditLogKey.CHANNEL_NSFW),
 

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

@@ -19,6 +19,7 @@
 import net.dv8tion.jda.api.Permission;
 import net.dv8tion.jda.api.Region;
 import net.dv8tion.jda.api.entities.channel.IGuildChannelContainer;
+import net.dv8tion.jda.api.entities.channel.unions.DefaultGuildChannelUnion;
 import net.dv8tion.jda.api.entities.emoji.CustomEmoji;
 import net.dv8tion.jda.api.entities.emoji.RichCustomEmoji;
 import net.dv8tion.jda.api.entities.sticker.*;
@@ -1965,17 +1966,17 @@ default RestAction<RichCustomEmoji> retrieveEmoji(@Nonnull CustomEmoji emoji)
     Role getPublicRole();
 
     /**
-     * The default {@link net.dv8tion.jda.api.entities.BaseGuildMessageChannel BaseGuildMessageChannel} for a {@link net.dv8tion.jda.api.entities.Guild Guild}.
+     * The default {@link net.dv8tion.jda.api.entities.StandardGuildChannel} for a {@link net.dv8tion.jda.api.entities.Guild Guild}.
      * <br>This is the channel that the Discord client will default to opening when a Guild is opened for the first time when accepting an invite
-     * that is not directed at a specific {@link net.dv8tion.jda.api.entities.BaseGuildMessageChannel BaseGuildMessageChannel}.
+     * that is not directed at a specific {@link IInviteContainer channel}.
      *
      * <p>Note: This channel is the first channel in the guild (ordered by position) that the {@link #getPublicRole()}
      * has the {@link net.dv8tion.jda.api.Permission#VIEW_CHANNEL Permission.VIEW_CHANNEL} in.
      *
-     * @return The {@link net.dv8tion.jda.api.entities.BaseGuildMessageChannel BaseGuildMessageChannel} representing the default channel for this guild
+     * @return The {@link net.dv8tion.jda.api.entities.StandardGuildChannel channel} representing the default channel for this guild
      */
     @Nullable
-    BaseGuildMessageChannel getDefaultChannel();
+    DefaultGuildChannelUnion getDefaultChannel();
 
     /**
      * Returns the {@link GuildManager GuildManager} for this Guild, used to modify

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

@@ -22,10 +22,9 @@
 /**
  * Represents all message channels present in guilds.
  *
- * This includes channels that are not included in {@link BaseGuildMessageChannel BaseGuildMessageChannel}, such as {@link ThreadChannel}.
- *
- * @see BaseGuildMessageChannel
+ * This includes channels that are not included in {@link StandardGuildMessageChannel}, such as {@link ThreadChannel}.
  *
+ * @see StandardGuildMessageChannel
  */
 public interface GuildMessageChannel extends GuildChannel, MessageChannel
 {

src/main/java/net/dv8tion/jda/api/entities/BaseGuildMessageChannel.java → src/main/java/net/dv8tion/jda/api/entities/IWebhookContainer.java

@@ -1,51 +1,38 @@
+/*
+ * 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 net.dv8tion.jda.api.managers.channel.middleman.BaseGuildMessageChannelManager;
 import net.dv8tion.jda.api.requests.RestAction;
 import net.dv8tion.jda.api.requests.restaction.AuditableRestAction;
-import net.dv8tion.jda.api.requests.restaction.ChannelAction;
 import net.dv8tion.jda.api.requests.restaction.WebhookAction;
 
 import javax.annotation.CheckReturnValue;
 import javax.annotation.Nonnull;
-import javax.annotation.Nullable;
 import java.util.List;
 
-
 /**
- * Represents a standard {@link Guild Guild} {@link MessageChannel MessageChannel}.
- * <br>These are the "<i>normal</i>" message channels that are present in the channel sidebar.
- * These are <b>not</b> {@link ThreadChannel ThreadChannels}.
+ * Represents a {@link GuildChannel} that is capable of utilizing <a href="https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks" target="_blank">webhooks</a>.
  *
- * @see net.dv8tion.jda.api.entities.GuildMessageChannel
- * @see TextChannel
- * @see NewsChannel
+ * Webhooks can be used to integrate third-party systems into Discord by way of sending information via messages.
  */
-public interface BaseGuildMessageChannel extends GuildMessageChannel, IThreadContainer, GuildChannel, ICategorizableChannel, ICopyableChannel, IPermissionContainer, IMemberContainer, IInviteContainer, IPositionableChannel
+public interface IWebhookContainer extends GuildChannel
 {
-    //TODO-v5: Docs
-    @Override
-    @Nonnull
-    BaseGuildMessageChannelManager<?, ?> getManager();
-
-    /**
-     * The topic set for this TextChannel.
-     * <br>If no topic has been set, this returns null.
-     *
-     * @return Possibly-null String containing the topic of this TextChannel.
-     */
-    @Nullable
-    String getTopic();
-
-    /**
-     * Whether or not this channel is considered as "NSFW" (Not-Safe-For-Work)
-     *
-     * @return True, If this TextChannel is considered NSFW by the official Discord Client
-     */
-    boolean isNSFW();
-
-    /**
-     * Retrieves the {@link net.dv8tion.jda.api.entities.Webhook Webhooks} attached to this TextChannel.
+     /**
+     * Retrieves the {@link net.dv8tion.jda.api.entities.Webhook Webhooks} attached to this channel.
      *
      * <p>Possible ErrorResponses include:
      * <ul>
@@ -102,7 +89,7 @@ public interface BaseGuildMessageChannel extends GuildMessageChannel, IThreadCon
      * <p>Possible ErrorResponses include:
      * <ul>
      *     <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_WEBHOOK}
-     *     <br>The provided id does not refer to a WebHook present in this TextChannel, either due
+     *     <br>The provided id does not refer to a WebHook present in this channel, either due
      *         to it not existing or having already been deleted.</li>
      *
      *     <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#UNKNOWN_CHANNEL UNKNOWN_CHANNEL}
@@ -130,14 +117,4 @@ public interface BaseGuildMessageChannel extends GuildMessageChannel, IThreadCon
     @Nonnull
     @CheckReturnValue
     AuditableRestAction<Void> deleteWebhookById(@Nonnull String id);
-
-    @Override
-    @Nonnull
-    @CheckReturnValue
-    ChannelAction<? extends BaseGuildMessageChannel> createCopy(@Nonnull Guild guild);
-
-    @Override
-    @Nonnull
-    @CheckReturnValue
-    ChannelAction<? extends BaseGuildMessageChannel> createCopy();
 }

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

@@ -19,6 +19,7 @@
 import net.dv8tion.jda.annotations.Incubating;
 import net.dv8tion.jda.api.JDA;
 import net.dv8tion.jda.api.OnlineStatus;
+import net.dv8tion.jda.api.entities.channel.unions.DefaultGuildChannelUnion;
 import net.dv8tion.jda.api.entities.emoji.RichCustomEmoji;
 import net.dv8tion.jda.api.requests.restaction.AuditableRestAction;
 import net.dv8tion.jda.api.utils.ImageProxy;
@@ -423,18 +424,18 @@ default ImageProxy getEffectiveAvatar()
     boolean isPending();
 
     /**
-     * The default {@link net.dv8tion.jda.api.entities.BaseGuildMessageChannel BaseGuildMessageChannel} for a {@link net.dv8tion.jda.api.entities.Member Member}.
+     * The {@link DefaultGuildChannelUnion default channel} for a {@link net.dv8tion.jda.api.entities.Member Member}.
      * <br>This is the channel that the Discord client will default to opening when a Guild is opened for the first time
      * after joining the guild.
      * <br>The default channel is the channel with the highest position in which the member has
      * {@link net.dv8tion.jda.api.Permission#VIEW_CHANNEL Permission.VIEW_CHANNEL} permissions. If this requirement doesn't apply for
      * any channel in the guild, this method returns {@code null}.
      *
-     * @return The {@link net.dv8tion.jda.api.entities.BaseGuildMessageChannel BaseGuildMessageChannel} representing the default channel for this member
+     * @return The {@link DefaultGuildChannelUnion channel} representing the default channel for this member
      *         or null if no such channel exists.
      */
     @Nullable
-    BaseGuildMessageChannel getDefaultChannel();
+    DefaultGuildChannelUnion getDefaultChannel();
 
     /**
      * Bans this Member and deletes messages sent by the user based on the amount of delDays.