001/* This file is part of Vault.
002
003    Vault is free software: you can redistribute it and/or modify
004    it under the terms of the GNU Lesser General Public License as published by
005    the Free Software Foundation, either version 3 of the License, or
006    (at your option) any later version.
007
008    Vault is distributed in the hope that it will be useful,
009    but WITHOUT ANY WARRANTY; without even the implied warranty of
010    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
011    GNU Lesser General Public License for more details.
012
013    You should have received a copy of the GNU Lesser General Public License
014    along with Vault.  If not, see <http://www.gnu.org/licenses/>.
015 */
016
017package net.milkbowl.vault.economy;
018
019import java.util.List;
020
021import org.bukkit.OfflinePlayer;
022
023/**
024 * The main economy API
025 *
026 */
027public interface Economy {
028
029    /**
030     * Checks if economy method is enabled.
031     * @return Success or Failure
032     */
033    public boolean isEnabled();
034
035    /**
036     * Gets name of economy method
037     * @return Name of Economy Method
038     */
039    public String getName();
040
041    /**
042     * Returns true if the given implementation supports banks.
043     * @return true if the implementation supports banks
044     */
045    public boolean hasBankSupport();
046
047    /**
048     * Some economy plugins round off after a certain number of digits.
049     * This function returns the number of digits the plugin keeps
050     * or -1 if no rounding occurs.
051     * @return number of digits after the decimal point kept
052     */
053    public int fractionalDigits();
054
055    /**
056     * Format amount into a human readable String This provides translation into
057     * economy specific formatting to improve consistency between plugins.  
058     *
059     * @param amount to format
060     * @return Human readable string describing amount
061     */
062    public String format(double amount);
063
064    /**
065     * Returns the name of the currency in plural form.
066     * If the economy being used does not support currency names then an empty string will be returned.
067     * 
068     * @return name of the currency (plural)
069     */
070    public String currencyNamePlural();
071
072
073    /**
074     * Returns the name of the currency in singular form.
075     * If the economy being used does not support currency names then an empty string will be returned.
076     * 
077     * @return name of the currency (singular)
078     */
079    public String currencyNameSingular();
080
081    /**
082     * 
083     * @deprecated As of VaultAPI 1.4 use {@link #hasAccount(OfflinePlayer)} instead.
084     */
085    @Deprecated
086    public boolean hasAccount(String playerName);
087
088    /**
089     * Checks if this player has an account on the server yet
090     * This will always return true if the player has joined the server at least once
091     * as all major economy plugins auto-generate a player account when the player joins the server
092     * 
093     * @param player to check
094     * @return if the player has an account
095     */
096    public boolean hasAccount(OfflinePlayer player);
097    
098    /**
099     * @deprecated As of VaultAPI 1.4 use {@link #hasAccount(OfflinePlayer, String)} instead.
100     */
101    @Deprecated
102    public boolean hasAccount(String playerName, String worldName);
103
104    /**
105     * Checks if this player has an account on the server yet on the given world
106     * This will always return true if the player has joined the server at least once
107     * as all major economy plugins auto-generate a player account when the player joins the server
108     * 
109     * @param player to check in the world
110     * @param worldName world-specific account
111     * @return if the player has an account
112     */
113    public boolean hasAccount(OfflinePlayer player, String worldName);
114
115    /**
116     * @deprecated As of VaultAPI 1.4 use {@link #getBalance(OfflinePlayer)} instead.
117     */
118    @Deprecated
119    public double getBalance(String playerName);
120    
121    /**
122     * Gets balance of a player
123     * 
124     * @param player of the player
125     * @return Amount currently held in players account
126     */
127    public double getBalance(OfflinePlayer player);
128
129    /**
130     * @deprecated As of VaultAPI 1.4 use {@link #getBalance(OfflinePlayer, String)} instead.
131     */
132    @Deprecated
133    public double getBalance(String playerName, String world);
134    
135    /**
136     * Gets balance of a player on the specified world.
137     * IMPLEMENTATION SPECIFIC - if an economy plugin does not support this the global balance will be returned.
138     * @param player to check
139     * @param world name of the world
140     * @return Amount currently held in players account
141     */
142    public double getBalance(OfflinePlayer player, String world);
143    
144    /**
145     * @deprecated As of VaultAPI 1.4 use {@link #has(OfflinePlayer, double)} instead.
146     */
147    @Deprecated
148    public boolean has(String playerName, double amount);
149    
150    /**
151     * Checks if the player account has the amount - DO NOT USE NEGATIVE AMOUNTS
152     * 
153     * @param player to check
154     * @param amount to check for
155     * @return True if <b>player</b> has <b>amount</b>, False else wise
156     */
157    public boolean has(OfflinePlayer player, double amount);
158
159    /**
160     * @deprecated As of VaultAPI 1.4 use @{link {@link #has(OfflinePlayer, String, double)} instead.
161     */
162    @Deprecated
163    public boolean has(String playerName, String worldName, double amount);
164    
165    /**
166     * Checks if the player account has the amount in a given world - DO NOT USE NEGATIVE AMOUNTS
167     * IMPLEMENTATION SPECIFIC - if an economy plugin does not support this the global balance will be returned.
168     * 
169     * @param player to check
170     * @param worldName to check with
171     * @param amount to check for
172     * @return True if <b>player</b> has <b>amount</b>, False else wise
173     */
174    public boolean has(OfflinePlayer player, String worldName, double amount);
175
176    /**
177     * @deprecated As of VaultAPI 1.4 use {@link #withdrawPlayer(OfflinePlayer, double)} instead.
178     */
179    @Deprecated
180    public EconomyResponse withdrawPlayer(String playerName, double amount);
181
182    /**
183     * Withdraw an amount from a player - DO NOT USE NEGATIVE AMOUNTS
184     * 
185     * @param player to withdraw from
186     * @param amount Amount to withdraw
187     * @return Detailed response of transaction
188     */
189    public EconomyResponse withdrawPlayer(OfflinePlayer player, double amount);
190
191    /**
192     * @deprecated As of VaultAPI 1.4 use {@link #withdrawPlayer(OfflinePlayer, String, double)} instead.
193     */
194    @Deprecated
195    public EconomyResponse withdrawPlayer(String playerName, String worldName, double amount);
196    
197    /**
198     * Withdraw an amount from a player on a given world - DO NOT USE NEGATIVE AMOUNTS
199     * IMPLEMENTATION SPECIFIC - if an economy plugin does not support this the global balance will be returned.
200     * @param player to withdraw from
201     * @param worldName - name of the world
202     * @param amount Amount to withdraw
203     * @return Detailed response of transaction
204     */
205    public EconomyResponse withdrawPlayer(OfflinePlayer player, String worldName, double amount);
206
207    /**
208     * @deprecated As of VaultAPI 1.4 use {@link #depositPlayer(OfflinePlayer, double)} instead.
209     */
210    @Deprecated
211    public EconomyResponse depositPlayer(String playerName, double amount);
212
213    /**
214     * Deposit an amount to a player - DO NOT USE NEGATIVE AMOUNTS
215     * 
216     * @param player to deposit to
217     * @param amount Amount to deposit
218     * @return Detailed response of transaction
219     */
220    public EconomyResponse depositPlayer(OfflinePlayer player, double amount);
221
222    /**
223     * @deprecated As of VaultAPI 1.4 use {@link #depositPlayer(OfflinePlayer, String, double)} instead.
224     */
225    @Deprecated
226    public EconomyResponse depositPlayer(String playerName, String worldName, double amount);
227   
228    /**
229     * Deposit an amount to a player - DO NOT USE NEGATIVE AMOUNTS
230     * IMPLEMENTATION SPECIFIC - if an economy plugin does not support this the global balance will be returned.
231     * 
232     * @param player to deposit to
233     * @param worldName name of the world
234     * @param amount Amount to deposit
235     * @return Detailed response of transaction
236     */
237    public EconomyResponse depositPlayer(OfflinePlayer player, String worldName, double amount);
238
239    /**
240     * @deprecated As of VaultAPI 1.4 use {{@link #createBank(String, OfflinePlayer)} instead.
241     */
242    @Deprecated
243    public EconomyResponse createBank(String name, String player);
244
245    /**
246     * Creates a bank account with the specified name and the player as the owner
247     * @param name of account
248     * @param player the account should be linked to
249     * @return EconomyResponse Object
250     */
251    public EconomyResponse createBank(String name, OfflinePlayer player);
252
253    /**
254     * Deletes a bank account with the specified name.
255     * @param name of the back to delete
256     * @return if the operation completed successfully
257     */
258    public EconomyResponse deleteBank(String name);
259
260    /**
261     * Returns the amount the bank has
262     * @param name of the account
263     * @return EconomyResponse Object
264     */
265    public EconomyResponse bankBalance(String name);
266
267    /**
268     * Returns true or false whether the bank has the amount specified - DO NOT USE NEGATIVE AMOUNTS
269     * 
270     * @param name of the account
271     * @param amount to check for
272     * @return EconomyResponse Object
273     */
274    public EconomyResponse bankHas(String name, double amount);
275
276    /**
277     * Withdraw an amount from a bank account - DO NOT USE NEGATIVE AMOUNTS
278     * 
279     * @param name of the account
280     * @param amount to withdraw
281     * @return EconomyResponse Object
282     */
283    public EconomyResponse bankWithdraw(String name, double amount);
284
285    /**
286     * Deposit an amount into a bank account - DO NOT USE NEGATIVE AMOUNTS
287     * 
288     * @param name of the account
289     * @param amount to deposit
290     * @return EconomyResponse Object
291     */
292    public EconomyResponse bankDeposit(String name, double amount);
293    
294    /**
295     * @deprecated As of VaultAPI 1.4 use {{@link #isBankOwner(String, OfflinePlayer)} instead.
296     */
297    @Deprecated
298    public EconomyResponse isBankOwner(String name, String playerName);
299    
300    /**
301     * Check if a player is the owner of a bank account
302     * 
303     * @param name of the account
304     * @param player to check for ownership
305     * @return EconomyResponse Object
306     */
307    public EconomyResponse isBankOwner(String name, OfflinePlayer player);
308
309    /**
310     * @deprecated As of VaultAPI 1.4 use {{@link #isBankMember(String, OfflinePlayer)} instead.
311     */
312    @Deprecated
313    public EconomyResponse isBankMember(String name, String playerName);
314    
315    /**
316     * Check if the player is a member of the bank account
317     * 
318     * @param name of the account
319     * @param player to check membership
320     * @return EconomyResponse Object
321     */
322    public EconomyResponse isBankMember(String name, OfflinePlayer player);
323
324    /**
325     * Gets the list of banks
326     * @return the List of Banks
327     */
328    public List<String> getBanks();
329
330    /**
331     * @deprecated As of VaultAPI 1.4 use {{@link #createPlayerAccount(OfflinePlayer)} instead.
332     */
333    @Deprecated
334    public boolean createPlayerAccount(String playerName);
335    
336    /**
337     * Attempts to create a player account for the given player
338     * @param player OfflinePlayer
339     * @return if the account creation was successful
340     */
341    public boolean createPlayerAccount(OfflinePlayer player);
342    
343    /**
344     * @deprecated As of VaultAPI 1.4 use {{@link #createPlayerAccount(OfflinePlayer, String)} instead.
345     */
346    @Deprecated
347    public boolean createPlayerAccount(String playerName, String worldName);
348    
349    /**
350     * Attempts to create a player account for the given player on the specified world
351     * IMPLEMENTATION SPECIFIC - if an economy plugin does not support this then false will always be returned.
352     * @param player OfflinePlayer
353     * @param worldName String name of the world
354     * @return if the account creation was successful
355     */
356    public boolean createPlayerAccount(OfflinePlayer player, String worldName);
357}