Introduce Channel Unions

[DV8FromTheWorld]

Pull Request Etiquette

• I have checked the PRs for upcoming features/bug fixes.
• I have read the contributing guidelines.

Changes

• Internal code
• Library interface (affecting end-user code)
• Documentation
• Other: _____

Closes Issue: NaN

Description

The goal of this PR is to introduce Unions to JDA for channel types while also reworking the type hierarchy slightly to make way for ForumChannels and Messages in VoiceChannels (aka TextInVoice (TiV))

This PR changes the return types of a lot of method (basically all of them) that are the type getX : XChannel (e.g: Message#getChannel() : MessageChannel) to instead return union types (MessageChannelUnion in this case). Also, before you panic, anywhere that changed from XChannel -> XChannelUnion is completely compatible with 0 changes to existing bot/developer code because unions are extensions of the interface their representing.

Additionally, a variety of channel getters have been changed to return more limited channel classes so that they can properly represent the channel types returned. For example, the Webhook#getChannel used to return BaseGuildMessageChannel but now instead returns IWebhookContainerUnion. Read on for more info!

Unions

In JDA, a Union will represent a type that has getters on it to provide a signal to the developer of what types are available in this type. Technically this information is typically available via documentation, but we've found that this is also a great way to introduce additional discoverability.

These getters are in the format asX like asTextChannel() : TextChannel. The are effectively just casts, but they provide a method of introducing the available interfaces and types that are represented by the union. They also provide a way to introduce developers to "in-between" or "bridge" interfaces that may be useful like StandardGuildChannel or direct them to known useful casts like to IThreadContainer.

For example, the GuildMessageChannelUnion. The GuildMessageChannelUnion interface extends the GuildMessageChannel interface and differs only by providing the getters that can implement GuildMessageChannel:

• asTextChannel() : TextChannel
• asNewsChannel() : NewsChannel
• asThreadChannel() : ThreadChannel
• asStandardGuildChannel() : StandardGuildChannel
• asStandardGuildMessageChannel() : StandardGuildMessageChannel

Clean Interfaces

Another thing to note is that Unions are not directly included in the normal type hierarchy, so their asX getters are not present on the end concrete interface. For example, when looking at a TextChannel tchan = jda.getTextChannelById("...") the tchan variable will not have the asNewsChannel (nor any other asXChannel getter) on it even though TextChannel implements GuildMessageChannel. This is because the type hierarchy for TextChannel does not contain the GuildMessageChannelUnion interface, only the GuildMessageChannel interface. This means devs aren't going to have weird asX getters when they aren't needed, and this is an expectation we place on all unions going forward.

Unions are NOT wrapper objects

(This is mostly for the curious)
While the concrete type interfaces like TextChannel do not inherit from the Union classes, their XImpl (like TextChannelImpl) do implement them.

The advantage of this is 2 fold. Like mentioned before, the interfaces presented to developers are clean of these asX getters when they aren't pertinent anymore (after you've left the union type for a concrete type) however since the Impl implements it it means that when a method calls for a union (like GuildChannelMessageUnion) and we have the non union type (like GuildChannelMessage) we can confidently just cast from the normal type to the union type because we know the underlying Impl that represents that channel supports the union.

This is nice because it means we don't need special union wrappers to wrap objects to be returned by asX. The object itself is the union.

For the really curious

Given the above, here is an example
TextChannel < StandardGuildMessageChannel < StandardGuildChannel + GuildMessageChannel + ...
TextChannelImpl < StandardGuildMessageChannelImpl < StandardGuildChannelImpl + GuildChannelMessageUnion + ...

Note how the impl uses the union when building up StandardGuildMessageChannelImpl but the interface uses GuildMessageChannel when building up StandardGuildMessageChannel.

(technically the impl uses GuildMessageChannelMixin which includes the union, but I digress)

Removed Types

