Broker.java

package com.gmail.justisroot.broker;

import java.math.BigDecimal;
import java.util.UUID;

import org.spongepowered.api.item.inventory.Inventory;
import org.spongepowered.api.item.inventory.ItemStack;

public interface Broker {

	/**
	 * Get the identifier for the market used by this player in this world.
	 * @param playerID The UUID for the player accessing the market
	 * @param worldName The name of the world that the transaction will take place in
	 * @return String representation of the ID for the market which the player in the provided world will see
	 */
	public String getMarketID(UUID playerID, String worldName);

	/**
	 * Can the provided player make purchases in the provided world?
	 * @param playerID The UUID for the player to attempt purchases
	 * @param worldName The name of the world that the transaction will take place in
	 * @return true if the player can make purchases in this world, false if otherwise
	 */
	public boolean canBuy(UUID playerID, String worldName);

	/**
	 * Can the provided player make sales in the provided world?
	 * @param playerID The UUID for the player to attempt sales
	 * @param worldName The name of the world that the
	 * @return true if the player can make sales in this world, false if otherwise
	 */
	public boolean canSell(UUID playerID, String worldName);

	/**
	 * Can the provided player purchase the provided item in the provided world?
	 * @param playerID The UUID for the player attempting to purchase the item
	 * @param worldName The name of the world that the transaction will take place in
	 * @param item The ItemStack that the player is attempting to purchase
	 * @return true if the player can purchase the item in this world, false if otherwise
	 */
	public boolean canBeBought(UUID playerID, String worldName, ItemStack item);

	/**
	 * Can the provided player sell the provided item in the provided world?
	 * @param playerID The UUID for the player attempting to sell the item
	 * @param worldName The name of the world that the transaction will take place in
	 * @param item The ItemStack that the player is attempting to sell
	 * @return true if the player can sell the item in this world, false if otherwise
	 */
	public boolean canBeSold(UUID playerID, String worldName, ItemStack item);

	/**
	 * Can the provided player sell damaged items in the provided world?
	 * @param playerID The UUID for the player attempting to sell damaged items
	 * @param worldName The name of the world that the transaction will take place in
	 * @return true if the player can sell damaged items in this world, false if otherwise
	 */
	public boolean canSellDamagedItems(UUID playerID, String worldName);

	/**
	 * Get the price the provided player will need to pay to obtain the provided item in the provided world.<br>
	 * Has the same functionality as {@link #getBuyPrice(UUID, String, ItemStack, int)} where 'amount' is 1.
	 * @param playerID The UUID for the player attempting to buy the item
	 * @param worldName The name of the world that the transaction will take place in
	 * @param item The ItemStack that the player is attempting to purchase
	 * @return BigDecimal representation of the price the player will need to pay in order to buy the item
	 */
	default public BigDecimal getBuyPrice(UUID playerID, String worldName, ItemStack item) {
		return getBuyPrice(playerID, worldName, item, 1);
	}

	/**
	 * Get the price the provided player will receive for selling the provided item in the provided world.
	 * Has the same functionality as {@link #getSellPrice(UUID, String, ItemStack, int)} where 'amount' is 1.
	 * @param playerID The UUID for the player attempting to sell the item
	 * @param worldName The name of the world that the transaction will take place in
	 * @param item The ItemStack that the player is attempting to sell
	 * @return BigDecimal representation of the price the player will be paid as a result of selling
	 */
	default public BigDecimal getSellPrice(UUID playerID, String worldName, ItemStack item) {
		return getSellPrice(playerID, worldName, item, 1);
	}

	/**
	 * Get the price the provided player will need to pay to obtain the provided amount of the provided item in the provided world.<br>
	 * The amount of individual items the player is paying for should equal the number of items in the ItemStack, multiplied by the amount of ItemStacks being purchased.
	 * @param playerID The UUID for the player attempting to buy the item
	 * @param worldName The name of the world that the transaction will take place in
	 * @param item The ItemStack that the player is attempting to purchase
	 * @param amount The amount of ItemStacks that the player is attempting to purchase
	 * @return BigDecimal representation of the price the player will need to pay in order to buy these items
	 */
	public BigDecimal getBuyPrice(UUID playerID, String worldName, ItemStack item, int amount);

	/**
	 * Get the price the provided player will receive for selling the provided item in the provided world.
	 * The amount of individual items the player is selling should equal the number of items in the ItemStack, multiplied by the amount of ItemStacks being sold.
	 * @param playerID The UUID for the player attempting to sell the item
	 * @param worldName The name of the world that the transaction will take place in
	 * @param item The ItemStack that the player is attempting to sell
	 * @param amount The amount of ItemStacks that the player is attempting to sell
	 * @return BigDecimal representation of the price the player will be paid as a result of selling
	 */
	public BigDecimal getSellPrice(UUID playerID, String worldName, ItemStack item, int amount);

