Plugin Interfacing ( API )

BOSEconomy Plugin API:
To have your plugin interface with BOSEconomy, add BOSEconomy.jar to your plugin's build path. Use the following code to get a reference to it (called from within your main plugin class):

// This variable will store the reference to BOSEconomy.
BOSEconomy economy = null;

public void loadBOSEconomy()
{
    // Attempt to get the plugin instance for BOSEconomy.
    Plugin temp = this.getServer().getPluginManager().getPlugin("BOSEconomy");
    
    // Check whether BOSEconomy is loaded.
    if(temp == null)
        // BOSEconomy is not loaded on the server.
        economy = null;
    else
        // BOSEconomy is now stored in the "economy" variable.
        economy = (BOSEconomy)temp;
}

The following methods are available for use. These are accessed directly off of the BOSEconomy reference. It's up to your implementation to decide how you want to make this reference available where it is needed.

/**

    * Gets the money owned by the given player name. To find an existing player,

    * the name must be an exact match. Note though that the name is not case

    * sensitive. When attempting to get the money of a nonexistent player, their

    * name is registered in the economy and given the default money value. To

    * check in advance whether a player is registered in the economy, use the

    * playerRegistered() method.

    *

    * @param name

    *          - The name of the player.

    * @return The amount of money owned by the player.

    */

    public double getPlayerMoneyDouble(String name)

    /**

    * Sets a player's money. To modify an existing player, the name must be an

    * exact match. Note though that the name is not case sensitive. If the name

    * does not match any player, it is registered into the economy and given the

    * provided money value. Players are not automatically notified of any changes

    * to their money; if desired, it must be done explicitly after calling this

    * method. If the mustBeOnline flag is set to true, the method will only

    * perform changes on players that are online and will not register

    * nonexistent players into the economy.

    *

    * @param name

    *          - The name of the player.

    * @param money

    *          - The money to set the player to.

    * @param mustBeOnline

    *          - Whether the player must be online to perform the change.

    * @return True if any changes were made, false otherwise.

    */

    public boolean setPlayerMoney(String name, double money, boolean mustBeOnline)

    /**

    * Adds to a player's money. Negative values will subtract money instead. Note

    * that a player's money can be negative. To modify an existing player, the

    * name must be an exact match. Note though that the name is not case

    * sensitive. If the name does not match any player, it is registered into the

    * economy and the given money value is added to it. Players are not

    * automatically notified of any changes to their money; if desired, it must

    * be done explicitly after calling this method. If the mustBeOnline flag is

    * set to true, the method will only perform changes on players that are

    * online and will not register nonexistent players into the economy.

    *

    * @param name

    *          - The name of the player.

    * @param money

    *          - The money to add to the player.

    * @param mustBeOnline

    *          - Whether the player must be online to perform the change.

    * @return True if any changes were made, false otherwise.

    */

    public boolean addPlayerMoney(String name, double money, boolean mustBeOnline)

    /**

    * Checks if a player is registered into the economy. All online players are

    * already considered registered. The name of the player must be an exact

    * match, though the name is not case sensitive.

    *

    * @param name

    *          - The name of the player.

    * @param mustBeOnline

    *          - If set, the method will only return true if the player is

    *          registered and is online.

    * @return Whether the player is registered in the economy.

    */

    public boolean playerRegistered(String name, boolean mustBeOnline)

    /**

    * Registers the given player name into the economy system. If a player with

    * this name is already registered, nothing happens.

    *

    * @param name

    *          - The name of the player to register.

    * @return True if the player was registered, or false if a player with that

    *        name already exists.

    */

    public boolean registerPlayer(String name)

    /**

    * Sends a message to the given player informing them of how much money they

    * have. If the player is not online, nothing happens.

    *

    * @param name

    *          - The name of the player.

    */

    public void tellPlayerMoney(String name)

    /**

    * Gets the amount of money in the given bank account. To find an existing

    * bank, the name must be an exact match. Note though that the name is not

    * case sensitive. When attempting to get the money of a nonexistent bank, a

    * bank by that name is created automatically. To check in advance whether a

    * bank exists, use the bankExists() method.

    *

    * @param name

    *          - The name of the bank.

    * @return The amount of money in the bank.

    */

    public double getBankMoneyDouble(String name)

    /**

    * Sets the amount of money in the given bank account. To modify an existing

    * bank, the name must be an exact match. Note though that the name is not

    * case sensitive. If the name does not match any bank and the mustExist flag

    * is set to false, a bank by that name is created and given the provided

    * money value. Any members of the bank who are online will not be

    * automatically notified of any changes. If desired, it must be done

    * explicitly after calling this method.

    *

    * @param name

    *          - The name of the bank.

    * @param money

    *          - The money to set the bank to.

    * @param mustExist

    *          - Whether he bank account must already exist.

    * @return True if any changes were made, false otherwise.

    */

    public boolean setBankMoney(String name, double money, boolean mustExist)

    /**

    * Adds to the amount of money in the given bank account. To modify an

    * existing bank, the name must be an exact match. Note though that the name

    * is not case sensitive. If the name does not match any bank and the

    * mustExist flag is set to false, a bank by that name is created and given

    * the provided money value. Any members of the bank who are online will not

    * be automatically notified of any changes. If desired, it must be done

    * explicitly after calling this method.

    *

    * @param name

    *          - The name of the bank.

    * @param money

    *          - The money to add to the bank.

    * @param mustExist

    *          - Whether he bank account must already exist.

    * @return True if any changes were made, false otherwise.

    */

    public boolean addBankMoney(String name, double money, boolean mustExist)

    /**

    * Checks if a bank account exists in the economy. The name of the bank must

    * be an exact match, though the name is not case sensitive.

    *

    * @param name

    *          - The name of the bank.

    * @return Whether the bank account exists.

    */

    public boolean bankExists(String name)

    /**

    * Creates the given bank account. If a bank with this name already exists,

    * nothing happens.

    *

    * @param name

    *          - The name of the bank to create.

    * @return True if the bank was created, or false if a bank with that name

    *        already exists.

    */

    public boolean createBank(String name)

    /**

    * Removes the given bank account. Members of the account are not notified of

    * the removal. If no bank with this name exists, nothing happens.

    *

    * @param name

    *          - The name of the bank to remove.

    * @return True if the bank was removed, or false no bank with that name

    *        existed.

    */

    public boolean removeBank(String name)

    /**

    * Adds an owner to the given bank account. Owners can withdraw funds from the

    * account and add or remove other owners and members. If the name is already

    * a member, they are promoted to an owner. The name will not be added if it

    * is null, empty, or a duplicate. If the bank account doesn't exist and the

    * mustExist flag is set to false, one by the given name is created first. The

    * name of the owner will be added regardless of whether they are online or

    * actually exist.

    *

    * @param bank

    *          - The name of the bank.

    * @param owner

    *          - The name of the owner to add.

    * @param mustExist

    *          - Whether the bank account must already exist to add an owner.

    * @return True if the owner was added, or false if otherwise. False may be

    *        returned either because the bank doesn't exist and mustExist was

    *        true, or because an owner by this name already exists.

    */

    public boolean addBankOwner(String bank, String owner, boolean mustExist)

    /**

    * Adds a member to the given bank account. Members can withdraw funds from

    * the account. If the name is already an owner, they are demoted to a member.

    * The name will not be added if it is null, empty, or a duplicate. If the

    * bank account doesn't exist and the mustExist flag is set to false, one by

    * the given name is created first. The name of the member will be added

    * regardless of whether they are online or actually exist.

    *

    * @param bank

    *          - The name of the bank.

    * @param member

    *          - The name of the member to add.

    * @param mustExist

    *          - Whether the bank account must already exist to add a member.

    * @return True if the member was added, or false if otherwise. False may be

    *        returned either because the bank doesn't exist and mustExist was

    *        true, or because a member by this name already exists.

    */

    public boolean addBankMember(String bank, String member, boolean mustExist)

    /**

    * Removes the given owner or member from the given bank account.

    *

    * @param bank

    *          - The name of the bank.

    * @param player

    *          - The name of the owner or member to remove.

    * @return True if an owner or member was removed, or false if otherwise.

    *        False may be returned either because the bank doesn't exist or

    *        because no player by this name was registered to it.

    */

    public boolean removeBankPlayer(String bank, String player)

    /**

    * Checks if the given name is an owner of the bank account.

    *

    * @param bank

    *          - The name of the bank.

    * @param owner

    *          - The name of the owner to check for.

    * @return True if the name is an owner, or false if otherwise. False may be

    *        returned either because the bank doesn't exist or because the given

    *        name is not an owner.

    */

    public boolean isBankOwner(String bank, String owner)

    /**

    * Checks if the given name is a member of the bank account. Note that owners

    * are not considered to be members in this context and that this method will

    * return false if the name of an owner is provided.

    *

    * @param bank

    *          - The name of the bank.

    * @param owner

    *          - The name of the member to check for.

    * @return True if the name is a member, or false if otherwise. False may be

    *        returned either because the bank doesn't exist or because the given

    *        name is not a member.

    */

    public boolean isBankMember(String bank, String member)

    /**

    * Sends a message to all online owners and members of the given bank account.

    * If no bank account exists by this name, nothing happens.

    *

    * @param bank

    *          - The name of the bank.

    * @param message

    *          - The message to send to the bank's members.

    * @param sender

    *          - The name of the sender. If the sender is a member of the bank,

    *          they are not sent the message. Leave this null to send the message

    *          to all of the members.

    */

    public void tellBankMessage(String bank, String message, String sender)

    /**

    * Sends a message to all online owners and members informing them of how much

    * money this bank account has. This should not be confused with

    * tellBankBalanceToPlayer(), which sends this message to a specified player.

    * This method may be useful in a context where all members were just notified

    * of a change and you wish to follow it with the new balance of the account.

    * If the bank account doesn't exist, nothing happens.

    *

    * @param bank

    *          - The name of the bank.

    * @param account

    *          - The name of the player.

    */

    public void tellBankBalance(String bank)

    /**

    * Sends a message to the given player informing them of how much money this

    * bank account has. This should not be confused with tellBankBalance(), which

    * sends this message to all members of the account. If the player is not

    * online, or if the bank account doesn't exist, nothing happens.

    *

    * @param bank

    *          - The name of the bank.

    * @param account

    *          - The name of the player.

    */

    public void tellBankBalanceToPlayer(String bank, String player)

    /**

    * Gets the value of the initial money setting. This is how much money brand

    * new players are initialized with when they first enter the economy.

    *

    * @return The initial money.

    */

    public double getInitialMoneyDouble()

    /**

    * Gets the name of one unit of currency. This name is not capitalized and

    * should be singular. Ex: "coin"

    */

    public String getMoneyName()

    /**

    * Gets the name of a pluralized unit of currency. Ex: "coins"

    */

    public String getMoneyNamePlural()

    /**

    * Gets the name of one capitalized unit of currency. Ex: "Coin"

    */

    public String getMoneyNameCaps()

    /**

    * Gets the name of a capitalized and pluralized unit of currency. Ex: "Coins"

    */

    public String getMoneyNamePluralCaps()

    /**

    * Gets the number of decimal digits used as the fraction for a money value.

    * For instance, a money system using hundredths (e.g. 314.15 pies) would have

    * two fractional digits.

    */

    public int getFractionalDigits()

    /**

    * Gets an alphabetically sorted list containing the names of every player

    * currently registered in the economy. The list is independent of the

    * underlying player data, so note that every call to this method will

    * allocate a new list. Be sure to de-reference it when you're finished using

    * it.

    *

    * @return The player list. If there are no players then the list will be

    *        empty, not null.

    */

    public List<String> getPlayerList()

    /**

    * Gets an alphabetically sorted list containing the names of every bank

    * account currently registered in the economy. The list is independent of the

    * underlying bank account data, so note that every call to this method will

    * allocate a new list. Be sure to de-reference it when you're finished using

    * it.

    *

    * @return The bank account list. If there are no bank accounts then the list

    *        will be empty, not null.

    */

    public List<String> getBankList()

    /**

    * Takes a money value and rounds it to the nearest appropriate value based on

    * however many fractional digits are set to follow the radix point.

    *

    * @param money

    *          - The value of money to round.

    *

    * @return The rounded money value.

    */

    public double getMoneyRounded(double money)

    /**

    * Converts a money value into its formatted decimal string. This will trim

    * off any extra digits or fill extra space after the decimal point with

    * zeroes. The money value is truncated, not rounded. If you need to round and

    * format the money value, invoke getMoneyRounded() first and then use this

    * method.

    *

    * @param value

    *          - The value of money to format.

    * @return The formatted value.

    */

    public String getMoneyFormatted(double money)

    /**

    * Gets the correct form of the money name depending on whether a given money

    * value is singular or plural. Positive and negative one will return the

    * singular form, and all other values will return the plural form.

    *

    * @param money

    *          - The amount of money.

    * @return The appropriate money name.

    */

    public String getMoneyNameProper(double money)

    /**

    * Gets the correct capitalized form of the money name depending on whether a

    * given money value is singular or plural. Positive and negative one will

    * return the singular form, and all other values will return the plural form.

    *

    * @param money

    *          - The amount of money.

    * @return The appropriate capitalized money name.

    */

    public String getMoneyNameCapsProper(double money)

You may notice that there are some other methods in the BOSEconomy reference, as well as some static variables. These are subject to change without warning and should never be utilized by your plugin. The methods listed above, however, will rarely if ever need to be changed. When necessary, methods will be deprecated rather than removed.

Need a new method? Don't like something about this API? Please don't hesitate to post feedback about it!


Comments

Posts Quoted:
Reply
Clear All Quotes