• BaseGuildMessageChannel
  The BGMC served as a great accumulator of all of the "attribute interfaces" (the IXChannel / IXContainer interfaces, ex: IThreadContainer) and acted as a base between TextChannel and NewsChannel. While this is really useful it cannot be reused for other messaging situations like TiV (because TiV doesn't support threads!) and we were returning BGMC from some methods that no longer can fully model the functionalities promised by BGMC like Guild#getDefaultChannel as ForumChannels can be a default channel in the future and they don't support MessageChannel!

  As such, the functionality present in this type technically lives on in a form in StandardGuildMessageChannel, but it would be wrong to say it is simply renamed. A large amount of the "base" functionality present in this interface has now been spread out across StandardGuildChannel and StandardGuildMessageChannel. Additionally, most (if not all) of the getX : BGMC getters have been changed to return a super type with a more limited set of functionalities compared to the previous usages of BGMC due needing to support future Discord changes. Going back to our Guild#getDefaultChannel it now returns DefaultGuildChannelUnion to better represent the functionalities expected by a default channel.

New Types

Channel Types

• IWebhookContainer
  Represents any channel that can add/edit/remove webhooks

• StandardGuildChannel
  Represents any of the "normal" Guild channels. These are the channels that are in the sidebar and have the "standard" functionalities expected by channels.

• StandardGuildMessageChannel
  Represents any of the "normal" message channels in a Guild. This is the bridge interface between TextChannels and NewsChannels and generally supersedes the responsibility that BaseGuildMessageChannel had previously.

Union Types

• GuildChannelUnion
  Represents the union of all GuildChannel channels.

• MessageChannelUnion
  Represents the union of all MessageChannel channels.

• GuildMessageChannelUnion
  Represents the union of all GuildMessageChannel channels.

• IWebhookContainerUnion
  Represents the union of all IWebhookContainer channels.

• IThreadContainerUnion
  Represents the union of all IThreadContainer channels.

• DefaultGuildChannelUnion
  This is a specialized Union as it doesn't follow the expected pattern defined by the "normal" unions above. This Union extends StandardGuildChannel just like StandardGuildChannelUnion but it is specialized to only have asXChannel methods for the channels that are actually viable for the Guild#getDefaultChannel and Member#getDefaultChannel methods. This is in contrast to the StandardGuildChannelUnion which has an asXChannel on it for every channel type that implements StandardGuildChannel

  In the future we may have more specialized unions that follow this pattern, but for now this is the only specialized union.

Examples

@Override
public void onMessageReceived(MessageReceivedEvent event) {
    if (!event.isFromGuild())
        return;

    GuildMessageChannelUnion union = event.getGuildChannel();

    //Methods available on this union.
    //Of course you couldn't use these all together as one of them would throw since it can only be one!
    TextChannel tChan = union.asTextChannel();
    NewsChannel nChan = union.asNewsChannel();
    ThreadChannel thChan = union.asThreadChannel();
    //etc

    //This would throw if the channel was actually a ThreadChannel,
    //  but if it isn't a ThreadChannel then it provides a lot of shared functionality to work with!
    StandardGuildMessageChannel sChan = union.asStandardGuildMessageChannel();


    // And, if you want to check the actual type, you can just use the `instanceof` checks like you already do today
    //  before doing any asX getters. Remember, they're only there to help you know what classes are available
    //  and the union is still just a normal channel at the end of the day. Typecheck and do whatever you want!
    if (!(union instanceof StandardGuildMessageChannel))
        return;

    //I don't need no stinkin' asX methods. I can cast all by myself thank-you-very-much!
    StandardGuildMessageChannel ssChan = (StandardGuildMessageChannel) union;

    //Also, like previously mentioned, the union itself _is_ the channel type it is representing
    //  which in this case is `GuildMessageChannel`, so you don't have to cast or
    //  use asX if you just need access to the methods on the interface itself
    union.sendMessage("See, just using methods on GuildMessageChannel interface!").queue();

    //Lastly, if you don't care about unions, you can stick to the types you've used up until now.
    //The union returns are just there to make things more discoverable, especially for attribute interfaces
    GuildMessageChannel channel = event.getGuildChannel();
}

[MinnDevelopment]

This PR should also move the channel interfaces into a dedicated package

[MinnDevelopment]

This PR should also address GenericChannelEvent

[DV8FromTheWorld]

PR now addresses GenericChannelEvent

[MinnDevelopment]

After addressing the MessageReaction#getGuild and the javadoc error, this should be good to go.