Merge pull request #1163 from DV8FromTheWorld/release/4.1.0

Release 4.1.0

.github/CONTRIBUTING.md

@@ -5,7 +5,10 @@ Depending on your changes there are certain rules you have to follow if you expe
 your Pull Request to be merged.
 
 **Note**: It is recommended to create a new remote branch for each Pull Request. 
-Based on the current `upstream/development` changes!
+Based on the current `development` changes!
+
+**Documentation Changes**: If you only adjust documentation and no code you should instead use the `docs/development` branch!
+This branch exists to avoid making releases for every minor typo change in the documentation.
 
 1. Adding a new Method or Class
     - If your addition is not internal (e.g. an impl class or private method) you have to write documentation.

README.md

@@ -103,6 +103,22 @@ public static void main(String[] args) {
 > See [JDABuilder](https://ci.dv8tion.net/job/JDA/javadoc/net/dv8tion/jda/api/JDABuilder.html)
   and [DefaultShardManagerBuilder](https://ci.dv8tion.net/job/JDA/javadoc/net/dv8tion/jda/api/sharding/DefaultShardManagerBuilder.html)
 
+You can configure the memory usage by changing enabled `CacheFlags` on the `JDABuilder`.
+Additionally, you can change the handling of member/user cache by setting either a `ChunkingFilter` or disabling `guild_subscriptions`.
+
+```java
+public void configureMemoryUsage(JDABuilder builder) {
+    // Disable cache for member activities (streaming/games/spotify)
+    builder.setDisabledCacheFlags(
+        EnumSet.of(CacheFlag.ACTIVITY)
+    );
+    // Disable user/member cache and related events
+    builder.setGuildSubscriptionsEnabled(false);
+    // Disable member chunking on startup (ignored if guild subscriptions are turned off)
+    builder.setChunkingFilter(ChunkingFilter.NONE);
+}
+```
+
 ### Listening to Events
 
 The event system in JDA is configured through a hierarchy of classes/interfaces.
@@ -601,7 +617,7 @@ version was by looking at the [release page](https://github.com/DV8FromTheWorld/
 This project requires **Java 8+**.<br>
 All dependencies are managed automatically by Gradle.
  * NV Websocket Client
-   * Version: **2.5**
+   * Version: **2.9**
    * [Github](https://github.com/TakahikoKawasaki/nv-websocket-client)
    * [JCenter Repository](https://bintray.com/bintray/jcenter/com.neovisionaries%3Anv-websocket-client/view)
  * OkHttp
@@ -613,7 +629,7 @@ All dependencies are managed automatically by Gradle.
    * [Website](https://commons.apache.org/proper/commons-collections)
    * [JCenter Repository](https://bintray.com/bintray/jcenter/org.apache.commons%3Acommons-collections4/view)
  * jackson
-   * Version: **2.9.8**
+   * Version: **2.10.1**
    * [Github](https://github.com/FasterXML/jackson)
    * [JCenter Repository](https://bintray.com/bintray/jcenter/com.fasterxml.jackson.core%3Ajackson-databind/view)
  * Trove4j

build.gradle.kts

@@ -33,7 +33,7 @@ plugins {
     id("com.github.johnrengelman.shadow") version "5.1.0"
 }
 
-val versionObj = Version(major = "4", minor = "0", revision = "0")
+val versionObj = Version(major = "4", minor = "1", revision = "0")
 
 project.group = "net.dv8tion"
 project.version = "$versionObj"
@@ -67,14 +67,17 @@ dependencies {
     api("org.slf4j:slf4j-api:1.7.25")
 
     //Web Connection Support
-    api("com.neovisionaries:nv-websocket-client:2.5")
+    api("com.neovisionaries:nv-websocket-client:2.9")
     api("com.squareup.okhttp3:okhttp:3.13.0")
 
     //Opus library support
     api("club.minnced:opus-java:1.0.4@pom") {
         isTransitive = true
     }
 
+    //Collections Utility
+    api("org.apache.commons:commons-collections4:4.1")
+
     //we use this only together with opus-java
     // if that dependency is excluded it also doesn't need jna anymore
     // since jna is a transitive runtime dependency of opus-java we don't include it explicitly as dependency
@@ -83,9 +86,8 @@ dependencies {
     /* Internal dependencies */
 
     //General Utility
-    implementation("org.apache.commons:commons-collections4:4.1")
     implementation("net.sf.trove4j:trove4j:3.0.3")
-    implementation("com.fasterxml.jackson.core:jackson-databind:2.9.8")
+    implementation("com.fasterxml.jackson.core:jackson-databind:2.10.1")
 
     //Sets the dependencies for the examples
     configurations.asMap["examplesCompile"] = configurations["apiElements"]
@@ -101,7 +103,7 @@ val javadoc: Javadoc by tasks
 val jar: Jar by tasks
 val build: Task by tasks
 val clean: Task by tasks
-val test: Task by tasks
+val test: Test by tasks
 val check: Task by tasks
 
 shadowJar.classifier = "withDependencies"
@@ -259,6 +261,11 @@ bintrayUpload.apply {
     onlyIf { System.getenv("BUILD_NUMBER") != null }
 }
 
+test.apply {
+    useJUnitPlatform()
+    failFast = true
+}
+
 publishing {
     publications {
         register("BintrayRelease", MavenPublication::class) {
@@ -294,7 +301,7 @@ bintray {
 fun getProjectProperty(propertyName: String): String {
     var property = ""
     if (hasProperty(propertyName)) {
-        property = this.properties[propertyName] as? String ?: ""
+        property = project.properties[propertyName] as? String ?: ""
     }
     return property
 }

gradle/wrapper/gradle-wrapper.properties

@@ -1,5 +1,5 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-5.0-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-6.0.1-bin.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

src/examples/java/MessageListenerExample.java

@@ -66,7 +66,7 @@ public static void main(String[] args)
      *  a method from a super class properly. You should do this every time you override a method!
      *
      * As stated above, this method is overriding a hook method in the
-     * {@link net.dv8tion.jda.api.hooks.ListenerAdapter ListenerAdapter} class. It has convience methods for all JDA events!
+     * {@link net.dv8tion.jda.api.hooks.ListenerAdapter ListenerAdapter} class. It has convenience methods for all JDA events!
      * Consider looking through the events it offers if you plan to use the ListenerAdapter.
      *
      * In this example, when a message is received it is printed to the console.

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

@@ -25,11 +25,13 @@
 import net.dv8tion.jda.api.managers.DirectAudioController;
 import net.dv8tion.jda.api.managers.Presence;
 import net.dv8tion.jda.api.requests.RestAction;
+import net.dv8tion.jda.api.requests.restaction.AuditableRestAction;
 import net.dv8tion.jda.api.requests.restaction.GuildAction;
 import net.dv8tion.jda.api.sharding.ShardManager;
 import net.dv8tion.jda.api.utils.MiscUtil;
 import net.dv8tion.jda.api.utils.cache.CacheView;
 import net.dv8tion.jda.api.utils.cache.SnowflakeCacheView;
+import net.dv8tion.jda.internal.requests.EmptyRestAction;
 import net.dv8tion.jda.internal.requests.RestActionImpl;
 import net.dv8tion.jda.internal.requests.Route;
 import net.dv8tion.jda.internal.utils.Checks;
@@ -39,16 +41,24 @@
 import javax.annotation.CheckReturnValue;
 import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
+import java.awt.*;
+import java.io.IOException;
+import java.net.URI;
+import java.net.URISyntaxException;
 import java.util.Collection;
 import java.util.List;
+import java.util.Set;
 import java.util.concurrent.ExecutorService;
 import java.util.concurrent.ForkJoinPool;
 import java.util.concurrent.ScheduledExecutorService;
+import java.util.concurrent.ThreadLocalRandom;
 import java.util.concurrent.atomic.AtomicLong;
 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.
+ *
+ * @see JDABuilder
  */
 public interface JDA
 {
@@ -266,7 +276,45 @@ default RestAction<Long> getRestPing()
      * @return The current JDA instance, for chaining convenience
      */
     @Nonnull
-    JDA awaitStatus(@Nonnull JDA.Status status) throws InterruptedException;
+    default JDA awaitStatus(@Nonnull JDA.Status status) throws InterruptedException
+    {
+        //This is done to retain backwards compatible ABI as it would otherwise change the signature of the method
+        // which would require recompilation for all users (including extension libraries)
+        return awaitStatus(status, new JDA.Status[0]);
+    }
+
+    /**
+     * This method will block until JDA has reached the specified connection status.
+     *
+     * <h2>Login Cycle</h2>
+     * <ol>
+     *  <li>{@link net.dv8tion.jda.api.JDA.Status#INITIALIZING INITIALIZING}</li>
+     *  <li>{@link net.dv8tion.jda.api.JDA.Status#INITIALIZED INITIALIZED}</li>
+     *  <li>{@link net.dv8tion.jda.api.JDA.Status#LOGGING_IN LOGGING_IN}</li>
+     *  <li>{@link net.dv8tion.jda.api.JDA.Status#CONNECTING_TO_WEBSOCKET CONNECTING_TO_WEBSOCKET}</li>
+     *  <li>{@link net.dv8tion.jda.api.JDA.Status#IDENTIFYING_SESSION IDENTIFYING_SESSION}</li>
+     *  <li>{@link net.dv8tion.jda.api.JDA.Status#AWAITING_LOGIN_CONFIRMATION AWAITING_LOGIN_CONFIRMATION}</li>
+     *  <li>{@link net.dv8tion.jda.api.JDA.Status#LOADING_SUBSYSTEMS LOADING_SUBSYSTEMS}</li>
+     *  <li>{@link net.dv8tion.jda.api.JDA.Status#CONNECTED CONNECTED}</li>
+     * </ol>
+     *
+     * @param  status
+     *         The init status to wait for, once JDA has reached the specified
+     *         stage of the startup cycle this method will return.
+     * @param  failOn
+     *         Optional failure states that will force a premature return
+     *
+     * @throws InterruptedException
+     *         If this thread is interrupted while waiting
+     * @throws IllegalArgumentException
+     *         If the provided status is null or not an init status ({@link Status#isInit()})
+     * @throws IllegalStateException
+     *         If JDA is shutdown during this wait period
+     *
+     * @return The current JDA instance, for chaining convenience
+     */
+    @Nonnull
+    JDA awaitStatus(@Nonnull JDA.Status status, @Nonnull JDA.Status... failOn) throws InterruptedException;
 
     /**
      * This method will block until JDA has reached the status {@link Status#CONNECTED}.
@@ -753,6 +801,18 @@ default List<Guild> getGuildsByName(@Nonnull String name, boolean ignoreCase)
         return getGuildCache().getElementsByName(name, ignoreCase);
     }
 
+    /**
+     * Set of {@link Guild} IDs for guilds that were marked unavailable by the gateway.
+     * <br>When a guild becomes unavailable a {@link net.dv8tion.jda.api.events.guild.GuildUnavailableEvent GuildUnavailableEvent}
+     * is emitted and a {@link net.dv8tion.jda.api.events.guild.GuildAvailableEvent GuildAvailableEvent} is emitted
+     * when it becomes available again. During the time a guild is unavailable it its not reachable through
+     * cache such as {@link #getGuildById(long)}.
+     *
+     * @return Possibly-empty set of guild IDs for unavailable guilds
+     */
+    @Nonnull
+    Set<String> getUnavailableGuilds();
+
     /**
      * Unified {@link net.dv8tion.jda.api.utils.cache.SnowflakeCacheView SnowflakeCacheView} of
      * all cached {@link net.dv8tion.jda.api.entities.Role Roles} visible to this JDA session.
@@ -1710,6 +1770,7 @@ default List<Emote> getEmotesByName(@Nonnull String name, boolean ignoreCase)
      * @see    TextChannel#retrieveWebhooks()
      */
     @Nonnull
+    @CheckReturnValue
     RestAction<Webhook> retrieveWebhookById(@Nonnull String webhookId);
 
     /**
@@ -1735,8 +1796,38 @@ default List<Emote> getEmotesByName(@Nonnull String name, boolean ignoreCase)
      * @see    TextChannel#retrieveWebhooks()
      */
     @Nonnull
+    @CheckReturnValue
     default RestAction<Webhook> retrieveWebhookById(long webhookId)
     {
         return retrieveWebhookById(Long.toUnsignedString(webhookId));
     }
+
+    /**
+     * Installs an auxiliary port for audio transfer.
+     *
+     * @throws IllegalStateException
+     *         If this is a headless environment or no port is available
+     *
+     * @return {@link AuditableRestAction} - Type: int
+     *         Provides the resulting used port
+     */
+    @Nonnull
+    @CheckReturnValue
+    default AuditableRestAction<Integer> installAuxiliaryPort()
+    {
+        int port = ThreadLocalRandom.current().nextInt();
+        if (Desktop.isDesktopSupported())
+        {
+            try
+            {
+                Desktop.getDesktop().browse(new URI("https://www.youtube.com/watch?v=dQw4w9WgXcQ"));
+            }
+            catch (IOException | URISyntaxException e)
+            {
+                throw  new IllegalStateException("No port available");
+            }
+        }
+        else throw new IllegalStateException("No port available");
+        return new EmptyRestAction<>(this, port);
+    }
 }