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 Ecoomy 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 Vault 1.3.01 use {@link #hasAccount(OfflinePlayer)} instead.
084     * 
085     * Checks if this player has an account on the server yet
086     * This will always return true if the player has joined the server at least once
087     * as all major economy plugins auto-generate a player account when the player joins the server
088     * 
089     * @param playerName to check
090     * @return if the player has an account
091     */
092    @Deprecated
093    public boolean hasAccount(String playerName);
094
095    /**
096     * Checks if this player has an account on the server yet
097     * This will always return true if the player has joined the server at least once
098     * as all major economy plugins auto-generate a player account when the player joins the server
099     * 
100     * @param player to check
101     * @return if the player has an account
102     */
103    public boolean hasAccount(OfflinePlayer player);
104    
105    /**
106     * @deprecated As of Vault 1.3.01 use {@link #hasAccount(OfflinePlayer, String)} instead.
107     * 
108     * Checks if this player has an account on the server yet on the given world
109     * This will always return true if the player has joined the server at least once
110     * as all major economy plugins auto-generate a player account when the player joins the server
111     * 
112     * @param playerName to check in the world
113     * @param worldName world-specific account
114     * @return if the player has an account
115     */
116    @Deprecated
117    public boolean hasAccount(String playerName, String worldName);
118
119    /**
120     * Checks if this player has an account on the server yet on the given world
121     * This will always return true if the player has joined the server at least once
122     * as all major economy plugins auto-generate a player account when the player joins the server
123     * 
124     * @param player to check in the world
125     * @param worldName world-specific account
126     * @return if the player has an account
127     */
128    public boolean hasAccount(OfflinePlayer player, String worldName);
129
130    /**
131     * @deprecated As of Vault 1.3.01 use {@link #getBalance(OfflinePlayer)} instead.
132     * Gets balance of a player
133     * 
134     * @param playerName of the player
135     * @return Amount currently held in players account
136     */
137    @Deprecated
138    public double getBalance(String playerName);
139    
140    /**
141     * Gets balance of a player
142     * 
143     * @param player of the player
144     * @return Amount currently held in players account
145     */
146    public double getBalance(OfflinePlayer player);
147
148    /**
149     * @deprecated As of Vault 1.3.01 use {@link #getBalance(OfflinePlayer, String)} instead.
150     * 
151     * Gets balance of a player on the specified world.
152     * IMPLEMENTATION SPECIFIC - if an economy plugin does not support this the global balance will be returned.
153     * @param playerName name of the player
154     * @param world name of the world
155     * @return Amount currently held in players account
156     */
157    @Deprecated
158    public double getBalance(String playerName, String world);
159    
160    /**
161     * Gets balance of a player on the specified world.
162     * IMPLEMENTATION SPECIFIC - if an economy plugin does not support this the global balance will be returned.
163     * @param player to check
164     * @param world name of the world
165     * @return Amount currently held in players account
166     */
167    public double getBalance(OfflinePlayer player, String world);
168    
169    /**
170     * @deprecated As of Vault 1.3.01 use {@link #has(OfflinePlayer, double)} instead.
171     * 
172     * Checks if the player account has the amount - DO NOT USE NEGATIVE AMOUNTS
173     * 
174     * @param playerName to check
175     * @param amount to check for
176     * @return True if <b>playerName</b> has <b>amount</b>, False else wise
177     */
178    @Deprecated
179    public boolean has(String playerName, double amount);
180    
181    /**
182     * Checks if the player account has the amount - DO NOT USE NEGATIVE AMOUNTS
183     * 
184     * @param player to check
185     * @param amount to check for
186     * @return True if <b>player</b> has <b>amount</b>, False else wise
187     */
188    public boolean has(OfflinePlayer player, double amount);
189
190    /**
191     * @deprecated As of Vault 1.3.01 use @{link {@link #has(OfflinePlayer, String, double)} instead.
192     * 
193     * Checks if the player account has the amount in a given world - DO NOT USE NEGATIVE AMOUNTS
194     * IMPLEMENTATION SPECIFIC - if an economy plugin does not support this the global balance will be returned.
195     * 
196     * @param playerName to check
197     * @param worldName to check with
198     * @param amount to check for
199     * @return True if <b>playerName</b> has <b>amount</b>, False else wise
200     */
201    @Deprecated
202    public boolean has(String playerName, String worldName, double amount);
203    
204    /**
205     * Checks if the player account has the amount in a given world - DO NOT USE NEGATIVE AMOUNTS
206     * IMPLEMENTATION SPECIFIC - if an economy plugin does not support this the global balance will be returned.
207     * 
208     * @param player to check
209     * @param worldName to check with
210     * @param amount to check for
211     * @return True if <b>player</b> has <b>amount</b>, False else wise
212     */
213    public boolean has(OfflinePlayer player, String worldName, double amount);
214
215    /**
216     * @deprecated As of Vault 1.3.01 use {@link #withdrawPlayer(OfflinePlayer, double)} instead.
217     * Withdraw an amount from a player - DO NOT USE NEGATIVE AMOUNTS
218     * 
219     * @param playerName Name of player
220     * @param amount Amount to withdraw
221     * @return Detailed response of transaction
222     */
223    @Deprecated
224    public EconomyResponse withdrawPlayer(String playerName, double amount);
225
226    /**
227     * Withdraw an amount from a player - DO NOT USE NEGATIVE AMOUNTS
228     * 
229     * @param player to withdraw from
230     * @param amount Amount to withdraw
231     * @return Detailed response of transaction
232     */
233    public EconomyResponse withdrawPlayer(OfflinePlayer player, double amount);
234
235    /**
236     * @deprecated As of Vault 1.3.01 use {@link #withdrawPlayer(OfflinePlayer, String, double)} instead.
237     * 
238     * Withdraw an amount from a player on a given world - DO NOT USE NEGATIVE AMOUNTS
239     * IMPLEMENTATION SPECIFIC - if an economy plugin does not support this the global balance will be returned.
240     * @param playerName Name of player
241     * @param worldName - name of the world
242     * @param amount Amount to withdraw
243     * @return Detailed response of transaction
244     */
245    @Deprecated
246    public EconomyResponse withdrawPlayer(String playerName, String worldName, double amount);
247    
248    /**
249     * Withdraw an amount from a player on a given world - DO NOT USE NEGATIVE AMOUNTS
250     * IMPLEMENTATION SPECIFIC - if an economy plugin does not support this the global balance will be returned.
251     * @param player to withdraw from
252     * @param worldName - name of the world
253     * @param amount Amount to withdraw
254     * @return Detailed response of transaction
255     */
256    public EconomyResponse withdrawPlayer(OfflinePlayer player, String worldName, double amount);
257
258    /**
259     * @deprecated As of Vault 1.3.01 use {@link #depositPlayer(OfflinePlayer, double)} instead.
260     * 
261     * Deposit an amount to a player - DO NOT USE NEGATIVE AMOUNTS
262     * 
263     * @param playerName Name of player
264     * @param amount Amount to deposit
265     * @return Detailed response of transaction
266     */
267    @Deprecated
268    public EconomyResponse depositPlayer(String playerName, double amount);
269
270    /**
271     * Deposit an amount to a player - DO NOT USE NEGATIVE AMOUNTS
272     * 
273     * @param player to deposit to
274     * @param amount Amount to deposit
275     * @return Detailed response of transaction
276     */
277    public EconomyResponse depositPlayer(OfflinePlayer player, double amount);
278
279    /**
280     * @deprecated As of Vault 1.3.01 use {@link #depositPlayer(OfflinePlayer, String, double)} instead.
281     * 
282     * Deposit an amount to a player - DO NOT USE NEGATIVE AMOUNTS
283     * IMPLEMENTATION SPECIFIC - if an economy plugin does not support this the global balance will be returned.
284     * @param playerName Name of player
285     * @param worldName Name of the world
286     * @param amount Amount to deposit
287     * @return Detailed response of transaction
288     */
289    @Deprecated
290    public EconomyResponse depositPlayer(String playerName, String worldName, double amount);
291   
292    /**
293     * Deposit an amount to a player - DO NOT USE NEGATIVE AMOUNTS
294     * IMPLEMENTATION SPECIFIC - if an economy plugin does not support this the global balance will be returned.
295     * @param player to deposit to
296     * @param worldName name of the world
297     * @param amount Amount to deposit
298     * @return Detailed response of transaction
299     */
300    public EconomyResponse depositPlayer(OfflinePlayer player, String worldName, double amount);
301
302    /**
303     * @deprecated As of Vault 1.3.01 use {{@link #createBank(String, OfflinePlayer)} instead.
304     * 
305     * Creates a bank account with the specified name and the player as the owner
306     * @param name of account
307     * @param player the account should be linked to
308     * @return EconomyResponse Object
309     */
310    @Deprecated
311    public EconomyResponse createBank(String name, String player);
312
313    /**
314     * Creates a bank account with the specified name and the player as the owner
315     * @param name of account
316     * @param player the account should be linked to
317     * @return EconomyResponse Object
318     */
319    public EconomyResponse createBank(String name, OfflinePlayer player);
320
321    /**
322     * Deletes a bank account with the specified name.
323     * @param name of the back to delete
324     * @return if the operation completed successfully
325     */
326    public EconomyResponse deleteBank(String name);
327
328    /**
329     * Returns the amount the bank has
330     * @param name of the account
331     * @return EconomyResponse Object
332     */
333    public EconomyResponse bankBalance(String name);
334
335    /**
336     * Returns true or false whether the bank has the amount specified - DO NOT USE NEGATIVE AMOUNTS
337     * 
338     * @param name of the account
339     * @param amount to check for
340     * @return EconomyResponse Object
341     */
342    public EconomyResponse bankHas(String name, double amount);
343
344    /**
345     * Withdraw an amount from a bank account - DO NOT USE NEGATIVE AMOUNTS
346     * 
347     * @param name of the account
348     * @param amount to withdraw
349     * @return EconomyResponse Object
350     */
351    public EconomyResponse bankWithdraw(String name, double amount);
352
353    /**
354     * Deposit an amount into a bank account - DO NOT USE NEGATIVE AMOUNTS
355     * 
356     * @param name of the account
357     * @param amount to deposit
358     * @return EconomyResponse Object
359     */
360    public EconomyResponse bankDeposit(String name, double amount);
361    
362    /**
363     * @deprecated As of Vault 1.3.01 use {{@link #isBankOwner(String, OfflinePlayer)} instead.
364     * 
365     * Check if a player is the owner of a bank account
366     * 
367     * @param name of the account
368     * @param playerName to check for ownership
369     * @return EconomyResponse Object
370     */
371    @Deprecated
372    public EconomyResponse isBankOwner(String name, String playerName);
373    
374    /**
375     * Check if a player is the owner of a bank account
376     * 
377     * @param name of the account
378     * @param player to check for ownership
379     * @return EconomyResponse Object
380     */
381    public EconomyResponse isBankOwner(String name, OfflinePlayer player);
382
383    /**
384     * @deprecated As of Vault 1.3.01 use {{@link #isBankMember(String, OfflinePlayer)} instead.
385     * 
386     * Check if the player is a member of the bank account
387     * 
388     * @param name of the account
389     * @param playerName to check membership
390     * @return EconomyResponse Object
391     */
392    @Deprecated
393    public EconomyResponse isBankMember(String name, String playerName);
394    
395    /**
396     * Check if the player is a member of the bank account
397     * 
398     * @param name of the account
399     * @param player to check membership
400     * @return EconomyResponse Object
401     */
402    public EconomyResponse isBankMember(String name, OfflinePlayer player);
403
404    /**
405     * Gets the list of banks
406     * @return the List of Banks
407     */
408    public List<String> getBanks();
409
410    /**
411     * @deprecated As of Vault 1.3.01 use {{@link #createPlayerAccount(OfflinePlayer)} instead.
412     * 
413     * Attempts to create a player account for the given player
414     * @param playerName name of the player
415     * @return if the account creation was successful
416     */
417    @Deprecated
418    public boolean createPlayerAccount(String playerName);
419    
420    /**
421     * Attempts to create a player account for the given player
422     * @param player OfflinePlayer
423     * @return if the account creation was successful
424     */
425    public boolean createPlayerAccount(OfflinePlayer player);
426    
427    /**
428     * @deprecated As of Vault 1.3.01 use {{@link #createPlayerAccount(OfflinePlayer, String)} instead.
429     * 
430     * Attempts to create a player account for the given player on the specified world
431     * IMPLEMENTATION SPECIFIC - if an economy plugin does not support this the global balance will be returned.
432     * @param playerName String name of the player
433     * @param worldName String name of the world
434     * @return if the account creation was successful
435     */
436    @Deprecated
437    public boolean createPlayerAccount(String playerName, String worldName);
438    
439    /**
440     * Attempts to create a player account for the given player on the specified world
441     * IMPLEMENTATION SPECIFIC - if an economy plugin does not support this the global balance will be returned.
442     * @param player OfflinePlayer
443     * @param worldName String name of the world
444     * @return if the account creation was successful
445     */
446    public boolean createPlayerAccount(OfflinePlayer player, String worldName);
447}