Home  |  Software Components  |  Examples  |  Books  
   TVM Component -> Documentation -> Features   

 TVM 1.2.2 Java Bean


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



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
x         compoundingPerYear,
effectiveRate BigDecimal x         compoundingPerYear,
enterRateAsPercent boolean x x x true interestRate  
years BigDecimal x x   numberOfPeriods / paymentsPerYear numberOfPeriods numberOfPeriods



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




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 message property.
  • A computeProperty method will fire a PropertyChangeEvent when it completes successfully even when the new and old values are equal. The oldValue property in the PropertyChangeEvent is always set to null. If an error occurs, it will fire an ErrorEvent and will also set the message property.
  • 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 oldValue in the PropertyChangeEvent is always set to null.


Methods do not throw Exceptions when an error or warning occurs. Instead, a method will fire an ErrorEvent and set the message 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 errorerror
02 Invalid argumenterror
03 Number of Periods must be a whole numbererror
04 Value out of rangeerror
05 No solution existserror
06 Range is 0 - 1200 for number of periodserror
07 Iteration limit exceedederror
08 Scale cannot be negativeerror
09 Range is 0 - 999% for interest rate per yearerror
10 No solution founderror
11 Number of Periods is 0error
12 Range is 0 - 365 for payments per yearerror
13 Range is 0 - 365 for compounding periods per yearerror
14 Effective Rate must be > 0error
W01 Number of Periods was rounded to a whole numberwarning


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.

Copyright ©1998-2003 Cedar Spring Software, Inc.  All Rights Reserved
Privacy | Legal & Terms of Use | Trademarks | Feedback | About