public interface BankIntf
In each operation, each player is identified by his respective Rising World DB ID (as returned by the Player.getDbId() method); DB ID's are guaranteed to be persistent and unique, more than player names.
The interface has the concept of two special accounts: *) The WORLD account, which is intended as the source of money other plug-ins grant to or withdraw from players for any reason (time spent logged on, activities done, etc.) *) The BANK account, which is the source of money the bank gives to or withdraws from players for any reason (interest, mortgage, etc...)
These two special accounts are also identified by account numbers which cannot occur as player DB ID's.
Only banking plug-ins are expected to use the BANK account and only one banking plug-in is expected to run at a time.
All plug-ins are free to use the WORLD account, but it is suggested that an appropriate reason parameter is provided for all operations which support it, to ensure that bank statements make sense to the players.
By default, the WORLD and the BANK accounts have unlimited cash, but a money system is free to implement its own restrictions to the money flow.
Setup:
For consumer plug-ins (i.e. plug-ins which only use services provided by banks), it is enough to add the BankIntf.jar to the Java project of your plug-in (the details depends upon the specific IDE you are using); the BankIntf.jar must not be included within your plug-in or shipped with it: it is just for the Java compiler to know the details of the interface at compile time.
For provider plug-ins (i.e. plug-ins which provide banking services), the compiled BankIntf.class shall be included in the final .jar of your plug-in, within its proper hierarchy of package directories, parallel to the package of your plug-in.
Again, how to achieve this depends on the specific IDE you are using; the simpler set-up I found is to add the whole hierarchy of directories of the interface source code (i.e. com/vistamaresoft/bankintf/BankIntf.java) in your project, parallel to your plug-in package (i.e. usually, directly under src).
Adding the BankIntf.jar as it is within the .jar of your plug-in is not going to work, as Rising World will not find it.
A plug-in which is both a provider and a consumer, will need both set-up steps described above.
Modifier and Type | Interface and Description |
---|---|
static class |
BankIntf.TransactionData
Stores the data for a money transaction, relative to a certain account.
|
Modifier and Type | Field and Description |
---|---|
static int |
BANK_ID
The 'account number' of the Bank.
|
static int |
ERR_DENY
Operation is not allowed.
|
static int |
ERR_FROM_ACCOUNT_UNKNOWN
The source account does not exist.
|
static int |
ERR_NOT_ENOUGH_MONEY
The source account does not have enough money for the operation.
|
static int |
ERR_NOT_SUPPORTED
Operation is not supported.
|
static int |
ERR_SUCCESS
Operation has been successful.
|
static int |
ERR_TO_ACCOUNT_UNKNOWN
The destination account does not exist.
|
static int |
WORLD_ID
The 'account number' of the 'World'.
|
Modifier and Type | Method and Description |
---|---|
java.lang.Double |
getBalance(int player_dbid)
Returns the account balance for the given account.
|
java.lang.String |
getCurrencyName(int number)
Returns the currency name appropriate for the number
(to account for singular and plural forms).
|
java.lang.String |
getCurrencySymbol()
Return the symbol for the currency used.
|
default BankIntf.TransactionData[] |
getTransactions(int playerDbId,
long fromTimeStamp,
long toTimeStamp)
Returns an array of TransactionData with the transactions relative to
given player_dbid.
|
boolean |
hasAvailableMoney(int player_dbid,
double amount)
Checks whether the given account has at least the given amount of money
available in his account.
|
default int |
recurrentPayement(int from_dbid,
int to_dbid,
double amount,
int days,
int ref,
java.lang.String reason)
Establishes a recurring payment from from_dbid to to_dbid every days days.
|
default int |
requestPayment(int from_dbid,
int to_dbid,
double amount,
int ref,
java.lang.String reason)
Requests a player to authorise a payment.
|
default int |
reserveMoney(int from_dbid,
int to_dbid,
double amount,
java.lang.String reason)
Reserves the given amount of money from from_dbid in the name of to_dbid
for the given reason.
|
int |
transferMoney(int from_dbid,
int to_dbid,
double amount,
java.lang.String reason)
Transfers the given amount of money from one account to another.
|
static final int ERR_SUCCESS
static final int ERR_NOT_SUPPORTED
static final int ERR_DENY
static final int ERR_FROM_ACCOUNT_UNKNOWN
static final int ERR_TO_ACCOUNT_UNKNOWN
static final int ERR_NOT_ENOUGH_MONEY
static final int BANK_ID
static final int WORLD_ID
java.lang.String getCurrencyName(int number)
The name of the currency is distinct from its symbol: the former is to be used in textual contexts, while the latter is for numeric or tabular contexts.
It is up to the implementation to decide how many forms to support: just one ("euro"), two ("franc" and "francs") or more.
number
- the number of units for which the name is queried.java.lang.String getCurrencySymbol()
The name of the currency is distinct from its symbol: the former is to be used in textual contexts, while the latter is for numeric or tabular contexts.
boolean hasAvailableMoney(int player_dbid, double amount)
It is a decision of the implementation whether to support money reservations for future payments (pre-authorisations) or not. If it does support them, the check shall be done on the amount of money freely available on the account, once all encumbrances are discounted.
player_dbid
- the DB ID identifying the account.amount
- the required available amount of money.java.lang.Double getBalance(int player_dbid)
player_dbid
- the DB ID of the account.default BankIntf.TransactionData[] getTransactions(int playerDbId, long fromTimeStamp, long toTimeStamp)
Returns transactions involving player_dbid both as a source and a destination of money; the sign of the amount of each transaction shows if the amount is an income or an expense from player_dbid perspective.
Both fromTimeStamp and endTimeStamp are according to the Unix epoch (milliseconds from January 1st, 1970, 00:00).
playerDbId
- the account to retrieve transactions for.fromTimeStamp
- the start of the time range to return.toTimeStamp
- the end of the time range to return.int transferMoney(int from_dbid, int to_dbid, double amount, java.lang.String reason)
from_dbid
- the DB ID of the source account.to_dbid
- the DB ID of the destination account.amount
- the amount to transfer.reason
- a human-readable text explaining the reason of the
transfer, for the receiving player to read.default int reserveMoney(int from_dbid, int to_dbid, double amount, java.lang.String reason)
The implementation is not required to override this method, if it does not support encumbrances.
The default implementation does nothing and returns ERR_NOT_SUPPORTED.
from_dbid
- the DB ID of the account from whom the amount is reserved.to_dbid
- the DB ID of the account in whom name the amount is reserved.amount
- the amount reserved.reason
- a human-readable text explaining the reason of the request,
for the paying player to read.default int requestPayment(int from_dbid, int to_dbid, double amount, int ref, java.lang.String reason)
The implementation is not required to override this method, if it does not support pre-payments.
The default implementation does nothing and returns ERR_NOT_SUPPORTED.
It is the responsibility of the implementation, if it decides to support pre-payments, to present the request to the paying player, give him a way to authorise/deny and to inform the recipient of the outcome.
from_dbid
- the DB ID of the player from whom payment is requested.to_dbid
- the DB ID of the player requesting the payment.amount
- the requested amount.ref
- a numeric ID identifying the request to the caller.reason
- a human-readable text explaining the reason of the request, for
the paying player to read.default int recurrentPayement(int from_dbid, int to_dbid, double amount, int days, int ref, java.lang.String reason)
The implementation is not required to override this method, if it does not support recurring payments.
The default implementation does nothing and returns ERR_NOT_SUPPORTED.
The request is supposed to have been authorised by the paying player and the implementation is not required to take any step for this. It is however the responsibility of the implementation, if it decides to support recurring payments, to charge the paying account at each deadline and to notify the paid player if the source account does not have enough money to cover the expense.
from_dbid
- the DB ID of the paying player.to_dbid
- the DB ID of the paid player.amount
- the amount of each payment.days
- every how many days to pay the amount.ref
- a numeric ID identifying the request to the caller.reason
- a human-readable text explaining the reason of the request, for
the paying player to read.