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

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

@ -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);
@ -96,6 +101,10 @@ public interface Economy {
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
@ -113,6 +122,8 @@ public interface Economy {
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,6 +149,7 @@ 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
* @return Amount currently held in players account
@ -142,6 +157,9 @@ public interface Economy {
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
@ -174,6 +196,9 @@ public interface Economy {
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,6 +226,7 @@ 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 worldName - name of the world
* @param amount Amount to withdraw
@ -205,6 +235,9 @@ public interface Economy {
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
@ -237,6 +274,9 @@ public interface Economy {
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 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,8 +301,9 @@ 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);
@ -269,7 +312,7 @@ public interface Economy {
*
* @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);
@ -278,7 +321,7 @@ public interface Economy {
*
* @param name of the account
* @param amount to withdraw
* @return EconomyResponse Object
* @return Detailed response of transaction
*/
public EconomyResponse bankWithdraw(String name, double amount);
@ -287,12 +330,15 @@ public interface Economy {
*
* @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);
@ -302,11 +348,14 @@ public interface Economy {
*
* @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
@ -317,30 +366,37 @@ public interface Economy {
*
* @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<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
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,6 +405,7 @@ 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 worldName String name of the world
* @return if the account creation was successful

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

@ -39,6 +39,7 @@ public interface IdentityEconomy extends Economy{
* 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();
@ -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<UUID> getAllOnline();
@ -123,6 +128,7 @@ public interface IdentityEconomy extends Economy{
* 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);
@ -145,11 +151,11 @@ public interface IdentityEconomy extends Economy{
/**
* 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 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.
*/
public boolean renameAccount(UUID uuid, String name);

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

@ -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,9 +23,10 @@ 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 {
@ -36,23 +35,30 @@ public abstract class Permission {
/**
* 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,8 +88,9 @@ 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.
*
* <p>
* For easy checking of a commandsender
*
* @param sender to check permissions on
* @param permission to check for
* @return true if the sender has the permission
@ -90,6 +101,7 @@ public abstract class Permission {
/**
* Checks if player has a permission node. (Short for playerHas(...)
*
* @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
@ -146,20 +166,23 @@ public abstract class Permission {
}
/**
* @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 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.
*/
@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
@ -291,6 +314,10 @@ public abstract class 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
@ -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
@ -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
@ -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
@ -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
@ -693,12 +750,14 @@ public abstract class Permission {
/**
* 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();