TVM 1.2.2 Java Bean
Introduction
Time Value of Money (TVM) is an important concept in financial management. It can be used to compare investment alternatives and to solve a wide variety of financial calculations involving loans, mortgages, leases, savings, and annuities. (more...)
TVM Bean Features
CedarSpring.TVM is a non-visual (no graphical user interface) java bean that closely emulates the Time Value of Money functions of the Texas Instruments BAII Plus and Hewlett Packard 10B financial calculators. The bean can be used either on a client or a server so that you can choose the environment best suited for your application.The bean is offered as a educational tool to help illustrate the basic concepts of reusable software components and Time Value of Money. It should not be used for financial decisions or in any situation that might result in a financial loss without additional testing and modification to insure that it is accurate and suitable for your application.
You can:
- set any four of these values and then compute the fifth:
- control these options:
- scale and rounding for computed values
- payments per year
- compounding per year
- payments at beginning or end of period
- convert the annual interest rate to an equivalent effective rate
- create a loan amortization schedule
The bean is easy to use and customize:
- all calculations are performed with decimal arithmetic, not floating point
- very large or small numbers can be accommodated
- all public read/write properties can be bound
- error messages can be localized or specialized
- errors are reported as events for easy wiring
- interest rate can be entered as decimal or percent (selectable)
- compounding and payment periods do not have to coincide
- uses JDK 1.1 classes for greater browser compatibility
Properties
These are independent properties that you can set and retrieve in any order:| Property | Type | Read | Write | Bound | Default |
|---|---|---|---|---|---|
| compoundingPerYear | int | x | x | x | 12 |
| futureValue | BigDecimal | x | x | x | 0.0 |
| interestRate | BigDecimal | x | x | x | 0.0 |
| message | String | x | x | ||
| numberOfPeriods | BigDecimal | x | x | x | 0 |
| payAtEnd | boolean | x | x | x | true |
| payment | BigDecimal | x | x | x | 0.0 |
| paymentsPerYear | int | x | x | x | 12 |
| presentValue | BigDecimal | x | x | x | 0.0 |
| rateEstimate | BigDecimal | x | x | x | 10.0 |
| roundUp | boolean | x | x | x | true |
| scale | int | x | x | x | 4 |
These are properties that derive their value from other properties or affect other properties. They are marked as "Expert" since the order in which you set or retrieve them is important.
| Property | Type | Read | Write | Bound | Default | Affects | Uses |
|---|---|---|---|---|---|---|---|
| AmortizationSchedule | Amortization Schedule |
x | compoundingPerYear, interestRate, numberOfPeriods, payAtEnd, payment, paymentsPerYear, presentValue |
||||
| effectiveRate | BigDecimal | x | compoundingPerYear, interestRate, paymentsPerYear |
||||
| enterRateAsPercent | boolean | x | x | x | true | interestRate | |
| years | BigDecimal | x | x | numberOfPeriods / paymentsPerYear | numberOfPeriods | numberOfPeriods |
Methods
In additions to the get and set methods for each property listed in the properties table, there are five compute methods, three control methods, and four event registration methods. You can find more information about each method in the API.Compute Methods
These methods will compute a new property value after the other four values have been set:| Method | Params | Returns |
|---|---|---|
| computeInterestRate() | none | void |
| computePayment() | none | void |
| computePresentValue() | none | void |
| computeFutureValue() | none | void |
| computeNumberOfPeriods() | none | void |
Control Methods
These methods will set a group of properties to their default state:| Method | Params | Returns |
|---|---|---|
| clear() | none | void |
| clearMessage() | none | void |
| reset() | none | void |
Event Registration Methods
These methods will register an object to receive Error and Property Change Events:| Method | Params | Returns |
|---|---|---|
| addErrorListener() | none | Listener |
| removeErrorListener | none | Listener |
| addPropertyChangeListener | none | Listener |
| removePropertyChangeListener | none | Listener |
Events
PropertyChangeEvents
All read/write properties are bound.- A setter method will fire a PropertyChangeEvent when it
completes successfully and the new value is different from
the old one. If an error occurs, it will fire an ErrorEvent
and will also set the
messageproperty.
- A computeProperty method will fire a PropertyChangeEvent when it
completes successfully even when the new and old values
are equal. The
oldValueproperty in the PropertyChangeEvent is always set tonull. If an error occurs, it will fire an ErrorEvent and will also set themessageproperty.
- The clear and reset methods will fire a complete list of all
properties set (cleared), even when the old value and the
default value are equal. The
oldValuein the PropertyChangeEvent is always set tonull.
ErrorEvents
Methods do not throw Exceptions when an error or warning occurs. Instead, a method will fire an ErrorEvent and set themessage property. The state (except for
message) does not change when an error occurs. Events are
used instead of exceptions to make visual wiring easier. Refer to IBM´s tutorials:
"Visual programming tutorial - Visual debugging and error handling" and
"Designing beans for visual programming - Handling errors".
The two read-only properties (effectiveRate and AmortizationSchedule) can fire error events since they compute the values only when requested. When an error occurs, an event is fired. The getEffectiveRate method will return 0. The getAmortizationSchedule method will return an empty schedule.
The messages in the Error Events can be customized to fit the jargon of a particular industry or localized for a particular language and country (locale). Since the text of the message may change, you should always use the code (which remains constant) to determine which error occurred. Error W01 is not used in this version.
| Code | Message | Severity |
|---|---|---|
| 01 | Arithmetic error | error |
| 02 | Invalid argument | error |
| 03 | Number of Periods must be a whole number | error |
| 04 | Value out of range | error |
| 05 | No solution exists | error |
| 06 | Range is 0 - 1200 for number of periods | error |
| 07 | Iteration limit exceeded | error |
| 08 | Scale cannot be negative | error |
| 09 | Range is 0 - 999% for interest rate per year | error |
| 10 | No solution found | error |
| 11 | Number of Periods is 0 | error |
| 12 | Range is 0 - 365 for payments per year | error |
| 13 | Range is 0 - 365 for compounding periods per year | error |
| 14 | Effective Rate must be > 0 | error |
| W01 | Number of Periods was rounded to a whole number | warning |
Sign Conventions
The signs for present value, future value, and payment follow the cash flow convention where money that you invest (money flowing out) is negative and money that you receive is positive. For example, you apply for a $100,000 mortgage and agree to monthly payments with a final (balloon) payment of $50,000 at the end of 15 years. You must enter the present value as 100,000 since you receive that amount from the mortgage company. You must enter -50,000 into future value since you will pay out that amount as a lump-sum at the end of the loan. When you calculate the monthly payment, it will be a negative amount since it is money flowing out each month. There must be at least one positive and one negative cash flow in each financial transaction.
See the JavaDocs for more detail about the bean interface, and concepts for more information about time value of money.