Documentation and Flag Changes.

Bukkit/src/main/java/com/plotsquared/bukkit/listeners/ForceFieldListener.java

@@ -6,14 +6,15 @@ import com.intellectualcrafters.plot.object.Plot;
 import com.intellectualcrafters.plot.object.PlotPlayer;
 import com.plotsquared.bukkit.object.BukkitPlayer;
 import com.plotsquared.bukkit.util.BukkitUtil;
-import java.util.HashSet;
-import java.util.Set;
-import java.util.UUID;
 import org.bukkit.entity.Entity;
 import org.bukkit.entity.Player;
 import org.bukkit.event.Listener;
 import org.bukkit.util.Vector;
 
+import java.util.HashSet;
+import java.util.Set;
+import java.util.UUID;
+
 public class ForceFieldListener implements Listener {
 
     private static Set<PlotPlayer> getNearbyPlayers(Player player, Plot plot) {

Bukkit/src/main/java/com/plotsquared/bukkit/object/BukkitPlayer.java

@@ -22,8 +22,7 @@ public class BukkitPlayer extends PlotPlayer {
     public boolean offline;
     private UUID uuid;
     private String name;
-    private long last = 0;
-    
+
     /**
      * <p>Please do not use this method. Instead use
      * BukkitUtil.getPlayer(Player), as it caches player objects.</p>
@@ -39,15 +38,7 @@ public class BukkitPlayer extends PlotPlayer {
         this.offline = offline;
         super.populatePersistentMetaMap();
     }
-    
-    @Override
-    public long getPreviousLogin() {
-        if (this.last == 0) {
-            this.last = this.player.getLastPlayed();
-        }
-        return this.last;
-    }
-    
+
     @Override
     public Location getLocation() {
         Location location = super.getLocation();
@@ -61,7 +52,11 @@ public class BukkitPlayer extends PlotPlayer {
         }
         return this.uuid;
     }
-    
+
+    @Override public long getLastPlayed() {
+        return this.player.getLastPlayed();
+    }
+
     @Override
     public boolean hasPermission(String permission) {
         if (this.offline && EconHandler.manager != null) {

Core/src/main/java/com/intellectualcrafters/configuration/ConfigurationSection.java

@@ -144,10 +144,10 @@ public interface ConfigurationSection {
      * {@link Configuration}.
      *
      * @param path Path of the Object to get.
-     * @param def The default value to return if the path is not found.
+     * @param defaultValue The default value to return if the path is not found.
      * @return Requested Object.
      */
-    Object get(String path, Object def);
+    Object get(String path, Object defaultValue);
 
     /**
      * Sets the specified path to the given value.
@@ -293,11 +293,11 @@ public interface ConfigurationSection {
      * {@link Configuration}.
      *
      * @param path Path of the boolean to get.
-     * @param def The default value to return if the path is not found or is
+     * @param defaultValue The default value to return if the path is not found or is
      *     not a boolean.
      * @return Requested boolean.
      */
-    boolean getBoolean(String path, boolean def);
+    boolean getBoolean(String path, boolean defaultValue);
 
     /**
      * Checks if the specified path is a boolean.
@@ -333,11 +333,11 @@ public interface ConfigurationSection {
      * {@link Configuration}.
      *
      * @param path Path of the double to get.
-     * @param def The default value to return if the path is not found or is
+     * @param defaultValue The default value to return if the path is not found or is
      *     not a double.
      * @return Requested double.
      */
-    double getDouble(String path, double def);
+    double getDouble(String path, double defaultValue);
 
     /**
      * Checks if the specified path is a double.

Core/src/main/java/com/intellectualcrafters/configuration/MemorySection.java

@@ -1,7 +1,5 @@
 package com.intellectualcrafters.configuration;
 
-import com.intellectualcrafters.plot.PS;
-
 import java.util.ArrayList;
 import java.util.LinkedHashMap;
 import java.util.LinkedHashSet;
@@ -324,7 +322,7 @@ public class MemorySection implements ConfigurationSection {
     }
 
     @Override
-    public Object get(String path, Object def) {
+    public Object get(String path, Object defaultValue) {
         if (path == null) {
             throw new NullPointerException("Path cannot be null");
         }
@@ -347,7 +345,7 @@ public class MemorySection implements ConfigurationSection {
         while ((i1 = path.indexOf(separator, i2 = i1 + 1)) != -1) {
             section = section.getConfigurationSection(path.substring(i2, i1));
             if (section == null) {
-                return def;
+                return defaultValue;
             }
         }
 
@@ -355,12 +353,12 @@ public class MemorySection implements ConfigurationSection {
         if (section == this) {
             Object result = this.map.get(key);
             if (result == null) {
-                return def;
+                return defaultValue;
             } else {
                 return result;
             }
         }
-        return section.get(key, def);
+        return section.get(key, defaultValue);
     }
 
     @Override
@@ -464,12 +462,12 @@ public class MemorySection implements ConfigurationSection {
     }
 
     @Override
-    public boolean getBoolean(String path, boolean def) {
-        Object val = get(path, def);
+    public boolean getBoolean(String path, boolean defaultValue) {
+        Object val = get(path, defaultValue);
         if (val instanceof Boolean) {
             return (Boolean) val;
         } else {
-            return def;
+            return defaultValue;
         }
     }
 
@@ -486,9 +484,9 @@ public class MemorySection implements ConfigurationSection {
     }
 
     @Override
-    public double getDouble(String path, double def) {
-        Object val = get(path, def);
-        return toDouble(val, def);
+    public double getDouble(String path, double defaultValue) {
+        Object val = get(path, defaultValue);
+        return toDouble(val, defaultValue);
     }
 
     @Override

Core/src/main/java/com/intellectualcrafters/plot/flag/Flag.java

@@ -18,18 +18,16 @@ public abstract class Flag<V> {
         this.name = name;
     }
 
-    public Flag reserve() {
-        reserved = true;
-        return this;
+    public void reserve() {
+        this.reserved = true;
     }
 
     public boolean isReserved() {
-        return reserved;
+        return this.reserved;
     }
 
-    public Flag unreserve() {
-        reserved = false;
-        return this;
+    public void unreserve() {
+        this.reserved = false;
     }
 
     public abstract String valueToString(Object value);

Core/src/main/java/com/intellectualcrafters/plot/flag/FlagManager.java

@@ -1,6 +1,7 @@
 package com.intellectualcrafters.plot.flag;
 
 import com.google.common.base.Optional;
+import com.google.common.collect.ImmutableSet;
 import com.intellectualcrafters.plot.PS;
 import com.intellectualcrafters.plot.database.DBFunc;
 import com.intellectualcrafters.plot.object.Plot;
@@ -10,11 +11,11 @@ import com.intellectualcrafters.plot.object.PlotPlayer;
 import com.intellectualcrafters.plot.object.PlotSettings;
 import com.intellectualcrafters.plot.util.EventUtil;
 import com.intellectualcrafters.plot.util.Permissions;
+
 import java.lang.reflect.Field;
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.HashMap;
-import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
@@ -84,13 +85,13 @@ public class FlagManager {
      * @return a set of reserved flags
      */
     public static Set<Flag<?>> getReservedFlags() {
-        HashSet<Flag<?>> reserved = new HashSet<>();
+        ImmutableSet.Builder<Flag<?>> reserved = ImmutableSet.builder();
         for (Flag flag : Flags.getFlags()) {
             if (flag.isReserved()) {
                 reserved.add(flag);
             }
         }
-        return reserved;
+        return reserved.build();
     }
 
     /**
@@ -147,7 +148,7 @@ public class FlagManager {
     }
 
     /**
-     * Add a flag to a plot
+     * Add a flag to a plot.
      * @param origin
      * @param flag
      * @param value
@@ -173,9 +174,9 @@ public class FlagManager {
     }
 
     /**
-     *
+     * Returns a map of the {@link Flag}s and their values for the specified plot.
      * @param plot the plot
-     * @return a map of flags and their values
+     * @return a map of the flags and values for the plot, returns an empty map for unowned plots
      */
     public static Map<Flag<?>, Object> getPlotFlags(Plot plot) {
         if (!plot.hasOwner()) {
@@ -276,11 +277,11 @@ public class FlagManager {
     }
 
     /**
-     * Get a list of registered {@link Flag} objects based on player permissions
+     * Get a list of registered {@link Flag} objects based on player permissions.
      *
-     * @param player with permissions
+     * @param player the player
      *
-     * @return List (Flag)
+     * @return a list of flags the specified player can use
      */
     public static List<Flag> getFlags(PlotPlayer player) {
         List<Flag> returnFlags = new ArrayList<>();
@@ -293,11 +294,11 @@ public class FlagManager {
     }
 
     /**
-     * Get a {@link Flag} specified by a {@code String}.
+     * Get a {@link Flag} specified by the specified {@code String}.
      *
      * @param string the flag name
      *
-     * @return the {@code Flag} object defined by {@code string}
+     * @return the {@code Flag} object defined by the {@code String}
      */
     public static Flag<?> getFlag(String string) {
         return Flags.getFlag(string);

Core/src/main/java/com/intellectualcrafters/plot/flag/Flags.java

@@ -6,11 +6,13 @@ import com.intellectualcrafters.plot.object.PlotArea;
 import com.intellectualcrafters.plot.object.RunnableVal;
 import com.intellectualcrafters.plot.util.MainUtil;
 import com.intellectualcrafters.plot.util.MathMan;
+
 import java.lang.reflect.Field;
 import java.util.Collection;
+import java.util.Collections;
 import java.util.HashMap;
 
-public class Flags {
+public final class Flags {
 
     public static final IntegerFlag MUSIC = new IntegerFlag("music");
     public static final StringFlag DESCRIPTION = new StringFlag("description");
@@ -116,10 +118,7 @@ public class Flags {
     static {
         flags = new HashMap<>();
         try {
-            for (Field field : Flags.class.getDeclaredFields()) {
-                if (!field.isAccessible()) {
-                    field.setAccessible(true);
-                }
+            for (Field field : Flags.class.getFields()) {
                 String fieldName = field.getName().replace("_","-").toLowerCase();
                 Object fieldValue = field.get(null);
                 if (!(fieldValue instanceof Flag)) {
@@ -131,18 +130,18 @@ public class Flags {
                 }
                 flags.put(flag.getName(), flag);
             }
-        } catch (IllegalAccessException e) {
+        } catch (Exception e) {
             e.printStackTrace();
         }
     }
 
     /**
-     * Get an immutable set of registered flags.
+     * Get an immutable collection of registered flags.
      *
-     * @return a set of registered flags.
+     * @return a collection of registered flags.
      */
     public static Collection<Flag<?>> getFlags() {
-        return flags.values();
+        return Collections.unmodifiableCollection(flags.values());
     }
 
     public static Flag<?> getFlag(String flag) {

Core/src/main/java/com/intellectualcrafters/plot/object/ConsolePlayer.java

@@ -5,6 +5,7 @@ import com.intellectualcrafters.plot.commands.RequiredType;
 import com.intellectualcrafters.plot.database.DBFunc;
 import com.intellectualcrafters.plot.util.PlotGameMode;
 import com.intellectualcrafters.plot.util.PlotWeather;
+
 import java.util.UUID;
 
 public class ConsolePlayer extends PlotPlayer {
@@ -31,11 +32,6 @@ public class ConsolePlayer extends PlotPlayer {
         return instance;
     }
 
-    @Override
-    public long getPreviousLogin() {
-        return 0;
-    }
-    
     @Override
     public Location getLocation() {
         return this.<Location>getMeta("location");
@@ -50,7 +46,11 @@ public class ConsolePlayer extends PlotPlayer {
     public UUID getUUID() {
         return DBFunc.everyone;
     }
-    
+
+    @Override public long getLastPlayed() {
+        return 0;
+    }
+
     @Override
     public boolean hasPermission(String permission) {
         return true;

Core/src/main/java/com/intellectualcrafters/plot/object/OfflinePlotPlayer.java

@@ -2,18 +2,29 @@ package com.intellectualcrafters.plot.object;
 
 import java.util.UUID;
 
-/**
- * Created 2015-02-20 for PlotSquared
- *
-
- */
 public interface OfflinePlotPlayer {
 
+    /**
+     * Get the {@code UUID} of this player
+     * @return the player {@link UUID}
+     */
     UUID getUUID();
 
+    /**
+     * Get the time in milliseconds when the player was last seen online.
+     * @return the time in milliseconds when last online
+     */
     long getLastPlayed();
 
+    /**
+     * Checks if this player is online.
+     * @return true if this player is online
+     */
     boolean isOnline();
 
+    /**
+     * Get the name of this player.
+     * @return the player name
+     */
     String getName();
 }

Core/src/main/java/com/intellectualcrafters/plot/object/Plot.java

@@ -962,12 +962,12 @@ public class Plot {
     /**
      * Get the flag for a given key
      * @param key the flag
-     * @param def if the key is null, the value to return
+     * @param defaultValue if the key is null, the value to return
      */
-    public <V> V getFlag(Flag<V> key, V def) {
+    public <V> V getFlag(Flag<V> key, V defaultValue) {
         V value = FlagManager.getPlotFlagRaw(this, key);
         if (value == null) {
-            return def;
+            return defaultValue;
         } else {
             return value;
         }
@@ -1022,7 +1022,7 @@ public class Plot {
 
     /**
      * Returns true if a previous task was running
-     * @return
+     * @return true if a previous task is running
      */
     public int addRunning() {
         int value = this.getRunning();
@@ -1208,9 +1208,7 @@ public class Plot {
         return true;
     }
 
-    /**
-     * Clear the ratings for this plot
-     */
+    /** Clear the ratings for this plot */
     public void clearRatings() {
         Plot base = this.getBasePlot(false);
         PlotSettings baseSettings = base.getSettings();
@@ -1387,7 +1385,7 @@ public class Plot {
     }
 
     /**
-     * Get the biome.
+     * Retrieve the biome of the plot.
      * @return the name of the biome
      */
     public String getBiome() {

Core/src/main/java/com/intellectualcrafters/plot/object/PlotPlayer.java

@@ -23,15 +23,12 @@ import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.atomic.AtomicInteger;
 
 /**
- * The PlotPlayer class<br>
- *  - Can cast to: BukkitPlayer / SpongePlayer, which are the current implementations<br>
+ * The abstract class supporting {@code BukkitPlayer} and {@code SpongePlayer}.
  */
-public abstract class PlotPlayer implements CommandCaller {
+public abstract class PlotPlayer implements CommandCaller, OfflinePlotPlayer {
     private Map<String, byte[]> metaMap = new HashMap<>();
 
-    /**
-     * The metadata map.
-     */
+    /** The metadata map.*/
     private ConcurrentHashMap<String, Object> meta;
 
     /**
@@ -71,9 +68,9 @@ public abstract class PlotPlayer implements CommandCaller {
 
     /**
      * Get the session metadata for a key.
-     * @param <T>
-     * @param key
-     * @return
+     * @param key the name of the metadata key
+     * @param <T> the object type to return
+     * @return the value assigned to the key or null if it does not exist
      */
     public <T> T getMeta(String key) {
         if (this.meta != null) {
@@ -82,19 +79,12 @@ public abstract class PlotPlayer implements CommandCaller {
         return null;
     }
 
-    /**
-     *
-     * @param key
-     * @param def
-     * @param <T>
-     * @return
-     */
-    public <T> T getMeta(String key, T def) {
-        if (this.meta != null) {
-            T value = (T) this.meta.get(key);
-            return value == null ? def : value;
+    public <T> T getMeta(String key, T defaultValue) {
+        T meta = getMeta(key);
+        if (meta == null) {
+            return defaultValue;
         }
-        return def;
+        return meta;
     }
 
     /**
@@ -108,8 +98,9 @@ public abstract class PlotPlayer implements CommandCaller {
     }
 
     /**
-     * Returns the player's name.
-     * @see #getName()
+     * The player's name.
+     *
+     * @return the name of the player
      */
     @Override
     public String toString() {
@@ -118,9 +109,7 @@ public abstract class PlotPlayer implements CommandCaller {
 
     /**
      * Get the player's current plot.
-     *  - This will return null if the player is standing in the road, or not in a plot world/area
-     *  - An unowned plot is still a plot, it just doesn't have any settings
-     * @return
+     * @return the plot the player is standing on or null if standing on a road or not in a {@link PlotArea}
      */
     public Plot getCurrentPlot() {
         return (Plot) getMeta("lastplot");
@@ -189,10 +178,10 @@ public abstract class PlotPlayer implements CommandCaller {
     }
 
     /**
-     * Get the plots the player owns
+     * Get a {@code Set} of plots owned by this player.
      * @see PS for more searching functions
      * @see #getPlotCount() for the number of plots
-     * @return Set of plots
+     * @return a {@code Set} of plots owned by the player
      */
     public Set<Plot> getPlots() {
         return PS.get().getPlots(this);
@@ -232,11 +221,10 @@ public abstract class PlotPlayer implements CommandCaller {
 
     ////////////////////////////////////////////////
 
-    /**
-     * Get the previous time the player logged in.
-     * @return
-     */
-    public abstract long getPreviousLogin();
+    @Deprecated
+    public long getPreviousLogin() {
+        return getLastPlayed();
+    }
 
     /**
      * Get the player's full location (including yaw/pitch)
@@ -260,18 +248,6 @@ public abstract class PlotPlayer implements CommandCaller {
      */
     public abstract void teleport(Location location);
 
-    /**
-     * Checks if the player is online.
-     * @return true if the player is online
-     */
-    public abstract boolean isOnline();
-
-    /**
-     * Retrieves the name of the player.
-     * @return the players username
-     */
-    public abstract String getName();
-
     /**
      * Set the compass target.
      * @param location the target location
@@ -311,7 +287,7 @@ public abstract class PlotPlayer implements CommandCaller {
     }
 
     /**
-     * Set the player's local weather
+     * Set the player's local weather.
      * @param weather the weather visible to the player
      */
     public abstract void setWeather(PlotWeather weather);
@@ -342,13 +318,13 @@ public abstract class PlotPlayer implements CommandCaller {
 
     /**
      * Play music at a location for the player.
-     * @param location
-     * @param id
+     * @param location where to play the music
+     * @param id the numerical record item id
      */
     public abstract void playMusic(Location location, int id);
 
     /**
-     * Check if the player is banned
+     * Check if the player is banned.
      * @return true if the player is banned, false otherwise.
      */
     public abstract boolean isBanned();
@@ -399,7 +375,7 @@ public abstract class PlotPlayer implements CommandCaller {
 
     /**
      * Get the amount of clusters a player owns.
-     * @return
+     * @return the number of clusters this player owns
      */
     public int getPlayerClusterCount() {
         final AtomicInteger count = new AtomicInteger();
@@ -413,9 +389,9 @@ public abstract class PlotPlayer implements CommandCaller {
     }
 
     /**
-     * Return a set of all plots a player owns in a certain world.
+     * Return a {@code Set} of all plots a player owns in a certain world.
      * @param world the world to retrieve plots from
-     * @return a set of plots the player owns in the provided world
+     * @return a {@code Set} of plots the player owns in the provided world
      */
     public Set<Plot> getPlots(String world) {
         UUID uuid = getUUID();
@@ -460,6 +436,10 @@ public abstract class PlotPlayer implements CommandCaller {
 
     public abstract void stopSpectating();
 
+    /**
+     * The amount of money this playe
+     * @return
+     */
     public double getMoney() {
         return EconHandler.manager == null ? 0 : EconHandler.manager.getMoney(this);
     }

Core/src/main/java/com/intellectualcrafters/plot/util/CommentManager.java

@@ -57,7 +57,7 @@ public class CommentManager {
     }
 
     public static long getTimestamp(PlotPlayer player, String inbox) {
-        return player.getMeta("inbox:" + inbox, player.getPreviousLogin());
+        return player.getMeta("inbox:" + inbox, player.getLastPlayed());
     }
 
     public static void addInbox(CommentInbox inbox) {

Core/src/main/java/com/plotsquared/general/commands/CommandCaller.java

@@ -6,13 +6,15 @@ public interface CommandCaller {
 
     /**
      * Send the player a message.
+     * @param message the message to send
      */
     void sendMessage(String message);
 
     /**
-     * Check the player's permissions. Will be cached if permission caching is enabled.
+     * Check the player's permissions. <i>Will be cached if permission caching is enabled.</i>
+     * @param permission the name of the permission
      */
-    boolean hasPermission(String perm);
+    boolean hasPermission(String permission);
     
     RequiredType getSuperCaller();
 }

Sponge/src/main/java/com/plotsquared/sponge/object/SpongePlayer.java

@@ -11,7 +11,6 @@ import com.plotsquared.sponge.util.SpongeUtil;
 import org.spongepowered.api.Sponge;
 import org.spongepowered.api.data.key.Keys;
 import org.spongepowered.api.data.manipulator.mutable.TargetedLocationData;
-import org.spongepowered.api.data.value.mutable.Value;
 import org.spongepowered.api.effect.sound.SoundTypes;
 import org.spongepowered.api.entity.living.player.Player;
 import org.spongepowered.api.entity.living.player.gamemode.GameMode;
@@ -21,7 +20,7 @@ import org.spongepowered.api.text.chat.ChatTypes;
 import org.spongepowered.api.text.serializer.TextSerializers;
 import org.spongepowered.api.world.World;
 
-import java.time.Instant;
+import java.util.Optional;
 import java.util.UUID;
 
 public class SpongePlayer extends PlotPlayer {
@@ -29,7 +28,6 @@ public class SpongePlayer extends PlotPlayer {
     public final Player player;
     private UUID uuid;
     private String name;
-    private long last = 0;
 
     public SpongePlayer(Player player) {
         this.player = player;
@@ -40,19 +38,7 @@ public class SpongePlayer extends PlotPlayer {
     public RequiredType getSuperCaller() {
         return RequiredType.PLAYER;
     }
-    
-    @Override
-    public long getPreviousLogin() {
-        if (this.last != 0) {
-            return this.last;
-        }
-        Value<Instant> data = this.player.getJoinData().lastPlayed();
-        if (data.exists()) {
-            return this.last = data.get().getEpochSecond() * 1000;
-        }
-        return 0;
-    }
-    
+
     @Override
     public Location getLocation() {
         Location location = super.getLocation();
@@ -75,7 +61,11 @@ public class SpongePlayer extends PlotPlayer {
         }
         return this.uuid;
     }
-    
+
+    @Override public long getLastPlayed() {
+        return this.player.lastPlayed().get().toEpochMilli();
+    }
+
     @Override
     public boolean hasPermission(String permission) {
         return this.player.hasPermission(permission);
@@ -234,7 +224,7 @@ public class SpongePlayer extends PlotPlayer {
 
     @Override
     public boolean isBanned() {
-        BanService service = Sponge.getServiceManager().provide(BanService.class).get();
-        return service.isBanned(this.player.getProfile());
+        Optional<BanService> service = Sponge.getServiceManager().provide(BanService.class);
+        return service.isPresent() && service.get().isBanned(this.player.getProfile());
     }
 }

Sponge/src/main/java/com/plotsquared/sponge/util/SpongeUtil.java

@@ -15,7 +15,6 @@ import com.intellectualcrafters.plot.util.StringComparison;
 import com.intellectualcrafters.plot.util.StringMan;
 import com.intellectualcrafters.plot.util.UUIDHandler;
 import com.intellectualcrafters.plot.util.WorldUtil;
-import com.plotsquared.sponge.SpongeMain;
 import com.plotsquared.sponge.object.SpongePlayer;
 import net.minecraft.block.Block;
 import net.minecraft.world.biome.Biome;
@@ -46,6 +45,7 @@ import java.lang.reflect.Field;
 import java.lang.reflect.InvocationTargetException;
 import java.lang.reflect.Method;
 import java.util.ArrayList;
+import java.util.Collection;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Locale;
@@ -246,11 +246,9 @@ public class SpongeUtil extends WorldUtil {
     }
 
     public static org.spongepowered.api.world.Location<World> getLocation(Location location) {
-        Optional<World> world = SpongeMain.THIS.getServer().getWorld(location.getWorld());
-        if (!world.isPresent()) {
-            return null;
-        }
-        return new org.spongepowered.api.world.Location<>(world.get(), location.getX(), location.getY(), location.getZ());
+        Collection<World> worlds = Sponge.getServer().getWorlds();
+        World world = Sponge.getServer().getWorld(location.getWorld()).orElse(worlds.toArray(new World[worlds.size()])[0]);
+        return new org.spongepowered.api.world.Location<>(world, location.getX(), location.getY(), location.getZ());
     }
 
     public static Location getLocation(String world, Vector3i position) {