	/**
	 * Set the buy price for the provided item in the provided world using the provided player's market.<br>
	 * Price is always set on an individual basis, the amount of items in the stack is thus always ignored.
	 * @param playerID The UUID for the player whose market prices are being modified
	 * @param worldName The name of the world where the market to be modified is located
	 * @param item The ItemStack whose buy price is being modified
	 * @param price The new value of the ItemStack
	 */
	public void setBuyPrice(UUID playerID, String worldName, ItemStack item, BigDecimal price);

	/**
	 * Set the sell price for the provided item in the provided world using the provided player's market.<br>
	 * Price is always set on an individual basis, the amount of items in the stack is thus always ignored.
	 * @param playerID The UUID for the player whose market prices are being modified
	 * @param worldName The name of the world where the market to be modified is located
	 * @param item The ItemStack whose buy price is being modified
	 * @param price The new value of the ItemStack
	 */
	public void setSellPrice(UUID playerID, String worldName, ItemStack item, BigDecimal price);

	/**
	 * Have the provided player buy the provided item in the provided world.<br>
	 * The implementing plugin handles all aspects of the transaction including redistribution of player funds and distribution of the transacted item.
	 * @param playerID The UUID for the player whose market will be used for the purchase of the item
	 * @param worldName The name of the world in which the transaction is taking place
	 * @param item The ItemStack being transacted
	 */
	default public void buy(UUID playerID, String worldName, ItemStack item) {
		buy(playerID, worldName, item, 1);
	}

	/**
	 * Have the provided player buy the provided item in the provided world.<br>
	 * The implementing plugin handles all aspects of the transaction including redistribution of player funds and distribution of the transacted item.<br>
	 * The amount of individual items the player is paying for should equal the number of items in the ItemStack, multiplied by the amount of ItemStacks being purchased.
	 * @param playerID The UUID for the player whose market will be used for the purchase of the item
	 * @param worldName The name of the world in which the transaction is taking place
	 * @param item The ItemStack being transacted
	 * @param amount The amount of stacks being purchased
	 */
	public void buy(UUID playerID, String worldName, ItemStack item, int amount);

	/**
	 * Have the provided player buy all of the items in the provided inventory, in the provided world.<br>
	 * The implementing plugin handles all aspects of the transaction including redistribution of player funds and distribution of the transacted item.<br>
	 * @param playerID The UUID for the player whose market will be used for the purchase of the items
	 * @param worldName The name of the world in which the transaction is taking place
	 * @param inv The Inventory of items to be transacted<br>
	 * Items in this inventory will not be modified or removed upon purchase by the implementing plugin.
	 */
	public void buy(UUID playerID, String worldName, Inventory inv);

	/**
	 * Have the provided player sell the provided item in the provided world.<br>
	 * The implementing plugin handles all aspects of the transaction including redistribution of player funds and distribution of the transacted item.
	 * @param playerID The UUID for the player whose market will be used for the sale of the item
	 * @param worldName The name of the world in which the transaction is taking place
	 * @param item The ItemStack being transacted
	 */
	default public void sell(UUID playerID, String worldName, ItemStack item) {
		sell(playerID, worldName, item, 1);
	}

	/**
	 * Have the provided player sell the provided item in the provided world.<br>
	 * The implementing plugin handles all aspects of the transaction including redistribution of player funds and distribution of the transacted item.<br>
	 * The amount of individual items the player is selling should equal the number of items in the ItemStack, multiplied by the amount of ItemStacks being sold.
	 * @param playerID The UUID for the player whose market will be used for the sale of the item
	 * @param worldName The name of the world in which the transaction is taking place
	 * @param item The ItemStack being transacted
	 * @param amount The amount of stacks being sold
	 */
	public void sell(UUID playerID, String worldName, ItemStack item, int amount);

	/**
	 * Have the provided player sell all of the items in the provided inventory, in the provided world.<br>
	 * The implementing plugin handles all aspects of the transaction including redistribution of player funds and distribution of the transacted item.<br>
	 * @param playerID The UUID for the player whose market will be used for the sale of the items
	 * @param worldName The name of the world in which the transaction is taking place
	 * @param inv The Inventory of items to be transacted<br>
	 * Items in this inventory will not be modified or removed upon sale by the implementing plugin.
	 */
	public void sell(UUID playerID, String worldName, Inventory inv);

	/**
	 * Format the provided value into a currency String used within the implementing market.
	 * @param playerID The UUID for the player whose market will be used for formatting the provided value into currency
	 * @param worldName The name of the world in which the value will be formatted into currency
	 * @param value The value to be formatted into currency
	 * @return String representation of the value as determined by the market of the provided player in the provided world
	 */
	public String format(UUID playerID, String worldName, BigDecimal value);

}