Upstream/VaultAPI
1
0
Fork 0
mirror of https://github.com/MilkBowl/VaultAPI.git synced 2024-09-27 14:53:01 +02:00
Code Issues Projects Releases Wiki Activity

Improves and fixes JavaDocs for Economy, IdentityEconomy and Permission

Browse Source
This commit is contained in:
lbenav8095 2023-04-02 03:45:25 -06:00
parent b3bbcddff4
commit 1496c69fa0
3 changed files with 334 additions and 212 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

131
src/main/java/net/milkbowl/vault/economy/Economy.java
View File

@ -16,10 +16,10 @@
package net.milkbowl.vault.economy; package net.milkbowl.vault.economy;
import java.util.List;
import org.bukkit.OfflinePlayer; import org.bukkit.OfflinePlayer;
import java.util.List;
/** /**
* The main economy API * The main economy API
* *
@ -28,18 +28,21 @@ public interface Economy {
/** /**
* Checks if economy method is enabled. * Checks if economy method is enabled.
*
* @return Success or Failure * @return Success or Failure
*/ */
public boolean isEnabled(); public boolean isEnabled();
/** /**
* Gets name of economy method * Gets name of economy method
*
* @return Name of Economy Method * @return Name of Economy Method
*/ */
public String getName(); public String getName();
/** /**
* Returns true if the given implementation supports banks. * Returns true if the given implementation supports banks.
*
* @return true if the implementation supports banks * @return true if the implementation supports banks
*/ */
public boolean hasBankSupport(); public boolean hasBankSupport();
@ -48,6 +51,7 @@ public interface Economy {
* Some economy plugins round off after a certain number of digits. * Some economy plugins round off after a certain number of digits.
* This function returns the number of digits the plugin keeps * This function returns the number of digits the plugin keeps
* or -1 if no rounding occurs. * or -1 if no rounding occurs.
*
* @return number of digits after the decimal point kept * @return number of digits after the decimal point kept
*/ */
public int fractionalDigits(); public int fractionalDigits();
@ -79,8 +83,9 @@ public interface Economy {
public String currencyNameSingular(); public String currencyNameSingular();
/** /**
* * @param playerName Name of the player.
* @deprecated As of VaultAPI 1.4 use {@link #hasAccount(OfflinePlayer)} or {@link #hasAccount(UUID)} instead. * @return True if specified player name has an account, otherwise false.
* @deprecated As of VaultAPI 1.4 use {@link #hasAccount(OfflinePlayer)}
*/ */
@Deprecated @Deprecated
public boolean hasAccount(String playerName); public boolean hasAccount(String playerName);
@ -94,8 +99,12 @@ public interface Economy {
* @return if the player has an account * @return if the player has an account
*/ */
public boolean hasAccount(OfflinePlayer player); 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 As of VaultAPI 1.4 use {@link #hasAccount(OfflinePlayer, String)} instead.
*/ */
@Deprecated @Deprecated
@ -105,14 +114,16 @@ public interface Economy {
* Checks if this player has an account on the server yet on the given world * 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 * 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 * 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 * @param worldName world-specific account
* @return if the player has an account * @return if the player has an account
*/ */
public boolean hasAccount(OfflinePlayer player, String worldName); 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 As of VaultAPI 1.4 use {@link #getBalance(OfflinePlayer)} instead.
*/ */
@Deprecated @Deprecated
@ -127,6 +138,9 @@ public interface Economy {
public double getBalance(OfflinePlayer player); 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 As of VaultAPI 1.4 use {@link #getBalance(OfflinePlayer, String)} instead.
*/ */
@Deprecated @Deprecated
@ -135,13 +149,17 @@ public interface Economy {
/** /**
* Gets balance of a player on the specified world. * 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. * 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 world name of the world * @param world name of the world
* @return Amount currently held in players account * @return Amount currently held in players account
*/ */
public double getBalance(OfflinePlayer player, String world); 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 As of VaultAPI 1.4 use {@link #has(OfflinePlayer, double)} instead.
*/ */
@Deprecated @Deprecated
@ -157,6 +175,10 @@ public interface Economy {
public boolean has(OfflinePlayer player, double amount); 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 As of VaultAPI 1.4 use @{link {@link #has(OfflinePlayer, String, double)} instead.
*/ */
@Deprecated @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 * 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. * 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 worldName to check with
* @param amount to check for * @param amount to check for
* @return True if <b>player</b> has <b>amount</b> in the given <b>world</b>, False else wise * @return True if <b>player</b> has <b>amount</b> in the given <b>world</b>, False else wise
*/ */
public boolean has(OfflinePlayer player, String worldName, double amount); 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 As of VaultAPI 1.4 use {@link #withdrawPlayer(OfflinePlayer, double)} instead.
*/ */
@Deprecated @Deprecated
@ -189,6 +214,10 @@ public interface Economy {
public EconomyResponse withdrawPlayer(OfflinePlayer player, double amount); 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 As of VaultAPI 1.4 use {@link #withdrawPlayer(OfflinePlayer, String, double)} instead.
*/ */
@Deprecated @Deprecated
@ -197,14 +226,18 @@ public interface Economy {
/** /**
* Withdraw an amount from a player on a given world - DO NOT USE NEGATIVE AMOUNTS * 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. * 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 worldName - name of the world
* @param amount Amount to withdraw * @param amount Amount to withdraw
* @return Detailed response of transaction * @return Detailed response of transaction
*/ */
public EconomyResponse withdrawPlayer(OfflinePlayer player, String worldName, double amount); 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 As of VaultAPI 1.4 use {@link #depositPlayer(OfflinePlayer, double)} instead.
*/ */
@Deprecated @Deprecated
@ -220,6 +253,10 @@ public interface Economy {
public EconomyResponse depositPlayer(OfflinePlayer player, double amount); 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 As of VaultAPI 1.4 use {@link #depositPlayer(OfflinePlayer, String, double)} instead.
*/ */
@Deprecated @Deprecated
@ -228,15 +265,18 @@ public interface Economy {
/** /**
* Deposit an amount to a player on a given world - DO NOT USE NEGATIVE AMOUNTS * 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. * 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 worldName name of the world
* @param amount Amount to deposit * @param amount Amount to deposit
* @return Detailed response of transaction * @return Detailed response of transaction
*/ */
public EconomyResponse depositPlayer(OfflinePlayer player, String worldName, double amount); 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 As of VaultAPI 1.4 use {{@link #createBank(String, OfflinePlayer)} instead.
*/ */
@Deprecated @Deprecated
@ -244,14 +284,16 @@ public interface Economy {
/** /**
* Creates a bank account with the specified name and the player as the owner * 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 * @param player the account should be linked to
* @return EconomyResponse Object * @return Detailed response of transaction
*/ */
public EconomyResponse createBank(String name, OfflinePlayer player); public EconomyResponse createBank(String name, OfflinePlayer player);
/** /**
* Deletes a bank account with the specified name. * Deletes a bank account with the specified name.
*
* @param name of the back to delete * @param name of the back to delete
* @return if the operation completed successfully * @return if the operation completed successfully
*/ */
@ -259,54 +301,61 @@ public interface Economy {
/** /**
* Returns the amount the bank has * Returns the amount the bank has
*
* @param name of the account * @param name of the account
* @return EconomyResponse Object * @return Detailed response of transaction
*/ */
public EconomyResponse bankBalance(String name); public EconomyResponse bankBalance(String name);
/** /**
* Returns true or false whether the bank has the amount specified - DO NOT USE NEGATIVE AMOUNTS * 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 * @param amount to check for
* @return EconomyResponse Object * @return Detailed response of transaction
*/ */
public EconomyResponse bankHas(String name, double amount); public EconomyResponse bankHas(String name, double amount);
/** /**
* Withdraw an amount from a bank account - DO NOT USE NEGATIVE AMOUNTS * 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 * @param amount to withdraw
* @return EconomyResponse Object * @return Detailed response of transaction
*/ */
public EconomyResponse bankWithdraw(String name, double amount); public EconomyResponse bankWithdraw(String name, double amount);
/** /**
* Deposit an amount into a bank account - DO NOT USE NEGATIVE AMOUNTS * 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 * @param amount to deposit
* @return EconomyResponse Object * @return Detailed response of transaction
*/ */
public EconomyResponse bankDeposit(String name, double amount); 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 @Deprecated
public EconomyResponse isBankOwner(String name, String playerName); public EconomyResponse isBankOwner(String name, String playerName);
/** /**
* Check if a player is the owner of a bank account * 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 * @param player to check for ownership
* @return EconomyResponse Object * @return Detailed response of transaction
*/ */
public EconomyResponse isBankOwner(String name, OfflinePlayer player); 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 As of VaultAPI 1.4 use {{@link #isBankMember(String, OfflinePlayer)} instead.
*/ */
@Deprecated @Deprecated
@ -314,33 +363,40 @@ public interface Economy {
/** /**
* Check if the player is a member of the bank account * 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 * @param player to check membership
* @return EconomyResponse Object * @return Detailed response of transaction
*/ */
public EconomyResponse isBankMember(String name, OfflinePlayer player); public EconomyResponse isBankMember(String name, OfflinePlayer player);
/** /**
* Gets the list of banks * Gets the list of banks
*
* @return the List of Banks * @return the List of Banks
*/ */
public List<String> getBanks(); public List<String> 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 @Deprecated
public boolean createPlayerAccount(String playerName); public boolean createPlayerAccount(String playerName);
/** /**
* Attempts to create a player account for the given player * Attempts to create a player account for the given player
*
* @param player OfflinePlayer * @param player OfflinePlayer
* @return if the account creation was successful * @return if the account creation was successful
*/ */
public boolean createPlayerAccount(OfflinePlayer player); 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 As of VaultAPI 1.4 use {{@link #createPlayerAccount(OfflinePlayer, String)} instead.
*/ */
@Deprecated @Deprecated
@ -349,7 +405,8 @@ public interface Economy {
/** /**
* Attempts to create a player account for the given player on the specified world * 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. * 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 * @param worldName String name of the world
* @return if the account creation was successful * @return if the account creation was successful
*/ */

66
src/main/java/net/milkbowl/vault/economy/IdentityEconomy.java
View File

@ -32,13 +32,14 @@ import java.util.UUID;
* <p> * <p>
* In order to register/provide it, you should use {@link IdentityEconomyWrapper#registerProviders()} * 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 * Used to determine if IdentityEconomy was built through
* the EconomyWrapper as a LegacyEconomy. * the EconomyWrapper as a LegacyEconomy.
* If false, method {@link #getAllRecords()} will not be work. * If false, method {@link #getAllRecords()} will not be work.
* This was made in order to support plugins which use older versions of VaultAPI/Vault. * 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! * You can also use it / override it to disable previous mentioned methods!
*
* @return true if operation is supported * @return true if operation is supported
*/ */
public boolean supportsAllRecordsOperation(); public boolean supportsAllRecordsOperation();
@ -49,6 +50,7 @@ public interface IdentityEconomy extends Economy{
* If false, the method {@link #getAllOnline()} (UUID)} will not be work. * 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. * 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! * You can also use it / override it to disable previous mentioned methods!
*
* @return true if operation is supported * @return true if operation is supported
*/ */
public boolean supportsAllOnlineOperation(); public boolean supportsAllOnlineOperation();
@ -60,6 +62,7 @@ public interface IdentityEconomy extends Economy{
* are online/connected to the server in real time. * are online/connected to the server in real time.
* If true, you should expect to call these operations * If true, you should expect to call these operations
* asynchronously. * asynchronously.
*
* @return true if operation is supported * @return true if operation is supported
*/ */
public boolean supportsOfflineOperations(); public boolean supportsOfflineOperations();
@ -69,6 +72,7 @@ public interface IdentityEconomy extends Economy{
* the EconomyWrapper as a LegacyEconomy. * the EconomyWrapper as a LegacyEconomy.
* If false, you should expect UnsupportedOperationException * If false, you should expect UnsupportedOperationException
* being thrown when calling these methods. * being thrown when calling these methods.
*
* @return true if operation is supported * @return true if operation is supported
*/ */
public boolean supportsUUIDOperations(); public boolean supportsUUIDOperations();
@ -79,7 +83,7 @@ public interface IdentityEconomy extends Economy{
/** /**
* Attempts to create a account for the given uuid * Attempts to create a account for the given uuid
* *
* @param uuid associated with the account * @param uuid associated with the account
* @param name associated with the account. * @param name associated with the account.
* @return if the account creation was successful * @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 * Attempts to create an account for the given UUID on the specified world
* IMPLEMENTATION SPECIFIC - if an economy plugin does not support this then * IMPLEMENTATION SPECIFIC - if an economy plugin does not support this then
* false will always be returned. * false will always be returned.
* *
* @param uuid associated with the account * @param uuid associated with the account
* @param name associated with the account. * @param name associated with the account.
* @param worldName String name of the world * @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 * 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. * converter and should be given every account available.
* Needs IdentityEconomy#hasUUIDSupport() to be true. * Needs IdentityEconomy#hasUUIDSupport() to be true.
* *
* @return a {@link Map} composed of the accounts keyed by their UUID, along * @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<UUID, String> getAllRecords(); public Map<UUID, String> getAllRecords();
@ -114,6 +118,7 @@ public interface IdentityEconomy extends Economy{
* online/connected to the server. * online/connected to the server.
* This is used for Vault's economy converter and should * This is used for Vault's economy converter and should
* Needs IdentityEconomy#hasUUIDSupport() to be true. * Needs IdentityEconomy#hasUUIDSupport() to be true.
*
* @return a {@link Collection} of all UUIDs which have accounts in the plugin * @return a {@link Collection} of all UUIDs which have accounts in the plugin
*/ */
public Collection<UUID> getAllOnline(); public Collection<UUID> 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 * 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. * messages to be more human-readable than UUIDs alone can provide.
* *
* @param uuid UUID to look up. * @param uuid UUID to look up.
* @return the last known name of the account associated with the given UUID.
*/ */
public String getAccountName(UUID uuid); public String getAccountName(UUID uuid);
/** /**
* Checks if this uuid has an account yet * Checks if this uuid has an account yet
* *
* @param uuid to check * @param uuid to check
* @return if the uuid has an account * @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 * Checks if this uuid has an account yet on the given world
* *
* @param uuid to check * @param uuid to check
* @param worldName world-specific account * @param worldName world-specific account
* @return if the uuid has an 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 * A method which changes the name associated with the given UUID in the
* Map<UUID, String> received from {@link #getAllRecords()} * Map&lt;UUID, String&gt; received from {@link #getAllRecords()}
* *
* @param uuid which is having a name change. * @param uuid which is having a name change.
* @param name name that will be associated with the UUID in the * @param name name that will be associated with the UUID in the
* Map<UUID, String> map. * Map&lt;UUID, String&gt; map.
* @return true if the name change is successful. * @return true if the name change is successful.
*/ */
public boolean renameAccount(UUID uuid, String name); public boolean renameAccount(UUID uuid, String name);
/** /**
* Gets balance of a UUID * Gets balance of a UUID
* *
* @param uuid of the account to get a balance for * @param uuid of the account to get a balance for
* @return Amount currently held in account associated with the given UUID * @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 * 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. * an economy plugin does not support this the global balance will be returned.
* *
* @param uuid of the account to get a balance for * @param uuid of the account to get a balance for
* @param world name of the world * @param world name of the world
* @return Amount currently held in account associated with the given UUID * @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 * Checks if the account associated with the given UUID has the amount - DO NOT
* USE NEGATIVE AMOUNTS * USE NEGATIVE AMOUNTS
* *
* @param uuid to check * @param uuid to check
* @param amount to check for * @param amount to check for
* @return True if <b>UUID</b> has <b>amount</b>, False else wise * @return True if <b>UUID</b> has <b>amount</b>, 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 * 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 * given world - DO NOT USE NEGATIVE AMOUNTS IMPLEMENTATION SPECIFIC - if an
* economy plugin does not support this the global balance will be returned. * economy plugin does not support this the global balance will be returned.
* *
* @param uuid to check * @param uuid to check
* @param worldName to check with * @param worldName to check with
* @param amount to check for * @param amount to check for
* @return True if <b>UUID</b> has <b>amount</b> in the given <b>world</b>, * @return True if <b>UUID</b> has <b>amount</b> in the given <b>world</b>,
* False else wise * False else wise
*/ */
public boolean has(UUID uuid, String worldName, double amount); public boolean has(UUID uuid, String worldName, double amount);
/** /**
* Withdraw an amount from an account associated with a UUID - DO NOT USE * Withdraw an amount from an account associated with a UUID - DO NOT USE
* NEGATIVE AMOUNTS * NEGATIVE AMOUNTS
* *
* @param uuid to withdraw from * @param uuid to withdraw from
* @param amount Amount to withdraw * @param amount Amount to withdraw
* @return Detailed response of transaction * @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 - * 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 * DO NOT USE NEGATIVE AMOUNTS IMPLEMENTATION SPECIFIC - if an economy plugin
* does not support this the global balance will be returned. * does not support this the global balance will be returned.
* *
* @param uuid to withdraw from * @param uuid to withdraw from
* @param worldName - name of the world * @param worldName - name of the world
* @param amount Amount to withdraw * @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 * Deposit an amount to an account associated with the given UUID - DO NOT USE
* NEGATIVE AMOUNTS * NEGATIVE AMOUNTS
* *
* @param uuid to deposit to * @param uuid to deposit to
* @param amount Amount to deposit * @param amount Amount to deposit
* @return Detailed response of transaction * @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 - * 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 * DO NOT USE NEGATIVE AMOUNTS IMPLEMENTATION SPECIFIC - if an economy plugin
* does not support this the global balance will be returned. * does not support this the global balance will be returned.
* *
* @param uuid to deposit to * @param uuid to deposit to
* @param worldName name of the world * @param worldName name of the world
* @param amount Amount to deposit * @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 * Creates a bank account with the specified name and the given UUID as the
* owner * owner
* *
* @param name of account * @param name of account
* @param uuid the account should be linked to * @param uuid the account should be linked to
* @return EconomyResponse Object * @return EconomyResponse Object
@ -255,7 +261,7 @@ public interface IdentityEconomy extends Economy{
/** /**
* Deletes a bank account with the specified name. * Deletes a bank account with the specified name.
* *
* @param name of the back to delete * @param name of the back to delete
* @return if the operation completed successfully * @return if the operation completed successfully
*/ */
@ -263,7 +269,7 @@ public interface IdentityEconomy extends Economy{
/** /**
* Returns the amount the bank has * Returns the amount the bank has
* *
* @param name of the account * @param name of the account
* @return EconomyResponse Object * @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 * Returns true or false whether the bank has the amount specified - DO NOT USE
* NEGATIVE AMOUNTS * NEGATIVE AMOUNTS
* *
* @param name of the account * @param name of the account
* @param amount to check for * @param amount to check for
* @return EconomyResponse Object * @return EconomyResponse Object
@ -281,7 +287,7 @@ public interface IdentityEconomy extends Economy{
/** /**
* Withdraw an amount from a bank account - DO NOT USE NEGATIVE AMOUNTS * 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 * @param amount to withdraw
* @return EconomyResponse Object * @return EconomyResponse Object
@ -290,7 +296,7 @@ public interface IdentityEconomy extends Economy{
/** /**
* Deposit an amount into a bank account - DO NOT USE NEGATIVE AMOUNTS * 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 * @param amount to deposit
* @return EconomyResponse Object * @return EconomyResponse Object
@ -299,7 +305,7 @@ public interface IdentityEconomy extends Economy{
/** /**
* Check if a uuid is the owner of a bank account * Check if a uuid is the owner of a bank account
* *
* @param name of the account * @param name of the account
* @param uuid to check for ownership * @param uuid to check for ownership
* @return EconomyResponse Object * @return EconomyResponse Object
@ -308,7 +314,7 @@ public interface IdentityEconomy extends Economy{
/** /**
* Check if the uuid is a member of the bank account * Check if the uuid is a member of the bank account
* *
* @param name of the account * @param name of the account
* @param uuid to check membership * @param uuid to check membership
* @return EconomyResponse Object * @return EconomyResponse Object
@ -317,7 +323,7 @@ public interface IdentityEconomy extends Economy{
/** /**
* Gets the list of banks * Gets the list of banks
* *
* @return the List of Banks * @return the List of Banks
*/ */
public List<String> getBanks(); public List<String> getBanks();

349
src/main/java/net/milkbowl/vault/permission/Permission.java
View File

@ -15,8 +15,6 @@
*/ */
package net.milkbowl.vault.permission; package net.milkbowl.vault.permission;
import java.util.logging.Logger;
import org.bukkit.OfflinePlayer; import org.bukkit.OfflinePlayer;
import org.bukkit.World; import org.bukkit.World;
import org.bukkit.command.CommandSender; import org.bukkit.command.CommandSender;
@ -25,34 +23,42 @@ import org.bukkit.permissions.PermissionAttachment;
import org.bukkit.permissions.PermissionAttachmentInfo; import org.bukkit.permissions.PermissionAttachmentInfo;
import org.bukkit.plugin.Plugin; import org.bukkit.plugin.Plugin;
import java.util.logging.Logger;
/** /**
* The main Permission API - allows for group and player based permission tests * The main Permission API - allows for group and player based permission tests
*
*/ */
public abstract class Permission { public abstract class Permission {
protected static final Logger log = Logger.getLogger("Minecraft"); protected static final Logger log = Logger.getLogger("Minecraft");
protected Plugin plugin = null; protected Plugin plugin = null;
/** /**
* Gets name of permission method * Gets name of permission method
*
* @return Name of Permission Method * @return Name of Permission Method
*/ */
abstract public String getName(); abstract public String getName();
/** /**
* Checks if permission method is enabled. * Checks if permission method is enabled.
*
* @return Success or Failure * @return Success or Failure
*/ */
abstract public boolean isEnabled(); abstract public boolean isEnabled();
/** /**
* Returns if the permission system is or attempts to be compatible with super-perms. * Returns if the permission system is or attempts to be compatible with super-perms.
*
* @return True if this permission implementation works with super-perms * @return True if this permission implementation works with super-perms
*/ */
abstract public boolean hasSuperPermsCompat(); 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 As of VaultAPI 1.4 use {@link #playerHas(String, OfflinePlayer, String)} instead.
*/ */
@Deprecated @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 As of VaultAPI 1.4 use {@link #playerHas(String, OfflinePlayer, String)} instead.
*/ */
@Deprecated @Deprecated
@ -78,9 +88,10 @@ public abstract class Permission {
* Checks if a CommandSender has a permission node. * 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 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. * This method will explicitly fail if the registered permission system does not register permissions in bukkit.
* * <p>
* For easy checking of a commandsender * For easy checking of a commandsender
* @param sender to check permissions on *
* @param sender to check permissions on
* @param permission to check for * @param permission to check for
* @return true if the sender has the permission * @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(...) * Checks if player has a permission node. (Short for playerHas(...)
* @param player Player Object *
* @param player Player Object
* @param permission Permission node * @param permission Permission node
* @return Success or Failure * @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 As of VaultAPI 1.4 use {@link #playerHas(String, OfflinePlayer, String)} instead.
*/ */
@Deprecated @Deprecated
abstract public boolean playerHas(String world, String player, String permission); 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 As of VaultAPI 1.4 use {@link #playerHas(String, OfflinePlayer, String)} instead.
*/ */
@Deprecated @Deprecated
@ -114,21 +134,21 @@ public abstract class Permission {
} }
return playerHas(world.getName(), player, permission); return playerHas(world.getName(), player, permission);
} }
/** /**
* Checks if player has a permission node. * Checks if player has a permission node.
* Supports NULL value for World if the permission system registered supports global permissions. * 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. * 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 check * @param player to check
* @param permission Permission node * @param permission Permission node
* @return Success or Failure * @return Success or Failure
*/ */
public boolean playerHas(String world, OfflinePlayer player, String permission) { public boolean playerHas(String world, OfflinePlayer player, String permission) {
if (world == null) { if (world == null) {
return has((String) null, player.getName(), permission); return has((String) null, player.getName(), permission);
} }
return has(world, player.getName(), permission); return has(world, player.getName(), permission);
} }
@ -136,8 +156,8 @@ public abstract class Permission {
* Checks if player has a permission node. * Checks if player has a permission node.
* Defaults to world-specific permission check if the permission system supports it. * Defaults to world-specific permission check if the permission system supports it.
* See {@link #playerHas(String, OfflinePlayer, String)} for explicit global or world checks. * See {@link #playerHas(String, OfflinePlayer, String)} for explicit global or world checks.
* *
* @param player Player Object * @param player Player Object
* @param permission Permission node * @param permission Permission node
* @return Success or Failure * @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. * @deprecated As of VaultAPI 1.4 use {@link #playerAdd(String, OfflinePlayer, String)} instead.
* Add permission to a player. * Add permission to a player.
* Supports NULL value for World if the permission system registered supports global permissions. * 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. * 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 @Deprecated
abstract public boolean playerAdd(String world, String player, String permission); 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 As of VaultAPI 1.4 use {@link #playerAdd(String, OfflinePlayer, String)} instead.
*/ */
@Deprecated @Deprecated
@ -174,9 +197,9 @@ public abstract class Permission {
* Add permission to a player. * Add permission to a player.
* Supports NULL value for World if the permission system registered supports global permissions. * 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. * 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 to * @param player to add to
* @param permission Permission node * @param permission Permission node
* @return Success or Failure * @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. * 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. * 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. * See {@link #playerAdd(String, OfflinePlayer, String)} for global permission use.
* *
* @param player Player Object * @param player Player Object
* @param permission Permission node * @param permission Permission node
* @return Success or Failure * @return Success or Failure
*/ */
public boolean playerAdd(Player player, String permission) { public boolean playerAdd(Player player, String permission) {
return playerAdd(player.getWorld().getName(), player, permission); return playerAdd(player.getWorld().getName(), player, permission);
} }
/** /**
* Add transient permission to a player. * 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. * 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 * @param permission Permission node
* @return Success or Failure * @return Success or Failure
*/ */
public boolean playerAddTransient(OfflinePlayer player, String permission) throws UnsupportedOperationException { public boolean playerAddTransient(OfflinePlayer player, String permission) throws UnsupportedOperationException {
if (player.isOnline()) { if (player.isOnline()) {
return playerAddTransient((Player) player, permission); return playerAddTransient((Player) player, permission);
} }
throw new UnsupportedOperationException(getName() + " does not support offline player transient permissions!"); throw new UnsupportedOperationException(getName() + " does not support offline player transient permissions!");
} }
/** /**
* Add transient permission to a player. * Add transient permission to a player.
* This operation adds a permission onto the player object in bukkit via Bukkit's permission interface. * 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 * @param permission Permission node
* @return Success or Failure * @return Success or Failure
*/ */
public boolean playerAddTransient(Player player, String permission) { public boolean playerAddTransient(Player player, String permission) {
for (PermissionAttachmentInfo paInfo : player.getEffectivePermissions()) { for (PermissionAttachmentInfo paInfo : player.getEffectivePermissions()) {
if (paInfo.getAttachment() != null && paInfo.getAttachment().getPlugin().equals(plugin)) { if (paInfo.getAttachment() != null && paInfo.getAttachment().getPlugin().equals(plugin)) {
paInfo.getAttachment().setPermission(permission, true); paInfo.getAttachment().setPermission(permission, true);
return true; return true;
} }
} }
PermissionAttachment attach = player.addAttachment(plugin); PermissionAttachment attach = player.addAttachment(plugin);
attach.setPermission(permission, true); attach.setPermission(permission, true);
return true; return true;
} }
/** /**
* Adds a world specific transient permission to the player, may only work with some permission managers. * 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! * Defaults to GLOBAL permissions for any permission system that does not support world-specific transient permissions!
* *
* @param worldName to check on * @param worldName to check on
* @param player to add to * @param player to add to
* @param permission to test * @param permission to test
* @return Success or Failure * @return Success or Failure
*/ */
public boolean playerAddTransient(String worldName, OfflinePlayer player, String permission) { 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. * 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! * Defaults to GLOBAL permissions for any permission system that does not support world-specific transient permissions!
* *
* @param worldName to check on * @param worldName to check on
* @param player to check * @param player to check
* @param permission to check for * @param permission to check for
* @return Success or Failure * @return Success or Failure
*/ */
public boolean playerAddTransient(String worldName, Player player, String permission) { 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. * 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! * Defaults to GLOBAL permissions for any permission system that does not support world-specific transient permissions!
* *
* @param worldName to remove for * @param worldName to remove for
* @param player to remove for * @param player to remove for
* @param permission to remove * @param permission to remove
* @return Success or Failure * @return Success or Failure
*/ */
public boolean playerRemoveTransient(String worldName, OfflinePlayer player, String permission) { 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. * 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! * Defaults to GLOBAL permissions for any permission system that does not support world-specific transient permissions!
* *
* @param worldName to check on * @param worldName to check on
* @param player to check * @param player to check
* @param permission to check for * @param permission to check for
* @return Success or Failure * @return Success or Failure
*/ */
public boolean playerRemoveTransient(String worldName, Player player, String permission) { 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 As of VaultAPI 1.4 use {@link #playerRemove(String, OfflinePlayer, String)} instead.
*/ */
@Deprecated @Deprecated
@ -300,9 +327,9 @@ public abstract class Permission {
* Remove permission from a player. * Remove permission from a player.
* Supports NULL value for World if the permission system registered supports global permissions. * 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. * But May return odd values if the servers registered permission system does not have a global permission store.
* *
* @param world World name * @param world World name
* @param player OfflinePlayer * @param player OfflinePlayer
* @param permission Permission node * @param permission Permission node
* @return Success or Failure * @return Success or Failure
*/ */
@ -317,9 +344,9 @@ public abstract class Permission {
* Remove permission from a player. * Remove permission from a player.
* Supports NULL value for World if the permission system registered supports global permissions. * 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. * But May return odd values if the servers registered permission system does not have a global permission store.
* *
* @param world World name * @param world World name
* @param player Player name * @param player Player name
* @param permission Permission node * @param permission Permission node
* @return Success or Failure * @return Success or Failure
*/ */
@ -334,58 +361,58 @@ public abstract class Permission {
/** /**
* Remove permission from a player. * 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. * 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 * @param permission Permission node
* @return Success or Failure * @return Success or Failure
*/ */
public boolean playerRemove(Player player, String permission) { public boolean playerRemove(Player player, String permission) {
return playerRemove(player.getWorld().getName(), player, permission); return playerRemove(player.getWorld().getName(), player, permission);
} }
/** /**
* Remove transient permission from a player. * 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 * 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. * 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 * @param permission Permission node
* @return Success or Failure * @return Success or Failure
*/ */
public boolean playerRemoveTransient(OfflinePlayer player, String permission) { public boolean playerRemoveTransient(OfflinePlayer player, String permission) {
if (player.isOnline()) { if (player.isOnline()) {
return playerRemoveTransient((Player) player, permission); return playerRemoveTransient((Player) player, permission);
} else { } else {
return false; return false;
} }
} }
/** /**
* Remove transient permission from a player. * Remove transient permission from a player.
* *
* @param player Player Object * @param player Player Object
* @param permission Permission node * @param permission Permission node
* @return Success or Failure * @return Success or Failure
*/ */
public boolean playerRemoveTransient(Player player, String permission) { public boolean playerRemoveTransient(Player player, String permission) {
for (PermissionAttachmentInfo paInfo : player.getEffectivePermissions()) { for (PermissionAttachmentInfo paInfo : player.getEffectivePermissions()) {
if (paInfo.getAttachment() != null && paInfo.getAttachment().getPlugin().equals(plugin)) { if (paInfo.getAttachment() != null && paInfo.getAttachment().getPlugin().equals(plugin)) {
paInfo.getAttachment().unsetPermission(permission); paInfo.getAttachment().unsetPermission(permission);
return true; return true;
} }
} }
return false; return false;
} }
/** /**
* Checks if group has a permission node. * Checks if group has a permission node.
* Supports NULL value for World if the permission system registered supports global permissions. * 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. * But May return odd values if the servers registered permission system does not have a global permission store.
* *
* @param world World name * @param world World name
* @param group Group name * @param group Group name
* @param permission Permission node * @param permission Permission node
* @return Success or Failure * @return Success or Failure
*/ */
@ -395,9 +422,9 @@ public abstract class Permission {
* Checks if group has a permission node. * Checks if group has a permission node.
* Supports NULL value for World if the permission system registered supports global permissions. * 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. * 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 group Group name * @param group Group name
* @param permission Permission node * @param permission Permission node
* @return Success or Failure * @return Success or Failure
*/ */
@ -412,9 +439,9 @@ public abstract class Permission {
* Add permission to a group. * Add permission to a group.
* Supports NULL value for World if the permission system registered supports global permissions. * 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. * But May return odd values if the servers registered permission system does not have a global permission store.
* *
* @param world World name * @param world World name
* @param group Group name * @param group Group name
* @param permission Permission node * @param permission Permission node
* @return Success or Failure * @return Success or Failure
*/ */
@ -424,9 +451,9 @@ public abstract class Permission {
* Add permission to a group. * Add permission to a group.
* Supports NULL value for World if the permission system registered supports global permissions. * 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. * 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 group Group name * @param group Group name
* @param permission Permission node * @param permission Permission node
* @return Success or Failure * @return Success or Failure
*/ */
@ -441,9 +468,9 @@ public abstract class Permission {
* Remove permission from a group. * Remove permission from a group.
* Supports NULL value for World if the permission system registered supports global permissions. * 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. * But May return odd values if the servers registered permission system does not have a global permission store.
* *
* @param world World name * @param world World name
* @param group Group name * @param group Group name
* @param permission Permission node * @param permission Permission node
* @return Success or Failure * @return Success or Failure
*/ */
@ -453,9 +480,9 @@ public abstract class Permission {
* Remove permission from a group. * Remove permission from a group.
* Supports NULL value for World if the permission system registered supports global permissions. * 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. * 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 group Group name * @param group Group name
* @param permission Permission node * @param permission Permission node
* @return Success or Failure * @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 As of VaultAPI 1.4 use {@link #playerInGroup(String, OfflinePlayer, String)} instead.
*/ */
@Deprecated @Deprecated
abstract public boolean playerInGroup(String world, String player, String group); 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 As of VaultAPI 1.4 use {@link #playerInGroup(String, OfflinePlayer, String)} instead.
*/ */
@Deprecated @Deprecated
@ -482,15 +517,15 @@ public abstract class Permission {
} }
return playerInGroup(world.getName(), player, group); return playerInGroup(world.getName(), player, group);
} }
/** /**
* Check if player is member of a group. * Check if player is member of a group.
* Supports NULL value for World if the permission system registered supports global permissions. * 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. * 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 player to check
* @param group Group name * @param group Group name
* @return Success or Failure * @return Success or Failure
*/ */
public boolean playerInGroup(String world, OfflinePlayer player, String group) { 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. * 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 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. * This may result in odd return behaviour depending on what permission system has been registered.
* *
* @param player Player Object * @param player Player Object
* @param group Group name * @param group Group name
* @return Success or Failure * @return Success or Failure
*/ */
public boolean playerInGroup(Player player, String group) { 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 As of VaultAPI 1.4 use {@link #playerAddGroup(String, OfflinePlayer, String)} instead.
*/ */
@Deprecated @Deprecated
abstract public boolean playerAddGroup(String world, String player, String group); 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 As of VaultAPI 1.4 use {@link #playerAddGroup(String, OfflinePlayer, String)} instead.
*/ */
@Deprecated @Deprecated
@ -534,10 +577,10 @@ public abstract class Permission {
* Add player to a group. * Add player to a group.
* Supports NULL value for World if the permission system registered supports global permissions. * 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. * 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 player to add
* @param group Group name * @param group Group name
* @return Success or Failure * @return Success or Failure
*/ */
public boolean playerAddGroup(String world, OfflinePlayer player, String group) { public boolean playerAddGroup(String world, OfflinePlayer player, String group) {
@ -546,14 +589,14 @@ public abstract class Permission {
} }
return playerAddGroup(world, player.getName(), group); return playerAddGroup(world, player.getName(), group);
} }
/** /**
* Add player to a 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 * 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. * 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 player Player Object
* @param group Group name * @param group Group name
* @return Success or Failure * @return Success or Failure
*/ */
public boolean playerAddGroup(Player player, String group) { 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 As of VaultAPI 1.4 use {@link #playerRemoveGroup(String, OfflinePlayer, String)} instead.
*/ */
@Deprecated @Deprecated
abstract public boolean playerRemoveGroup(String world, String player, String group); 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 As of VaultAPI 1.4 use {@link #playerRemoveGroup(String, OfflinePlayer, String)} instead.
*/ */
@Deprecated @Deprecated
@ -576,15 +627,15 @@ public abstract class Permission {
} }
return playerRemoveGroup(world.getName(), player, group); return playerRemoveGroup(world.getName(), player, group);
} }
/** /**
* Remove player from a group. * Remove player from a group.
* Supports NULL value for World if the permission system registered supports global permissions. * 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. * 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 player to remove
* @param group Group name * @param group Group name
* @return Success or Failure * @return Success or Failure
*/ */
public boolean playerRemoveGroup(String world, OfflinePlayer player, String group) { public boolean playerRemoveGroup(String world, OfflinePlayer player, String group) {
@ -598,9 +649,9 @@ public abstract class Permission {
* Remove player from a group. * 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 * 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. * 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 player Player Object
* @param group Group name * @param group Group name
* @return Success or Failure * @return Success or Failure
*/ */
public boolean playerRemoveGroup(Player player, String group) { 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 As of VaultAPI 1.4 use {@link #getPlayerGroups(String, OfflinePlayer)} instead.
*/ */
@Deprecated @Deprecated
abstract public String[] getPlayerGroups(String world, String player); 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 As of VaultAPI 1.4 use {@link #getPlayerGroups(String, OfflinePlayer)} instead.
*/ */
@Deprecated @Deprecated
@ -623,25 +680,25 @@ public abstract class Permission {
} }
return getPlayerGroups(world.getName(), player); return getPlayerGroups(world.getName(), player);
} }
/** /**
* Gets the list of groups that this player has * Gets the list of groups that this player has
* Supports NULL value for World if the permission system registered supports global permissions. * 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. * 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 * @param player OfflinePlayer
* @return Array of groups * @return Array of groups
*/ */
public String[] getPlayerGroups(String world, OfflinePlayer player) { 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 * 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. * 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. * See {@link #getPlayerGroups(String, OfflinePlayer)} for better control of World-specific or global groups.
* *
* @param player Player Object * @param player Player Object
* @return Array of groups * @return Array of groups
*/ */
@ -665,13 +722,13 @@ public abstract class Permission {
} }
return getPrimaryGroup(world.getName(), player); return getPrimaryGroup(world.getName(), player);
} }
/** /**
* Gets players primary group * Gets players primary group
* Supports NULL value for World if the permission system registered supports global permissions. * 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. * 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 * @param player to get from
* @return Players primary group * @return Players primary group
*/ */
@ -683,22 +740,24 @@ public abstract class Permission {
* Get players primary group. * Get players primary group.
* Defaults to the players current world, so may return only world-specific groups. * Defaults to the players current world, so may return only world-specific groups.
* In most cases {@link #getPrimaryGroup(String, OfflinePlayer)} is preferable. * In most cases {@link #getPrimaryGroup(String, OfflinePlayer)} is preferable.
* *
* @param player Player Object * @param player Player Object
* @return Players primary group * @return Players primary group
*/ */
public String getPrimaryGroup(Player player) { public String getPrimaryGroup(Player player) {
return getPrimaryGroup(player.getWorld().getName(), player); return getPrimaryGroup(player.getWorld().getName(), player);
} }
/** /**
* Returns a list of all known groups * Returns a list of all known groups
*
* @return an Array of String of all groups * @return an Array of String of all groups
*/ */
abstract public String[] getGroups(); abstract public String[] getGroups();
/** /**
* Returns true if the given implementation supports groups. * Returns true if the given implementation supports groups.
*
* @return true if the implementation supports groups * @return true if the implementation supports groups
*/ */
abstract public boolean hasGroupSupport(); abstract public boolean hasGroupSupport();