Refactor Utils#getOnlinePlayers and add background info

src/main/java/fr/xephi/authme/util/Utils.java

@@ -17,6 +17,7 @@ import org.bukkit.entity.Entity;
 import org.bukkit.entity.Player;
 
 import java.io.*;
+import java.lang.reflect.InvocationTargetException;
 import java.lang.reflect.Method;
 import java.net.URL;
 import java.net.URLConnection;
@@ -26,23 +27,20 @@ import java.util.Collections;
 import java.util.zip.GZIPInputStream;
 
 /**
+ * Utility class for various operations used in the codebase.
  */
 public final class Utils {
 
     public static AuthMe plugin;
 
-    private static boolean getOnlinePlayersIsCollection;
+    private static boolean getOnlinePlayersIsCollection = false;
     private static Method getOnlinePlayers;
     private static LookupService lookupService;
 
     static {
         plugin = AuthMe.getInstance();
         checkGeoIP();
-        try {
-            Method m = Bukkit.class.getDeclaredMethod("getOnlinePlayers");
-            getOnlinePlayersIsCollection = m.getReturnType() == Collection.class;
-        } catch (Exception ignored) {
-        }
+        initializeOnlinePlayersIsCollectionField();
     }
 
     private Utils() {
@@ -259,9 +257,6 @@ public final class Utils {
         });
     }
 
-    /*
-     * Used for force player GameMode
-     */
     /**
      * Force the game mode of a player.
      *
@@ -300,25 +295,57 @@ public final class Utils {
         }
     }
 
+    /**
+     * Safe way to retrieve the list of online players from the server. Depending on the implementation
+     * of the server, either an array of {@link Player} instances is being returned, or a Collection.
+     * Always use this wrapper to retrieve online players instead of {@link Bukkit#getOnlinePlayers()} directly.
+     *
+     * @return collection of online players
+     *
+     * @see <a href="https://www.spigotmc.org/threads/solved-cant-use-new-getonlineplayers.33061/">SpigotMC forum</a>
+     * @see <a href="http://stackoverflow.com/questions/32130851/player-changed-from-array-to-collection">StackOverflow</a>
+     */
     @SuppressWarnings("unchecked")
     public static Collection<? extends Player> getOnlinePlayers() {
         if (getOnlinePlayersIsCollection) {
             return Bukkit.getOnlinePlayers();
         }
         try {
+            // The lookup of a method via Reflections is rather expensive, so we keep a reference to it
             if (getOnlinePlayers == null) {
                 getOnlinePlayers = Bukkit.class.getMethod("getOnlinePlayers");
             }
             Object obj = getOnlinePlayers.invoke(null);
-            if (obj instanceof Collection) {
+            if (obj instanceof Collection<?>) {
                 return (Collection<? extends Player>) obj;
+            } else if (obj instanceof Player[]) {
+                return Arrays.asList((Player[]) obj);
+            } else {
+                String type = (obj != null) ? obj.getClass().getName() : "null";
+                ConsoleLogger.showError("Unknown list of online players of type " + type);
             }
-            return Arrays.asList((Player[]) obj);
-        } catch (Exception ignored) {
+        } catch (NoSuchMethodException | IllegalAccessException | InvocationTargetException e) {
+            ConsoleLogger.showError("Could not retrieve list of online players: ["
+                    + e.getClass().getName() + "] " + e.getMessage());
         }
         return Collections.emptyList();
     }
 
+    /**
+     * Method run when the Utils class is loaded to verify whether or not the Bukkit
+     * implementation returns the online players as a Collection.
+     *
+     * @see Utils#getOnlinePlayers()
+     */
+    private static void initializeOnlinePlayersIsCollectionField() {
+        try {
+            Method method = Bukkit.class.getDeclaredMethod("getOnlinePlayers");
+            getOnlinePlayersIsCollection = method.getReturnType() == Collection.class;
+        } catch (NoSuchMethodException e) {
+            ConsoleLogger.showError("Error verifying if getOnlinePlayers is a collection! Method doesn't exist");
+        }
+    }
+
     @SuppressWarnings("deprecation")
     public static Player getPlayer(String name) {
         name = name.toLowerCase();