Adds User#getMutualGuilds() (#252)

* Adds User#getMutualGuilds()
* Adds JDA#getMutualGuilds(User...), with the appropriate Collection overload

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

@@ -25,13 +25,15 @@
 import net.dv8tion.jda.core.requests.ratelimit.IBucket;
 import org.apache.http.HttpHost;
 
+import java.util.Collection;
 import java.util.List;
 
 /**
  * The core of JDA. Acts as a registry system of JDA. All parts of the the API can be accessed starting from this class.
  */
 public interface JDA
 {
+
     /**
      * Represents the connection status of JDA and its Main WebSocket.
      */
@@ -207,6 +209,26 @@ public boolean equals(Object o)
      */
     User getUserById(String id);
 
+    /**
+     * Gets all {@link net.dv8tion.jda.core.entities.Guild Guilds} that contain all given users as their members.
+     *
+     * @param  users
+     *         The users which all the returned {@link net.dv8tion.jda.core.entities.Guild Guilds} must contain.
+     *
+     * @return Unmodifiable list of all {@link net.dv8tion.jda.core.entities.Guild Guild} instances which have all {@link net.dv8tion.jda.core.entities.User Users} in them.
+     */
+    List<Guild> getMutualGuilds(User... users);
+
+    /**
+     * Gets all {@link net.dv8tion.jda.core.entities.Guild Guilds} that contain all given users as their members.
+     *
+     * @param users
+     *        The users which all the returned {@link net.dv8tion.jda.core.entities.Guild Guilds} must contain.
+     *
+     * @return Unmodifiable list of all {@link net.dv8tion.jda.core.entities.Guild Guild} instances which have all {@link net.dv8tion.jda.core.entities.User Users} in them.
+     */
+    List<Guild> getMutualGuilds(Collection<User> users);
+
     /**
      * This unmodifiable returns all {@link net.dv8tion.jda.core.entities.User Users} that have the same username as the one provided.
      * <br>If there are no {@link net.dv8tion.jda.core.entities.User Users} with the provided name, then this returns an empty list.

src/main/java/net/dv8tion/jda/core/entities/User.java

@@ -19,6 +19,8 @@
 import net.dv8tion.jda.core.JDA;
 import net.dv8tion.jda.core.requests.RestAction;
 
+import java.util.List;
+
 /**
  * Represents a Discord User.
  * Contains all publicly available information about a specific Discord User.
@@ -76,11 +78,11 @@ public interface User extends ISnowflake, IMentionable, IFakeable
      * The URL for the user's avatar image
      * If they do not have an avatar set, this will return the URL of their
      * default avatar
-     * 
+     *
      * @return  Never-null String containing the {@link net.dv8tion.jda.core.entities.User User} effective avatar url.
      */
     String getEffectiveAvatarUrl();
-    
+
     /**
      * Whether or not the currently logged in user and this user have a currently open
      * {@link net.dv8tion.jda.core.entities.PrivateChannel PrivateChannel} or not.
@@ -110,6 +112,14 @@ public interface User extends ISnowflake, IMentionable, IFakeable
      */
     RestAction<PrivateChannel> openPrivateChannel();
 
+    /**
+     * Finds and collects all {@link net.dv8tion.jda.core.entities.Guild Guild} instances that contain this {@link net.dv8tion.jda.core.entities.User User} within the current {@link net.dv8tion.jda.core.JDA JDA} instance.<br>
+     * <p>This method is a shortcut for {@link net.dv8tion.jda.core.JDA#getMutualGuilds(User...) JDA.getMutualGuilds(User)}.</p>
+     *
+     * @return Unmodifiable list of all {@link net.dv8tion.jda.core.entities.Guild Guilds} that this user is a member of.
+     */
+    List<Guild> getMutualGuilds();
+
     /**
      * Gets the {@link net.dv8tion.jda.core.entities.PrivateChannel PrivateChannel} of this
      * {@link net.dv8tion.jda.core.entities.User User} for use in sending direct messages.

src/main/java/net/dv8tion/jda/core/entities/impl/JDAImpl.java

@@ -44,10 +44,7 @@
 
 import javax.security.auth.login.LoginException;
 import java.io.IOException;
-import java.util.ArrayList;
-import java.util.Collections;
-import java.util.HashMap;
-import java.util.List;
+import java.util.*;
 import java.util.stream.Collectors;
 
 public class JDAImpl implements JDA
@@ -303,6 +300,26 @@ public User getUserById(String id)
         return users.get(id);
     }
 
+    @Override
+    public List<Guild> getMutualGuilds(User... users)
+    {
+        Args.notNull(users, "users");
+        return getMutualGuilds(Arrays.asList(users));
+    }
+
+    @Override
+    public List<Guild> getMutualGuilds(Collection<User> users)
+    {
+        Args.notNull(users, "users");
+        for(User u : users)
+        {
+            Args.notNull(u, "All users");
+        }
+        return Collections.unmodifiableList(getGuilds().stream()
+                .filter(guild -> users.stream().allMatch(guild::isMember))
+                .collect(Collectors.toList()));
+    }
+
     @Override
     public List<User> getUsersByName(String name, boolean ignoreCase)
     {

src/main/java/net/dv8tion/jda/core/entities/impl/UserImpl.java

@@ -18,6 +18,7 @@
 
 import net.dv8tion.jda.core.JDA;
 import net.dv8tion.jda.core.entities.EntityBuilder;
+import net.dv8tion.jda.core.entities.Guild;
 import net.dv8tion.jda.core.entities.PrivateChannel;
 import net.dv8tion.jda.core.entities.User;
 import net.dv8tion.jda.core.requests.Request;
@@ -26,6 +27,8 @@
 import net.dv8tion.jda.core.requests.Route;
 import org.json.JSONObject;
 
+import java.util.List;
+
 public class UserImpl implements User
 {
     protected final String id;
@@ -65,7 +68,7 @@ public String getAvatarId()
     @Override
     public String getAvatarUrl()
     {
-        return getAvatarId() == null ? null : "https://cdn.discordapp.com/avatars/" + getId() + "/" + getAvatarId() 
+        return getAvatarId() == null ? null : "https://cdn.discordapp.com/avatars/" + getId() + "/" + getAvatarId()
                 + (getAvatarId().startsWith("a_") ? ".gif" : ".png");
     }
 
@@ -86,7 +89,7 @@ public String getEffectiveAvatarUrl()
     {
         return getAvatarUrl() == null ? getDefaultAvatarUrl() : getAvatarUrl();
     }
-    
+
 
     @Override
     public boolean hasPrivateChannel()
@@ -124,6 +127,12 @@ protected void handleResponse(Response response, Request request)
         };
     }
 
+    @Override
+    public List<Guild> getMutualGuilds()
+    {
+        return getJDA().getMutualGuilds(this);
+    }
+
     @Override
     public PrivateChannel getPrivateChannel()
     {