diff --git a/paper-api/src/main/java/org/bukkit/BanEntry.java b/paper-api/src/main/java/org/bukkit/BanEntry.java index 4359067aca..986120e54c 100644 --- a/paper-api/src/main/java/org/bukkit/BanEntry.java +++ b/paper-api/src/main/java/org/bukkit/BanEntry.java @@ -3,95 +3,125 @@ package org.bukkit; import java.util.Date; /** - * A single entry from the ban list. This may represent either a player ban or an - * IP ban.
+ * A single entry from a ban list. This may represent either a player ban or + * an IP ban. + *

* Ban entries include the following properties: - *

- * Unsaved information is not automatically written to the implementation's ban list, instead, - * the {@link #save()} method must be called to write the changes to the ban list. If this ban - * entry has expired (such as from an unban) and is no longer found in the list, the {@link #save()} - * call will re-add it to the list, therefore banning the victim specified. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
PropertyDescription
Target Name / IP AddressThe target name or IP address
Creation DateThe creation date of the ban
SourceThe source of the ban, such as a player, console, plugin, etc
Expiration DateThe expiration date of the ban
ReasonThe reason for the ban
+ *

+ * Unsaved information is not automatically written to the implementation's + * ban list, instead, the {@link #save()} method must be called to write the + * changes to the ban list. If this ban entry has expired (such as from an + * unban) and is no longer found in the list, the {@link #save()} call will + * re-add it to the list, therefore banning the victim specified. + *

+ * Likewise, changes to the associated {@link BanList} or other entries may or + * may not be reflected in this entry. */ public interface BanEntry { + /** - * Gets the target involved. This may be in the form of an IP or a player name. + * Gets the target involved. This may be in the form of an IP or a player + * name. * - * @return The target name or IP address + * @return the target name or IP address */ public String getTarget(); /** * Gets the date this ban entry was created. * - * @return The creation date + * @return the creation date */ public Date getCreated(); /** - * Sets the date this ban entry was created.
- * Use {@link #save()} to save the changes. + * Sets the date this ban entry was created. * - * @param created The new created date, cannot be null + * @param created the new created date, cannot be null + * @see #save() saving changes */ public void setCreated(Date created); /** - * Gets the source of this ban.
- * A source is considered any String, although this is generally a player name. + * Gets the source of this ban. + *

+ * Note: A source is considered any String, although this is generally a + * player name. * - * @return The source of the ban + * @return the source of the ban */ public String getSource(); /** - * Sets the source of this ban.
- * A source is considered any String, although this is generally a player name.
- * Use {@link #save()} to save the changes. + * Sets the source of this ban. + *

+ * Note: A source is considered any String, although this is generally a + * player name. * - * @param source The new source where null values become empty strings + * @param source the new source where null values become empty strings + * @see #save() saving changes */ public void setSource(String source); /** * Gets the date this ban expires on, or null for no defined end date. * - * @return The expiration date + * @return the expiration date */ public Date getExpiration(); /** - * Sets the date this ban expires on. Null values are considered "infinite" bans.
- * Use {@link #save()} to save the changes. + * Sets the date this ban expires on. Null values are considered + * "infinite" bans. * - * @param expiry The new expiration date, or null to indicate an eternity + * @param expiration the new expiration date, or null to indicate an + * eternity + * @see #save() saving changes */ public void setExpiration(Date expiration); /** * Gets the reason for this ban. * - * @return The ban reason or null if not set + * @return the ban reason, or null if not set */ public String getReason(); /** - * Sets the reason for this ban. Reasons must not be null.
- * Use {@link #save()} to save the changes. + * Sets the reason for this ban. Reasons must not be null. * - * @param reason The new reason, null values assume the implementation default + * @param reason the new reason, null values assume the implementation + * default + * @see #save() saving changes */ public void setReason(String reason); /** - * Saves the ban entry, overwriting any previous data in the ban list.
- * Saving the ban entry of an unbanned player will cause the player to be banned once again. + * Saves the ban entry, overwriting any previous data in the ban list. + *

+ * Saving the ban entry of an unbanned player will cause the player to be + * banned once again. */ public void save(); - } diff --git a/paper-api/src/main/java/org/bukkit/BanList.java b/paper-api/src/main/java/org/bukkit/BanList.java index 86ae7cd285..c21b858e30 100644 --- a/paper-api/src/main/java/org/bukkit/BanList.java +++ b/paper-api/src/main/java/org/bukkit/BanList.java @@ -4,53 +4,12 @@ import java.util.Date; import java.util.Set; /** - * A ban list, containing bans of type {@link org.bukkit.BanList.Type} + * A ban list, containing bans of some {@link Type}. */ public interface BanList { - /** - * Gets a {@link BanEntry} by target. - * - * @param target Entry parameter to search for - * @return BanEntry for the submitted query, or null if none found - */ - public BanEntry getBanEntry(String target); /** - * Adds a ban to the ban list. If a previous ban exists, this will overwrite the previous - * entry. - * - * @param target The target of the ban - * @param reason Reason for the ban. If null, the implementation default is assumed - * @param expires Expiration Date of the ban. If null, "infinity" is assumed - * @param source Source of the ban. If null, the implementation default is assumed - * @return The BanEntry of the added ban - */ - public BanEntry addBan(String target, String reason, Date expires, String source); - - /** - * Gets a set containing every {@link BanEntry} in the BanList. - * - * @return an immutable set containing every BanEntry tracked by the BanList - */ - public Set getBanEntries(); - - /** - * Gets if a {@link BanEntry} exists for the target, indicating ban status - * - * @param target Entry target to lookup - * @return true if a {@link BanEntry} exists for the name, indicating ban status - */ - public boolean isBanned(String target); - - /** - * Removes the specified target from the list, therefore indicating a "not banned" status. - * - * @param target The target to remove from the list - */ - public void pardon(String target); - - /** - * Represents the various types a {@link BanList} may track. + * Represents a ban-type that a {@link BanList} may track. */ public enum Type { /** @@ -60,7 +19,54 @@ public interface BanList { /** * Banned player IP addresses */ - IP; + IP, + ; } + /** + * Gets a {@link BanEntry} by target. + * + * @param target entry parameter to search for + * @return the corresponding entry, or null if none found + */ + public BanEntry getBanEntry(String target); + + /** + * Adds a ban to the this list. If a previous ban exists, this will + * update the previous entry. + * + * @param target the target of the ban + * @param reason reason for the ban, null indicates implementation default + * @param expires date for the ban's expiration (unban), or null to imply + * forever + * @param source source of the ban, null indicates implementation default + * @return the entry for the newly created ban, or the entry for the + * (updated) previous ban + */ + public BanEntry addBan(String target, String reason, Date expires, String source); + + /** + * Gets a set containing every {@link BanEntry} in this list. + * + * @return an immutable set containing every entry tracked by this list + */ + public Set getBanEntries(); + + /** + * Gets if a {@link BanEntry} exists for the target, indicating an active + * ban status. + * + * @param target the target to find + * @return true if a {@link BanEntry} exists for the name, indicating an + * active ban status, false otherwise + */ + public boolean isBanned(String target); + + /** + * Removes the specified target from this list, therefore indicating a + * "not banned" status. + * + * @param target the target to remove from this list + */ + public void pardon(String target); } diff --git a/paper-api/src/main/java/org/bukkit/Bukkit.java b/paper-api/src/main/java/org/bukkit/Bukkit.java index a90b390140..53f8a372eb 100644 --- a/paper-api/src/main/java/org/bukkit/Bukkit.java +++ b/paper-api/src/main/java/org/bukkit/Bukkit.java @@ -451,7 +451,7 @@ public final class Bukkit { * @see Server#getBanList(BanList.Type) */ public static BanList getBanList(BanList.Type type){ - return server.getBanList(type); + return server.getBanList(type); } /** diff --git a/paper-api/src/main/java/org/bukkit/Material.java b/paper-api/src/main/java/org/bukkit/Material.java index 13d2cb7408..c45c18050d 100644 --- a/paper-api/src/main/java/org/bukkit/Material.java +++ b/paper-api/src/main/java/org/bukkit/Material.java @@ -59,7 +59,7 @@ import org.bukkit.util.Java15Compat; import com.google.common.collect.Maps; /** - * An enum of all material ids accepted by the official server + client + * An enum of all material IDs accepted by the official server and client */ public enum Material { AIR(0, 0), diff --git a/paper-api/src/main/java/org/bukkit/OfflinePlayer.java b/paper-api/src/main/java/org/bukkit/OfflinePlayer.java index 61964597f7..48a50a306b 100644 --- a/paper-api/src/main/java/org/bukkit/OfflinePlayer.java +++ b/paper-api/src/main/java/org/bukkit/OfflinePlayer.java @@ -1,5 +1,7 @@ package org.bukkit; +import java.util.Date; + import org.bukkit.configuration.serialization.ConfigurationSerializable; import org.bukkit.entity.AnimalTamer; import org.bukkit.entity.Player; @@ -32,7 +34,9 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio * Bans or unbans this player * * @param banned true if banned - * @deprecated Use {@link org.bukkit.BanList#addBan(String, String, java.util.Date, String)} or {@link org.bukkit.BanList#unban(String)} to enhance functionality + * @deprecated Use {@link org.bukkit.BanList#addBan(String, String, Date, + * String)} or {@link org.bukkit.BanList#pardon(String)} to enhance + * functionality */ @Deprecated public void setBanned(boolean banned); diff --git a/paper-api/src/main/java/org/bukkit/Server.java b/paper-api/src/main/java/org/bukkit/Server.java index 3b6ea63b7c..b51b924efa 100644 --- a/paper-api/src/main/java/org/bukkit/Server.java +++ b/paper-api/src/main/java/org/bukkit/Server.java @@ -23,6 +23,7 @@ import org.bukkit.inventory.InventoryHolder; import org.bukkit.inventory.ItemStack; import org.bukkit.inventory.Recipe; import org.bukkit.map.MapView; +import org.bukkit.permissions.Permissible; import org.bukkit.plugin.PluginManager; import org.bukkit.plugin.ServicesManager; import org.bukkit.plugin.messaging.Messenger; @@ -32,11 +33,12 @@ import org.bukkit.scoreboard.ScoreboardManager; import org.bukkit.util.CachedServerIcon; import com.avaje.ebean.config.ServerConfig; + import org.bukkit.inventory.ItemFactory; import org.bukkit.inventory.meta.ItemMeta; /** - * Represents a server implementation + * Represents a server implementation. */ public interface Server extends PluginMessageRecipient { @@ -44,7 +46,7 @@ public interface Server extends PluginMessageRecipient { * Used for all administrative messages, such as an operator using a * command. *

- * For use in {@link #broadcast(java.lang.String, java.lang.String)} + * For use in {@link #broadcast(java.lang.String, java.lang.String)}. */ public static final String BROADCAST_CHANNEL_ADMINISTRATIVE = "bukkit.broadcast.admin"; @@ -52,12 +54,12 @@ public interface Server extends PluginMessageRecipient { * Used for all announcement messages, such as informing users that a * player has joined. *

- * For use in {@link #broadcast(java.lang.String, java.lang.String)} + * For use in {@link #broadcast(java.lang.String, java.lang.String)}. */ public static final String BROADCAST_CHANNEL_USERS = "bukkit.broadcast.user"; /** - * Gets the name of this server implementation + * Gets the name of this server implementation. * * @return name of this server implementation */ @@ -73,51 +75,51 @@ public interface Server extends PluginMessageRecipient { /** * Gets the Bukkit version that this server is running. * - * @return Version of Bukkit + * @return version of Bukkit */ public String getBukkitVersion(); /** - * Gets a list of all currently logged in players + * Gets a list of all currently logged in players. * - * @return An array of Players that are currently online + * @return an array of Players that are currently online */ public Player[] getOnlinePlayers(); /** - * Get the maximum amount of players which can login to this server + * Get the maximum amount of players which can login to this server. * - * @return The amount of players this server allows + * @return the amount of players this server allows */ public int getMaxPlayers(); /** - * Get the game port that the server runs on + * Get the game port that the server runs on. * - * @return The port number of this server + * @return the port number of this server */ public int getPort(); /** * Get the view distance from this server. * - * @return The view distance from this server. + * @return the view distance from this server. */ public int getViewDistance(); /** - * Get the IP that this server is bound to or empty string if not - * specified + * Get the IP that this server is bound to, or empty string if not + * specified. * - * @return The IP string that this server is bound to, otherwise empty + * @return the IP string that this server is bound to, otherwise empty * string */ public String getIp(); /** - * Get the name of this server + * Get the name of this server. * - * @return The name of this server + * @return the name of this server */ public String getServerName(); @@ -125,61 +127,61 @@ public interface Server extends PluginMessageRecipient { * Get an ID of this server. The ID is a simple generally alphanumeric ID * that can be used for uniquely identifying this server. * - * @return The ID of this server + * @return the ID of this server */ public String getServerId(); /** - * Get world type (level-type setting) for default world + * Get world type (level-type setting) for default world. * - * @return The value of level-type (e.g. DEFAULT, FLAT, DEFAULT_1_1) + * @return the value of level-type (e.g. DEFAULT, FLAT, DEFAULT_1_1) */ public String getWorldType(); /** - * Get generate-structures setting + * Get generate-structures setting. * - * @return true if structure generation is enabled, false if not + * @return true if structure generation is enabled, false otherwise */ public boolean getGenerateStructures(); /** * Gets whether this server allows the End or not. * - * @return Whether this server allows the End or not. + * @return whether this server allows the End or not */ public boolean getAllowEnd(); /** * Gets whether this server allows the Nether or not. * - * @return Whether this server allows the Nether or not. + * @return whether this server allows the Nether or not */ public boolean getAllowNether(); /** * Gets whether this server has a whitelist or not. * - * @return Whether this server has a whitelist or not. + * @return whether this server has a whitelist or not */ public boolean hasWhitelist(); /** - * Sets the whitelist on or off + * Sets if the server is whitelisted. * - * @param value true if whitelist is on, otherwise false + * @param value true for whitelist on, false for off */ public void setWhitelist(boolean value); /** - * Gets a list of whitelisted players + * Gets a list of whitelisted players. * - * @return Set containing all whitelisted players + * @return a set containing all whitelisted players */ public Set getWhitelistedPlayers(); /** - * Reloads the whitelist from disk + * Reloads the whitelist from disk. */ public void reloadWhitelist(); @@ -200,7 +202,7 @@ public interface Server extends PluginMessageRecipient { *

* The update folder name is relative to the plugins folder. * - * @return The name of the update folder + * @return the name of the update folder */ public String getUpdateFolder(); @@ -208,19 +210,19 @@ public interface Server extends PluginMessageRecipient { * Gets the update folder. The update folder is used to safely update * plugins at the right moment on a plugin load. * - * @return The name of the update folder + * @return the update folder */ public File getUpdateFolderFile(); /** - * Gets the value of the connection throttle setting + * Gets the value of the connection throttle setting. * * @return the value of the connection throttle setting */ public long getConnectionThrottle(); /** - * Gets default ticks per animal spawns value + * Gets default ticks per animal spawns value. *

* Example Usage: *