From 1496c69fa0d6836865507b65d42b27fcedb83759 Mon Sep 17 00:00:00 2001 From: lbenav8095 Date: Sun, 2 Apr 2023 03:45:25 -0600 Subject: [PATCH] Improves and fixes JavaDocs for Economy, IdentityEconomy and Permission --- .../net/milkbowl/vault/economy/Economy.java | 131 +++++-- .../vault/economy/IdentityEconomy.java | 66 ++-- .../milkbowl/vault/permission/Permission.java | 349 ++++++++++-------- 3 files changed, 334 insertions(+), 212 deletions(-) diff --git a/src/main/java/net/milkbowl/vault/economy/Economy.java b/src/main/java/net/milkbowl/vault/economy/Economy.java index ccb3740..bb7cc02 100644 --- a/src/main/java/net/milkbowl/vault/economy/Economy.java +++ b/src/main/java/net/milkbowl/vault/economy/Economy.java @@ -16,10 +16,10 @@ package net.milkbowl.vault.economy; -import java.util.List; - import org.bukkit.OfflinePlayer; +import java.util.List; + /** * The main economy API * @@ -28,18 +28,21 @@ public interface Economy { /** * Checks if economy method is enabled. + * * @return Success or Failure */ public boolean isEnabled(); /** * Gets name of economy method + * * @return Name of Economy Method */ public String getName(); /** * Returns true if the given implementation supports banks. + * * @return true if the implementation supports banks */ public boolean hasBankSupport(); @@ -48,6 +51,7 @@ public interface Economy { * Some economy plugins round off after a certain number of digits. * This function returns the number of digits the plugin keeps * or -1 if no rounding occurs. + * * @return number of digits after the decimal point kept */ public int fractionalDigits(); @@ -79,8 +83,9 @@ public interface Economy { public String currencyNameSingular(); /** - * - * @deprecated As of VaultAPI 1.4 use {@link #hasAccount(OfflinePlayer)} or {@link #hasAccount(UUID)} instead. + * @param playerName Name of the player. + * @return True if specified player name has an account, otherwise false. + * @deprecated As of VaultAPI 1.4 use {@link #hasAccount(OfflinePlayer)} */ @Deprecated public boolean hasAccount(String playerName); @@ -94,8 +99,12 @@ public interface Economy { * @return if the player has an account */ public boolean hasAccount(OfflinePlayer player); - + /** + * @param playerName Name of the player. + * @param worldName Name of the world. + * @return True if specified player name has an account in specific world, + * otherwise false. * @deprecated As of VaultAPI 1.4 use {@link #hasAccount(OfflinePlayer, String)} instead. */ @Deprecated @@ -105,14 +114,16 @@ public interface Economy { * Checks if this player has an account on the server yet on the given world * This will always return true if the player has joined the server at least once * as all major economy plugins auto-generate a player account when the player joins the server - * - * @param player to check in the world + * + * @param player to check in the world * @param worldName world-specific account * @return if the player has an account */ public boolean hasAccount(OfflinePlayer player, String worldName); /** + * @param playerName Name of the player. + * @return Amount currently held in players account * @deprecated As of VaultAPI 1.4 use {@link #getBalance(OfflinePlayer)} instead. */ @Deprecated @@ -127,6 +138,9 @@ public interface Economy { public double getBalance(OfflinePlayer player); /** + * @param playerName Name of the player. + * @param world Name of the world. + * @return Amount/balance currently held in players account * @deprecated As of VaultAPI 1.4 use {@link #getBalance(OfflinePlayer, String)} instead. */ @Deprecated @@ -135,13 +149,17 @@ public interface Economy { /** * Gets balance of a player on the specified world. * IMPLEMENTATION SPECIFIC - if an economy plugin does not support this the global balance will be returned. + * * @param player to check - * @param world name of the world + * @param world name of the world * @return Amount currently held in players account */ public double getBalance(OfflinePlayer player, String world); /** + * @param playerName Name of the player. + * @param amount Amount to set balance to. + * @return true if the transaction was successful, false otherwise. * @deprecated As of VaultAPI 1.4 use {@link #has(OfflinePlayer, double)} instead. */ @Deprecated @@ -157,6 +175,10 @@ public interface Economy { public boolean has(OfflinePlayer player, double amount); /** + * @param playerName Name of the player. + * @param worldName Name of the world. + * @param amount Amount to check for. + * @return True if the player has the amount in the given world, False else wise. * @deprecated As of VaultAPI 1.4 use @{link {@link #has(OfflinePlayer, String, double)} instead. */ @Deprecated @@ -165,15 +187,18 @@ public interface Economy { /** * Checks if the player account has the amount in a given world - DO NOT USE NEGATIVE AMOUNTS * IMPLEMENTATION SPECIFIC - if an economy plugin does not support this the global balance will be returned. - * - * @param player to check + * + * @param player to check * @param worldName to check with - * @param amount to check for + * @param amount to check for * @return True if player has amount in the given world, False else wise */ public boolean has(OfflinePlayer player, String worldName, double amount); /** + * @param playerName Name of the player + * @param amount Amount to withdraw + * @return Detailed response of transaction * @deprecated As of VaultAPI 1.4 use {@link #withdrawPlayer(OfflinePlayer, double)} instead. */ @Deprecated @@ -189,6 +214,10 @@ public interface Economy { public EconomyResponse withdrawPlayer(OfflinePlayer player, double amount); /** + * @param playerName Name of the player. + * @param worldName Name of the world. + * @param amount Amount to withdraw + * @return Detailed response of transaction * @deprecated As of VaultAPI 1.4 use {@link #withdrawPlayer(OfflinePlayer, String, double)} instead. */ @Deprecated @@ -197,14 +226,18 @@ public interface Economy { /** * Withdraw an amount from a player on a given world - DO NOT USE NEGATIVE AMOUNTS * IMPLEMENTATION SPECIFIC - if an economy plugin does not support this the global balance will be returned. - * @param player to withdraw from + * + * @param player to withdraw from * @param worldName - name of the world - * @param amount Amount to withdraw + * @param amount Amount to withdraw * @return Detailed response of transaction */ public EconomyResponse withdrawPlayer(OfflinePlayer player, String worldName, double amount); /** + * @param playerName Name of the player. + * @param amount Amount to deposit + * @return Detailed response of transaction * @deprecated As of VaultAPI 1.4 use {@link #depositPlayer(OfflinePlayer, double)} instead. */ @Deprecated @@ -220,6 +253,10 @@ public interface Economy { public EconomyResponse depositPlayer(OfflinePlayer player, double amount); /** + * @param playerName Name of the player. + * @param worldName Name of the world. + * @param amount Amount to deposit + * @return Detailed response of transaction * @deprecated As of VaultAPI 1.4 use {@link #depositPlayer(OfflinePlayer, String, double)} instead. */ @Deprecated @@ -228,15 +265,18 @@ public interface Economy { /** * Deposit an amount to a player on a given world - DO NOT USE NEGATIVE AMOUNTS * IMPLEMENTATION SPECIFIC - if an economy plugin does not support this the global balance will be returned. - * - * @param player to deposit to + * + * @param player to deposit to * @param worldName name of the world - * @param amount Amount to deposit + * @param amount Amount to deposit * @return Detailed response of transaction */ public EconomyResponse depositPlayer(OfflinePlayer player, String worldName, double amount); /** + * @param name of the account + * @param player to check + * @return Detailed response of transaction * @deprecated As of VaultAPI 1.4 use {{@link #createBank(String, OfflinePlayer)} instead. */ @Deprecated @@ -244,14 +284,16 @@ public interface Economy { /** * Creates a bank account with the specified name and the player as the owner - * @param name of account + * + * @param name of account * @param player the account should be linked to - * @return EconomyResponse Object + * @return Detailed response of transaction */ public EconomyResponse createBank(String name, OfflinePlayer player); /** * Deletes a bank account with the specified name. + * * @param name of the back to delete * @return if the operation completed successfully */ @@ -259,54 +301,61 @@ public interface Economy { /** * Returns the amount the bank has + * * @param name of the account - * @return EconomyResponse Object + * @return Detailed response of transaction */ public EconomyResponse bankBalance(String name); /** * Returns true or false whether the bank has the amount specified - DO NOT USE NEGATIVE AMOUNTS - * - * @param name of the account + * + * @param name of the account * @param amount to check for - * @return EconomyResponse Object + * @return Detailed response of transaction */ public EconomyResponse bankHas(String name, double amount); /** * Withdraw an amount from a bank account - DO NOT USE NEGATIVE AMOUNTS - * - * @param name of the account + * + * @param name of the account * @param amount to withdraw - * @return EconomyResponse Object + * @return Detailed response of transaction */ public EconomyResponse bankWithdraw(String name, double amount); /** * Deposit an amount into a bank account - DO NOT USE NEGATIVE AMOUNTS - * - * @param name of the account + * + * @param name of the account * @param amount to deposit - * @return EconomyResponse Object + * @return Detailed response of transaction */ public EconomyResponse bankDeposit(String name, double amount); /** - * @deprecated As of VaultAPI 1.4 use {@link #isBankOwner(String, OfflinePlayer)} or {@link #isBankOwner(String, UUID)} instead. + * @param name of the account + * @param playerName to check for ownership + * @return Detailed response of transaction + * @deprecated As of VaultAPI 1.4 use {@link #isBankOwner(String, OfflinePlayer)} instead. */ @Deprecated public EconomyResponse isBankOwner(String name, String playerName); /** * Check if a player is the owner of a bank account - * - * @param name of the account + * + * @param name of the account * @param player to check for ownership - * @return EconomyResponse Object + * @return Detailed response of transaction */ public EconomyResponse isBankOwner(String name, OfflinePlayer player); /** + * @param name of the account + * @param playerName to check for membership + * @return Detailed response of transaction * @deprecated As of VaultAPI 1.4 use {{@link #isBankMember(String, OfflinePlayer)} instead. */ @Deprecated @@ -314,33 +363,40 @@ public interface Economy { /** * Check if the player is a member of the bank account - * - * @param name of the account + * + * @param name of the account * @param player to check membership - * @return EconomyResponse Object + * @return Detailed response of transaction */ public EconomyResponse isBankMember(String name, OfflinePlayer player); /** * Gets the list of banks + * * @return the List of Banks */ public List getBanks(); /** - * @deprecated As of VaultAPI 1.4 use {@link #createPlayerAccount(OfflinePlayer)} or {@link #createPlayerAccount(UUID)} instead. + * @param playerName Name of the player + * @return if the account creation was successful + * @deprecated As of VaultAPI 1.4 use {@link #createPlayerAccount(OfflinePlayer)} instead. */ @Deprecated public boolean createPlayerAccount(String playerName); /** * Attempts to create a player account for the given player + * * @param player OfflinePlayer * @return if the account creation was successful */ public boolean createPlayerAccount(OfflinePlayer player); /** + * @param playerName Name of the player + * @param worldName Name of the world + * @return if the account creation was successful * @deprecated As of VaultAPI 1.4 use {{@link #createPlayerAccount(OfflinePlayer, String)} instead. */ @Deprecated @@ -349,7 +405,8 @@ public interface Economy { /** * Attempts to create a player account for the given player on the specified world * IMPLEMENTATION SPECIFIC - if an economy plugin does not support this then false will always be returned. - * @param player OfflinePlayer + * + * @param player OfflinePlayer * @param worldName String name of the world * @return if the account creation was successful */ diff --git a/src/main/java/net/milkbowl/vault/economy/IdentityEconomy.java b/src/main/java/net/milkbowl/vault/economy/IdentityEconomy.java index f3bfa5b..50591cc 100644 --- a/src/main/java/net/milkbowl/vault/economy/IdentityEconomy.java +++ b/src/main/java/net/milkbowl/vault/economy/IdentityEconomy.java @@ -32,13 +32,14 @@ import java.util.UUID; *

* In order to register/provide it, you should use {@link IdentityEconomyWrapper#registerProviders()} */ -public interface IdentityEconomy extends Economy{ +public interface IdentityEconomy extends Economy { /** * Used to determine if IdentityEconomy was built through * the EconomyWrapper as a LegacyEconomy. * If false, method {@link #getAllRecords()} will not be work. * This was made in order to support plugins which use older versions of VaultAPI/Vault. * You can also use it / override it to disable previous mentioned methods! + * * @return true if operation is supported */ public boolean supportsAllRecordsOperation(); @@ -49,6 +50,7 @@ public interface IdentityEconomy extends Economy{ * If false, the method {@link #getAllOnline()} (UUID)} will not be work. * This was made in order to support plugins which use older versions of VaultAPI/Vault. * You can also use it / override it to disable previous mentioned methods! + * * @return true if operation is supported */ public boolean supportsAllOnlineOperation(); @@ -60,6 +62,7 @@ public interface IdentityEconomy extends Economy{ * are online/connected to the server in real time. * If true, you should expect to call these operations * asynchronously. + * * @return true if operation is supported */ public boolean supportsOfflineOperations(); @@ -69,6 +72,7 @@ public interface IdentityEconomy extends Economy{ * the EconomyWrapper as a LegacyEconomy. * If false, you should expect UnsupportedOperationException * being thrown when calling these methods. + * * @return true if operation is supported */ public boolean supportsUUIDOperations(); @@ -79,7 +83,7 @@ public interface IdentityEconomy extends Economy{ /** * Attempts to create a account for the given uuid - * + * * @param uuid associated with the account * @param name associated with the account. * @return if the account creation was successful @@ -90,7 +94,7 @@ public interface IdentityEconomy extends Economy{ * Attempts to create an account for the given UUID on the specified world * IMPLEMENTATION SPECIFIC - if an economy plugin does not support this then * false will always be returned. - * + * * @param uuid associated with the account * @param name associated with the account. * @param worldName String name of the world @@ -103,9 +107,9 @@ public interface IdentityEconomy extends Economy{ * plugin (in the database, not memory), as well as their last-known-name. This is used for Vault's economy * converter and should be given every account available. * Needs IdentityEconomy#hasUUIDSupport() to be true. - * + * * @return a {@link Map} composed of the accounts keyed by their UUID, along - * with their associated last-known-name. + * with their associated last-known-name. */ public Map getAllRecords(); @@ -114,6 +118,7 @@ public interface IdentityEconomy extends Economy{ * online/connected to the server. * This is used for Vault's economy converter and should * Needs IdentityEconomy#hasUUIDSupport() to be true. + * * @return a {@link Collection} of all UUIDs which have accounts in the plugin */ public Collection getAllOnline(); @@ -121,14 +126,15 @@ public interface IdentityEconomy extends Economy{ /** * Gets the last known name of an account owned by the given UUID. Required for * messages to be more human-readable than UUIDs alone can provide. - * + * * @param uuid UUID to look up. + * @return the last known name of the account associated with the given UUID. */ public String getAccountName(UUID uuid); /** * Checks if this uuid has an account yet - * + * * @param uuid to check * @return if the uuid has an account */ @@ -136,7 +142,7 @@ public interface IdentityEconomy extends Economy{ /** * Checks if this uuid has an account yet on the given world - * + * * @param uuid to check * @param worldName world-specific account * @return if the uuid has an account @@ -145,18 +151,18 @@ public interface IdentityEconomy extends Economy{ /** * A method which changes the name associated with the given UUID in the - * Map received from {@link #getAllRecords()} - * + * Map<UUID, String> received from {@link #getAllRecords()} + * * @param uuid which is having a name change. - * @param name name that will be associated with the UUID in the - * Map map. + * @param name name that will be associated with the UUID in the + * Map<UUID, String> map. * @return true if the name change is successful. */ public boolean renameAccount(UUID uuid, String name); /** * Gets balance of a UUID - * + * * @param uuid of the account to get a balance for * @return Amount currently held in account associated with the given UUID */ @@ -165,7 +171,7 @@ public interface IdentityEconomy extends Economy{ /** * Gets balance of a UUID on the specified world. IMPLEMENTATION SPECIFIC - if * an economy plugin does not support this the global balance will be returned. - * + * * @param uuid of the account to get a balance for * @param world name of the world * @return Amount currently held in account associated with the given UUID @@ -175,7 +181,7 @@ public interface IdentityEconomy extends Economy{ /** * Checks if the account associated with the given UUID has the amount - DO NOT * USE NEGATIVE AMOUNTS - * + * * @param uuid to check * @param amount to check for * @return True if UUID has amount, False else wise @@ -186,19 +192,19 @@ public interface IdentityEconomy extends Economy{ * Checks if the account associated with the given UUID has the amount in the * given world - DO NOT USE NEGATIVE AMOUNTS IMPLEMENTATION SPECIFIC - if an * economy plugin does not support this the global balance will be returned. - * + * * @param uuid to check * @param worldName to check with * @param amount to check for * @return True if UUID has amount in the given world, - * False else wise + * False else wise */ public boolean has(UUID uuid, String worldName, double amount); /** * Withdraw an amount from an account associated with a UUID - DO NOT USE * NEGATIVE AMOUNTS - * + * * @param uuid to withdraw from * @param amount Amount to withdraw * @return Detailed response of transaction @@ -209,7 +215,7 @@ public interface IdentityEconomy extends Economy{ * Withdraw an amount from an account associated with a UUID on a given world - * DO NOT USE NEGATIVE AMOUNTS IMPLEMENTATION SPECIFIC - if an economy plugin * does not support this the global balance will be returned. - * + * * @param uuid to withdraw from * @param worldName - name of the world * @param amount Amount to withdraw @@ -220,7 +226,7 @@ public interface IdentityEconomy extends Economy{ /** * Deposit an amount to an account associated with the given UUID - DO NOT USE * NEGATIVE AMOUNTS - * + * * @param uuid to deposit to * @param amount Amount to deposit * @return Detailed response of transaction @@ -231,7 +237,7 @@ public interface IdentityEconomy extends Economy{ * Deposit an amount from an account associated with a UUID on a given world - * DO NOT USE NEGATIVE AMOUNTS IMPLEMENTATION SPECIFIC - if an economy plugin * does not support this the global balance will be returned. - * + * * @param uuid to deposit to * @param worldName name of the world * @param amount Amount to deposit @@ -246,7 +252,7 @@ public interface IdentityEconomy extends Economy{ /** * Creates a bank account with the specified name and the given UUID as the * owner - * + * * @param name of account * @param uuid the account should be linked to * @return EconomyResponse Object @@ -255,7 +261,7 @@ public interface IdentityEconomy extends Economy{ /** * Deletes a bank account with the specified name. - * + * * @param name of the back to delete * @return if the operation completed successfully */ @@ -263,7 +269,7 @@ public interface IdentityEconomy extends Economy{ /** * Returns the amount the bank has - * + * * @param name of the account * @return EconomyResponse Object */ @@ -272,7 +278,7 @@ public interface IdentityEconomy extends Economy{ /** * Returns true or false whether the bank has the amount specified - DO NOT USE * NEGATIVE AMOUNTS - * + * * @param name of the account * @param amount to check for * @return EconomyResponse Object @@ -281,7 +287,7 @@ public interface IdentityEconomy extends Economy{ /** * Withdraw an amount from a bank account - DO NOT USE NEGATIVE AMOUNTS - * + * * @param name of the account * @param amount to withdraw * @return EconomyResponse Object @@ -290,7 +296,7 @@ public interface IdentityEconomy extends Economy{ /** * Deposit an amount into a bank account - DO NOT USE NEGATIVE AMOUNTS - * + * * @param name of the account * @param amount to deposit * @return EconomyResponse Object @@ -299,7 +305,7 @@ public interface IdentityEconomy extends Economy{ /** * Check if a uuid is the owner of a bank account - * + * * @param name of the account * @param uuid to check for ownership * @return EconomyResponse Object @@ -308,7 +314,7 @@ public interface IdentityEconomy extends Economy{ /** * Check if the uuid is a member of the bank account - * + * * @param name of the account * @param uuid to check membership * @return EconomyResponse Object @@ -317,7 +323,7 @@ public interface IdentityEconomy extends Economy{ /** * Gets the list of banks - * + * * @return the List of Banks */ public List getBanks(); diff --git a/src/main/java/net/milkbowl/vault/permission/Permission.java b/src/main/java/net/milkbowl/vault/permission/Permission.java index 0f68eba..4328164 100644 --- a/src/main/java/net/milkbowl/vault/permission/Permission.java +++ b/src/main/java/net/milkbowl/vault/permission/Permission.java @@ -15,8 +15,6 @@ */ package net.milkbowl.vault.permission; -import java.util.logging.Logger; - import org.bukkit.OfflinePlayer; import org.bukkit.World; import org.bukkit.command.CommandSender; @@ -25,34 +23,42 @@ import org.bukkit.permissions.PermissionAttachment; import org.bukkit.permissions.PermissionAttachmentInfo; import org.bukkit.plugin.Plugin; +import java.util.logging.Logger; + /** * The main Permission API - allows for group and player based permission tests - * */ public abstract class Permission { - protected static final Logger log = Logger.getLogger("Minecraft"); + protected static final Logger log = Logger.getLogger("Minecraft"); protected Plugin plugin = null; /** * Gets name of permission method + * * @return Name of Permission Method */ abstract public String getName(); /** * Checks if permission method is enabled. + * * @return Success or Failure */ abstract public boolean isEnabled(); - + /** * Returns if the permission system is or attempts to be compatible with super-perms. + * * @return True if this permission implementation works with super-perms */ abstract public boolean hasSuperPermsCompat(); - + /** + * @param world World name + * @param player player name + * @param permission permission node + * @return true if player has permission node * @deprecated As of VaultAPI 1.4 use {@link #playerHas(String, OfflinePlayer, String)} instead. */ @Deprecated @@ -64,6 +70,10 @@ public abstract class Permission { } /** + * @param world World object + * @param player player name + * @param permission permission node + * @return true if player has permission node * @deprecated As of VaultAPI 1.4 use {@link #playerHas(String, OfflinePlayer, String)} instead. */ @Deprecated @@ -78,9 +88,10 @@ public abstract class Permission { * Checks if a CommandSender has a permission node. * This will return the result of bukkits, generic .hasPermission() method and is identical in all cases. * This method will explicitly fail if the registered permission system does not register permissions in bukkit. - * + *

* For easy checking of a commandsender - * @param sender to check permissions on + * + * @param sender to check permissions on * @param permission to check for * @return true if the sender has the permission */ @@ -90,7 +101,8 @@ public abstract class Permission { /** * Checks if player has a permission node. (Short for playerHas(...) - * @param player Player Object + * + * @param player Player Object * @param permission Permission node * @return Success or Failure */ @@ -99,12 +111,20 @@ public abstract class Permission { } /** + * @param world world name + * @param player player name + * @param permission permission node + * @return true if player has permission, false otherwise * @deprecated As of VaultAPI 1.4 use {@link #playerHas(String, OfflinePlayer, String)} instead. */ @Deprecated abstract public boolean playerHas(String world, String player, String permission); /** + * @param world World object + * @param player player name + * @param permission permission node + * @return true if player has permission, false otherwise * @deprecated As of VaultAPI 1.4 use {@link #playerHas(String, OfflinePlayer, String)} instead. */ @Deprecated @@ -114,21 +134,21 @@ public abstract class Permission { } return playerHas(world.getName(), player, permission); } - + /** * Checks if player has a permission node. * Supports NULL value for World if the permission system registered supports global permissions. * But May return odd values if the servers registered permission system does not have a global permission store. - * - * @param world String world name - * @param player to check + * + * @param world String world name + * @param player to check * @param permission Permission node * @return Success or Failure */ public boolean playerHas(String world, OfflinePlayer player, String permission) { - if (world == null) { - return has((String) null, player.getName(), permission); - } + if (world == null) { + return has((String) null, player.getName(), permission); + } return has(world, player.getName(), permission); } @@ -136,8 +156,8 @@ public abstract class Permission { * Checks if player has a permission node. * Defaults to world-specific permission check if the permission system supports it. * See {@link #playerHas(String, OfflinePlayer, String)} for explicit global or world checks. - * - * @param player Player Object + * + * @param player Player Object * @param permission Permission node * @return Success or Failure */ @@ -146,20 +166,23 @@ public abstract class Permission { } /** + * @param world World name + * @param player Player name + * @param permission Permission node + * @return Success or Failure * @deprecated As of VaultAPI 1.4 use {@link #playerAdd(String, OfflinePlayer, String)} instead. * Add permission to a player. * Supports NULL value for World if the permission system registered supports global permissions. * But May return odd values if the servers registered permission system does not have a global permission store. - * - * @param world World name - * @param player Player name - * @param permission Permission node - * @return Success or Failure */ @Deprecated abstract public boolean playerAdd(String world, String player, String permission); /** + * @param world World Object + * @param player Player name + * @param permission Permission node + * @return true if successful, false otherwise * @deprecated As of VaultAPI 1.4 use {@link #playerAdd(String, OfflinePlayer, String)} instead. */ @Deprecated @@ -174,9 +197,9 @@ public abstract class Permission { * Add permission to a player. * Supports NULL value for World if the permission system registered supports global permissions. * But May return odd values if the servers registered permission system does not have a global permission store. - * - * @param world String world name - * @param player to add to + * + * @param world String world name + * @param player to add to * @param permission Permission node * @return Success or Failure */ @@ -191,106 +214,110 @@ public abstract class Permission { * Add permission to a player ONLY for the world the player is currently on. * This is a world-specific operation, if you want to add global permission you must explicitly use NULL for the world. * See {@link #playerAdd(String, OfflinePlayer, String)} for global permission use. - * - * @param player Player Object + * + * @param player Player Object * @param permission Permission node * @return Success or Failure */ public boolean playerAdd(Player player, String permission) { return playerAdd(player.getWorld().getName(), player, permission); } - + /** * Add transient permission to a player. - * This implementation can be used by any subclass which implements a "pure" superperms plugin, i.e. + * This implementation can be used by any subclass which implements a "pure" superperms plugin, i.e. * one that only needs the built-in Bukkit API to add transient permissions to a player. - * - * @param player to add to + * + * @param player to add to * @param permission Permission node * @return Success or Failure */ public boolean playerAddTransient(OfflinePlayer player, String permission) throws UnsupportedOperationException { - if (player.isOnline()) { - return playerAddTransient((Player) player, permission); - } - throw new UnsupportedOperationException(getName() + " does not support offline player transient permissions!"); - } + if (player.isOnline()) { + return playerAddTransient((Player) player, permission); + } + throw new UnsupportedOperationException(getName() + " does not support offline player transient permissions!"); + } /** * Add transient permission to a player. * This operation adds a permission onto the player object in bukkit via Bukkit's permission interface. - * - * @param player Player Object + * + * @param player Player Object * @param permission Permission node * @return Success or Failure */ public boolean playerAddTransient(Player player, String permission) { - for (PermissionAttachmentInfo paInfo : player.getEffectivePermissions()) { - if (paInfo.getAttachment() != null && paInfo.getAttachment().getPlugin().equals(plugin)) { - paInfo.getAttachment().setPermission(permission, true); - return true; - } - } + for (PermissionAttachmentInfo paInfo : player.getEffectivePermissions()) { + if (paInfo.getAttachment() != null && paInfo.getAttachment().getPlugin().equals(plugin)) { + paInfo.getAttachment().setPermission(permission, true); + return true; + } + } - PermissionAttachment attach = player.addAttachment(plugin); - attach.setPermission(permission, true); + PermissionAttachment attach = player.addAttachment(plugin); + attach.setPermission(permission, true); - return true; + return true; } /** * Adds a world specific transient permission to the player, may only work with some permission managers. * Defaults to GLOBAL permissions for any permission system that does not support world-specific transient permissions! - * - * @param worldName to check on - * @param player to add to + * + * @param worldName to check on + * @param player to add to * @param permission to test * @return Success or Failure */ public boolean playerAddTransient(String worldName, OfflinePlayer player, String permission) { - return playerAddTransient(player, permission); + return playerAddTransient(player, permission); } - + /** * Adds a world specific transient permission to the player, may only work with some permission managers. * Defaults to GLOBAL permissions for any permission system that does not support world-specific transient permissions! - * - * @param worldName to check on - * @param player to check + * + * @param worldName to check on + * @param player to check * @param permission to check for * @return Success or Failure */ public boolean playerAddTransient(String worldName, Player player, String permission) { - return playerAddTransient(player, permission); + return playerAddTransient(player, permission); } - + /** * Removes a world specific transient permission from the player, may only work with some permission managers. * Defaults to GLOBAL permissions for any permission system that does not support world-specific transient permissions! - * - * @param worldName to remove for - * @param player to remove for + * + * @param worldName to remove for + * @param player to remove for * @param permission to remove * @return Success or Failure */ public boolean playerRemoveTransient(String worldName, OfflinePlayer player, String permission) { - return playerRemoveTransient(player, permission); + return playerRemoveTransient(player, permission); } - + /** * Removes a world specific transient permission from the player, may only work with some permission managers. * Defaults to GLOBAL permissions for any permission system that does not support world-specific transient permissions! - * - * @param worldName to check on - * @param player to check + * + * @param worldName to check on + * @param player to check * @param permission to check for * @return Success or Failure */ public boolean playerRemoveTransient(String worldName, Player player, String permission) { - return playerRemoveTransient((OfflinePlayer) player, permission); + return playerRemoveTransient((OfflinePlayer) player, permission); } - + /** + * @param world World name + * @param player player name + * @param permission Permission node + * @return true if successful, false otherwise * @deprecated As of VaultAPI 1.4 use {@link #playerRemove(String, OfflinePlayer, String)} instead. */ @Deprecated @@ -300,9 +327,9 @@ public abstract class Permission { * Remove permission from a player. * Supports NULL value for World if the permission system registered supports global permissions. * But May return odd values if the servers registered permission system does not have a global permission store. - * - * @param world World name - * @param player OfflinePlayer + * + * @param world World name + * @param player OfflinePlayer * @param permission Permission node * @return Success or Failure */ @@ -317,9 +344,9 @@ public abstract class Permission { * Remove permission from a player. * Supports NULL value for World if the permission system registered supports global permissions. * But May return odd values if the servers registered permission system does not have a global permission store. - * - * @param world World name - * @param player Player name + * + * @param world World name + * @param player Player name * @param permission Permission node * @return Success or Failure */ @@ -334,58 +361,58 @@ public abstract class Permission { /** * Remove permission from a player. * Will attempt to remove permission from the player on the player's current world. This is NOT a global operation. - * - * @param player Player Object + * + * @param player Player Object * @param permission Permission node * @return Success or Failure */ public boolean playerRemove(Player player, String permission) { return playerRemove(player.getWorld().getName(), player, permission); } - + /** * Remove transient permission from a player. - * This implementation can be used by any subclass which implements a "pure" superperms plugin, i.e. + * This implementation can be used by any subclass which implements a "pure" superperms plugin, i.e. * one that only needs the built-in Bukkit API to remove transient permissions from a player. Any subclass * implementing a plugin which provides its own API for this needs to override this method. - * - * @param player OfflinePlayer + * + * @param player OfflinePlayer * @param permission Permission node * @return Success or Failure */ - public boolean playerRemoveTransient(OfflinePlayer player, String permission) { - if (player.isOnline()) { - return playerRemoveTransient((Player) player, permission); - } else { - return false; - } - } - + public boolean playerRemoveTransient(OfflinePlayer player, String permission) { + if (player.isOnline()) { + return playerRemoveTransient((Player) player, permission); + } else { + return false; + } + } + /** * Remove transient permission from a player. - * - * @param player Player Object + * + * @param player Player Object * @param permission Permission node * @return Success or Failure */ public boolean playerRemoveTransient(Player player, String permission) { - for (PermissionAttachmentInfo paInfo : player.getEffectivePermissions()) { - if (paInfo.getAttachment() != null && paInfo.getAttachment().getPlugin().equals(plugin)) { - paInfo.getAttachment().unsetPermission(permission); - return true; - } - } - return false; + for (PermissionAttachmentInfo paInfo : player.getEffectivePermissions()) { + if (paInfo.getAttachment() != null && paInfo.getAttachment().getPlugin().equals(plugin)) { + paInfo.getAttachment().unsetPermission(permission); + return true; + } + } + return false; } - + /** * Checks if group has a permission node. * Supports NULL value for World if the permission system registered supports global permissions. * But May return odd values if the servers registered permission system does not have a global permission store. - * - * @param world World name - * @param group Group name + * + * @param world World name + * @param group Group name * @param permission Permission node * @return Success or Failure */ @@ -395,9 +422,9 @@ public abstract class Permission { * Checks if group has a permission node. * Supports NULL value for World if the permission system registered supports global permissions. * But May return odd values if the servers registered permission system does not have a global permission store. - * - * @param world World Object - * @param group Group name + * + * @param world World Object + * @param group Group name * @param permission Permission node * @return Success or Failure */ @@ -412,9 +439,9 @@ public abstract class Permission { * Add permission to a group. * Supports NULL value for World if the permission system registered supports global permissions. * But May return odd values if the servers registered permission system does not have a global permission store. - * - * @param world World name - * @param group Group name + * + * @param world World name + * @param group Group name * @param permission Permission node * @return Success or Failure */ @@ -424,9 +451,9 @@ public abstract class Permission { * Add permission to a group. * Supports NULL value for World if the permission system registered supports global permissions. * But May return odd values if the servers registered permission system does not have a global permission store. - * - * @param world World Object - * @param group Group name + * + * @param world World Object + * @param group Group name * @param permission Permission node * @return Success or Failure */ @@ -441,9 +468,9 @@ public abstract class Permission { * Remove permission from a group. * Supports NULL value for World if the permission system registered supports global permissions. * But May return odd values if the servers registered permission system does not have a global permission store. - * - * @param world World name - * @param group Group name + * + * @param world World name + * @param group Group name * @param permission Permission node * @return Success or Failure */ @@ -453,9 +480,9 @@ public abstract class Permission { * Remove permission from a group. * Supports NULL value for World if the permission system registered supports global permissions. * But May return odd values if the servers registered permission system does not have a global permission store. - * - * @param world World Object - * @param group Group name + * + * @param world World Object + * @param group Group name * @param permission Permission node * @return Success or Failure */ @@ -467,12 +494,20 @@ public abstract class Permission { } /** + * @param world World name + * @param player player name + * @param group group name + * @return true if player is in group, false otherwise * @deprecated As of VaultAPI 1.4 use {@link #playerInGroup(String, OfflinePlayer, String)} instead. */ @Deprecated abstract public boolean playerInGroup(String world, String player, String group); /** + * @param world World object + * @param player player name + * @param group group name + * @return true if player is in group, false otherwise * @deprecated As of VaultAPI 1.4 use {@link #playerInGroup(String, OfflinePlayer, String)} instead. */ @Deprecated @@ -482,15 +517,15 @@ public abstract class Permission { } return playerInGroup(world.getName(), player, group); } - + /** * Check if player is member of a group. * Supports NULL value for World if the permission system registered supports global permissions. * But May return odd values if the servers registered permission system does not have a global permission store. - * - * @param world World Object + * + * @param world World Object * @param player to check - * @param group Group name + * @param group Group name * @return Success or Failure */ public boolean playerInGroup(String world, OfflinePlayer player, String group) { @@ -504,9 +539,9 @@ public abstract class Permission { * Check if player is member of a group. * This method will ONLY check groups for which the player is in that are defined for the current world. * This may result in odd return behaviour depending on what permission system has been registered. - * + * * @param player Player Object - * @param group Group name + * @param group Group name * @return Success or Failure */ public boolean playerInGroup(Player player, String group) { @@ -514,12 +549,20 @@ public abstract class Permission { } /** + * @param world World name + * @param player player name + * @param group group name + * @return true if successful, false otherwise * @deprecated As of VaultAPI 1.4 use {@link #playerAddGroup(String, OfflinePlayer, String)} instead. */ @Deprecated abstract public boolean playerAddGroup(String world, String player, String group); /** + * @param world World Object + * @param player player name + * @param group group name + * @return true if successful, false otherwise * @deprecated As of VaultAPI 1.4 use {@link #playerAddGroup(String, OfflinePlayer, String)} instead. */ @Deprecated @@ -534,10 +577,10 @@ public abstract class Permission { * Add player to a group. * Supports NULL value for World if the permission system registered supports global permissions. * But May return odd values if the servers registered permission system does not have a global permission store. - * - * @param world String world name + * + * @param world String world name * @param player to add - * @param group Group name + * @param group Group name * @return Success or Failure */ public boolean playerAddGroup(String world, OfflinePlayer player, String group) { @@ -546,14 +589,14 @@ public abstract class Permission { } return playerAddGroup(world, player.getName(), group); } - + /** * Add player to a group. * This will add a player to the group on the current World. This may return odd results if the permission system * being used on the server does not support world-specific groups, or if the group being added to is a global group. - * + * * @param player Player Object - * @param group Group name + * @param group Group name * @return Success or Failure */ public boolean playerAddGroup(Player player, String group) { @@ -561,12 +604,20 @@ public abstract class Permission { } /** + * @param world world name + * @param player player name + * @param group group name + * @return true if successful, false otherwise * @deprecated As of VaultAPI 1.4 use {@link #playerRemoveGroup(String, OfflinePlayer, String)} instead. */ @Deprecated abstract public boolean playerRemoveGroup(String world, String player, String group); /** + * @param world World Object + * @param player name + * @param group Group name + * @return true if successful, false otherwise * @deprecated As of VaultAPI 1.4 use {@link #playerRemoveGroup(String, OfflinePlayer, String)} instead. */ @Deprecated @@ -576,15 +627,15 @@ public abstract class Permission { } return playerRemoveGroup(world.getName(), player, group); } - + /** * Remove player from a group. * Supports NULL value for World if the permission system registered supports global permissions. * But May return odd values if the servers registered permission system does not have a global permission store. - * - * @param world World Object + * + * @param world World Object * @param player to remove - * @param group Group name + * @param group Group name * @return Success or Failure */ public boolean playerRemoveGroup(String world, OfflinePlayer player, String group) { @@ -598,9 +649,9 @@ public abstract class Permission { * Remove player from a group. * This will add a player to the group on the current World. This may return odd results if the permission system * being used on the server does not support world-specific groups, or if the group being added to is a global group. - * + * * @param player Player Object - * @param group Group name + * @param group Group name * @return Success or Failure */ public boolean playerRemoveGroup(Player player, String group) { @@ -608,12 +659,18 @@ public abstract class Permission { } /** + * @param world world name + * @param player player name + * @return Array of groups * @deprecated As of VaultAPI 1.4 use {@link #getPlayerGroups(String, OfflinePlayer)} instead. */ @Deprecated abstract public String[] getPlayerGroups(String world, String player); /** + * @param world World Object + * @param player player name + * @return Array of groups * @deprecated As of VaultAPI 1.4 use {@link #getPlayerGroups(String, OfflinePlayer)} instead. */ @Deprecated @@ -623,25 +680,25 @@ public abstract class Permission { } return getPlayerGroups(world.getName(), player); } - + /** * Gets the list of groups that this player has * Supports NULL value for World if the permission system registered supports global permissions. * But May return odd values if the servers registered permission system does not have a global permission store. - * - * @param world String world name + * + * @param world String world name * @param player OfflinePlayer * @return Array of groups */ public String[] getPlayerGroups(String world, OfflinePlayer player) { - return getPlayerGroups(world, player.getName()); + return getPlayerGroups(world, player.getName()); } /** * Returns a list of world-specific groups that this player is currently in. May return unexpected results if * you are looking for global groups, or if the registered permission system does not support world-specific groups. * See {@link #getPlayerGroups(String, OfflinePlayer)} for better control of World-specific or global groups. - * + * * @param player Player Object * @return Array of groups */ @@ -665,13 +722,13 @@ public abstract class Permission { } return getPrimaryGroup(world.getName(), player); } - + /** * Gets players primary group * Supports NULL value for World if the permission system registered supports global permissions. * But May return odd values if the servers registered permission system does not have a global permission store. - * - * @param world String world name + * + * @param world String world name * @param player to get from * @return Players primary group */ @@ -683,22 +740,24 @@ public abstract class Permission { * Get players primary group. * Defaults to the players current world, so may return only world-specific groups. * In most cases {@link #getPrimaryGroup(String, OfflinePlayer)} is preferable. - * + * * @param player Player Object * @return Players primary group */ public String getPrimaryGroup(Player player) { return getPrimaryGroup(player.getWorld().getName(), player); } - + /** * Returns a list of all known groups + * * @return an Array of String of all groups */ abstract public String[] getGroups(); - + /** * Returns true if the given implementation supports groups. + * * @return true if the implementation supports groups */ abstract public boolean hasGroupSupport();