This document describes in Example form the usage of the NeuClear Ledger API. The Document is not intended as an implemntation document or a strict API definition. The current final API Specifications can be found in the Project Java Docs.
The main purpose of the NeuClear Ledger API is to provide a simple API for applications in need of Financial Ledger functionality. This could be Payment Systems, Sales Ledgers or General Ledger (accounting) systems. I'm sure there are many other applications. The main idea behind the API is to hide the implementation of such Ledgers from the front ends such as GUI's and web services.
The LedgerFactory is used to create new Ledgers. This handles the background implementations etc. You can have multiple Ledger's at any given time. Each identified by a name.
LedgerController controller=new SimpleLedgerController("test");
The above simply gets an instance of the LedgerFactory and returns a Ledger called "test" from the default implementation.
Books are the main groupings with a ledger. You might now them as accounts, books or something completely different. In the current implementation Books can be created on the fly. Different implementations might chose to change this behaviour, so bear this in mind.
LedgerController controller=new SimpleLedgerController("test");
Book bob=controller.getBook("Bob");
LedgerController controller=new SimpleLedgerController("test");
Book bob=controller.getBook("Bob");
double bobsBalance=controller.getBalance(bob);
A Transfer consists of a Debit (A subtraction) from one book and a Credit (an addition) to another book.
LedgerController controller=new SimpleLedgerController("test");
Book bob=controller.getBook("Bob");
Book alice=controller.getBook("Alice");
controller.transfer(bob,alice,100,"Loan");
For this example we had to create 2 Books. We transfered 100 from Bob's account to Alice's Account. These were transfered at the current time and with the comment of "Loan".
To create a complex Transaction you first need to create an UnPostedTransaction to work with. To this you can add several items for multiple Books. Remember though the Transaction must balance. The API wont let you post a Transaction that doesnt balance.
LedgerController controller=new SimpleLedgerController("test");
Book bob=controller.getBook("Bob");
Book alice=controller.getBook("Alice");
Book fees=controller.getBook("Fees");
UnPostedTransaction tran=new UnPostedTransaction(uniqueid,"Thanks");
double amount=100;
double fee=100*.01; // Charge a 1% fee
if (alice.getBalance()<(amount+fee))
// throw error Insufficient Funds
tran.addItem(alice,-(amount+fee)); // Subtract amount+fee's from Alice's account
tran.additem(bob,amount); // Add amount to Bob's account
tran.additem(fees,fee); // Add Fee's to Fee account
PostedTransaction posted=controller.performTransaction(tran); // Post Transaction to the Ledger
You can add as many items to a transaction as you wish as long as they balance when it gets posted. Once a transaction has been posted it cant be modified.
Held Transactions are mainly useful in Payment Systems and not so much in Account normal accounting systems. This means you can pretty much ignore it if you're not working on payment systems.
Held Transactions are what happens when your credit card get's authorized at a hotel for example. A hotel might authorize say $200 on check in. When you check out, they run up the actual bill and create a charge for that amount releasing the authorization. The Authorization is normally valid for a certain amount of time. During that time if it doesn't get charged, it affects the available balance of your credit card and not your real balance.
Within the NeuClear Ledger API any transaction can have an expiry time. This Holds the Transaction amount from the Transaction time to the Expiry time. This never affects the real balance but does affect the Available Balance of the debit books. Important! It never affects the balance or available balance of the credit side.
Calendar cal=Calendar.getInstance();
Date t1=cal.getTime();
cal.add(Calendar.DAY_OF_YEAR,1);
Date t2=cal.getTime(); // Tomorrow
Book plaza=controller.getBook("Plaza Hotel");
Book bob=controller.getBook("Bob");
// We are holding 200 from today to tomorrow
PostedTransaction held=controller.hold(bob,plaza,200,"Hold",t1,t2);
double available=controller.getAvailableBalance(bob);
// Lets complete it
PostedTransaction revised=controller.complete(held.getRequestId(),165.43,,"Thank you for your business");
// alternatively you could cancel it
controller.complete(held.getRequestId());