com.cedarspring.tvm
Class TVMu

java.lang.Object
  |
  +--com.cedarspring.tvm.TVMu
All Implemented Interfaces:
java.io.Serializable

public class TVMu
extends java.lang.Object
implements java.io.Serializable

GetObjects.TVM is a non-visual 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 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:

Benefits:

Requirements:

PropertyChangeEvents
All read/write properties are bound. ErrorEvent
Methods do not throw Exceptions when an error or warning occurs. Instead, a method will fire and errorEvent and set the message property. The state (except for message) is not changed when an error occurs.

The two read-only properties (effectiveRate and AmortizationSchedule) can also 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.

Firing an error event rather than throwing an exception makes the bean easier to wire in visual development tools, and allows additional info to be reported in the event.

Version:
1.2.2-u December-2003
Author:
Cedar Spring Software, Inc.
See Also:
Serialized Form

Field Summary
private  java.beans.PropertyChangeSupport change
          Reference to the PropertChangeSupport object.
static java.lang.String COMPOUNDING_PER_YEAR
          Property name "compoundingPerYear"
static java.lang.String ENTER_RATE_AS_PERCENT
          Property name "enterRateAsPercent"
private  ErrorSupport error
          Reference to the ErrorSupport object.
static java.lang.String FUTURE_VALUE
          Property name "futureValue"
private  FutureValue fv
          Reference to the FutureValue object.
static java.lang.String INTEREST_RATE
          Property name "interestRate"
private  InterestRate iy
          Reference to the InterestRate object.
static java.lang.String MESSAGE
          Property name "message"
private  NumberOfPeriods n
          Reference to the NumberOfPeriods object.
static java.lang.String NUMBER_OF_PERIODS
          Property name "numberOfPeriods"
private  Options opt
          Reference to the Options object.
static java.lang.String PAY_AT_END
          Property name "payAtEnd"
static java.lang.String PAYMENT
          Property name "payment"
static java.lang.String PAYMENTS_PER_YEAR
          Property name "paymentsPerYear"
private  Payment pmt
          Reference to the Payment object.
static java.lang.String PRESENT_VALUE
          Property name "presentValue"
private  PresentValue pv
          Reference to the PresentValue object
static java.lang.String RATE_ESTIMATE
          Property name "rateEstimate"
static java.lang.String ROUNDUP
          Property name "roundUp"
static java.lang.String SCALE
          Property name "scale"
(package private) static long serialVersionUID
           
 
Constructor Summary
TVMu()
          Create a new TVM object with default state.
 
Method Summary
 void addErrorListener(ErrorListener listener)
          Adds an ErrorListener to the listener list.
 void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
          Adds a PropertyChangeListener to the listener list.
 void clear()
          Clears the TVM fields and error message.
 void clearMessage()
          Clears the last message (error, warning, or information) that was delivered by any ErrorEvent.
 void computeFutureValue()
          Computes the future value and sets the futureValue property.
 void computeInterestRate()
          Computes an approximation of the annual interest rate and sets the interestRate property.
 void computeNumberOfPeriods()
          Computes number of periods and sets the numberOfPeriods property.
 void computePayment()
          Computes the annuity payment per period and sets the payment property.
 void computePresentValue()
          Computes the present value and sets the presentValue property.
 AmortizationSchedule getAmortizationSchedule()
          Gets an Amortization Schedule that divides each payment into interest and principal, and shows the ending balance for the period.
 int getCompoundingPerYear()
          Gets compounding periods per year.
 java.math.BigDecimal getEffectiveRate()
          Gets an annual effective interest rate that is equivalent to the annual nominal rate.
 boolean getEnterRateAsPercent()
          Gets interest rate representation (decimal or percent)
 java.math.BigDecimal getFutureValue()
          Gets future value.
 java.math.BigDecimal getInterestRate()
          Gets annual nominal interest rate.
 java.util.Locale getLocale()
          Gets the locale.
 java.lang.String getMessage()
          Gets the last message (error, warning, or information) that was delivered by any ErrorEvent.
 java.math.BigDecimal getNumberOfPeriods()
          Gets number of periods.
 java.math.BigDecimal getPayment()
          Gets annuity payment.
 int getPaymentsPerYear()
          Gets payments per year.
 java.math.BigDecimal getPresentValue()
          Gets Present Value.
 java.math.BigDecimal getRateEstimate()
          Gets interest rate estimate.
 boolean getRoundUp()
          Gets rounding mode.
 int getScale()
          Gets scale.
 java.math.BigDecimal getYears()
          Gets the virtual property years.
 boolean isPayAtEnd()
          Gets payAtEnd which indicates if payments are made at the beginning or end of each period.
 void removeErrorListener(ErrorListener listener)
          Removes an ErrorListener from the listener list.
 void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
          Removes a PropertyChangeListener from the listener list.
private  void reportError(java.lang.String errorNumber)
           
 void reset()
          Resets the Calculator to defaults.
 void setCompoundingPerYear(int compoundingPerYear)
          Sets compounding periods per year.
 void setEnterRateAsPercent(boolean enterRateAsPercent)
          Sets interest rate representation (decimal or percent).
 void setFutureValue(java.math.BigDecimal futureValue)
          Sets future value.
 void setInterestRate(java.math.BigDecimal interestRate)
          Sets annual nominal interest rate.
 void setLocale(java.util.Locale locale)
          Sets the Locale.
 void setNumberOfPeriods(java.math.BigDecimal numberOfPeriods)
          Sets number of periods.
 void setPayAtEnd(boolean payAtEnd)
          Sets payment at beginning or end of period mode.
 void setPayment(java.math.BigDecimal payment)
          Sets annuity payment.
 void setPaymentsPerYear(int paymentsPerYear)
          Sets payments per year.
 void setPresentValue(java.math.BigDecimal presentValue)
          Sets present value.
 void setRateEstimate(java.math.BigDecimal rateEstimate)
          Sets interest rate estimate.
 void setRoundUp(boolean roundUp)
          Sets Rounding mode.
 void setScale(int scale)
          Sets scale.
 void setYears(java.math.BigDecimal years)
          Sets the virtual property years.
 java.lang.String toString()
          Gets a string containing values of TVM properties.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

PRESENT_VALUE

public static final java.lang.String PRESENT_VALUE
Property name "presentValue"

See Also:
Constant Field Values

FUTURE_VALUE

public static final java.lang.String FUTURE_VALUE
Property name "futureValue"

See Also:
Constant Field Values

PAYMENT

public static final java.lang.String PAYMENT
Property name "payment"

See Also:
Constant Field Values

INTEREST_RATE

public static final java.lang.String INTEREST_RATE
Property name "interestRate"

See Also:
Constant Field Values

NUMBER_OF_PERIODS

public static final java.lang.String NUMBER_OF_PERIODS
Property name "numberOfPeriods"

See Also:
Constant Field Values

SCALE

public static final java.lang.String SCALE
Property name "scale"

See Also:
Constant Field Values

ROUNDUP

public static final java.lang.String ROUNDUP
Property name "roundUp"

See Also:
Constant Field Values

PAYMENTS_PER_YEAR

public static final java.lang.String PAYMENTS_PER_YEAR
Property name "paymentsPerYear"

See Also:
Constant Field Values

PAY_AT_END

public static final java.lang.String PAY_AT_END
Property name "payAtEnd"

See Also:
Constant Field Values

COMPOUNDING_PER_YEAR

public static final java.lang.String COMPOUNDING_PER_YEAR
Property name "compoundingPerYear"

See Also:
Constant Field Values

RATE_ESTIMATE

public static final java.lang.String RATE_ESTIMATE
Property name "rateEstimate"

See Also:
Constant Field Values

ENTER_RATE_AS_PERCENT

public static final java.lang.String ENTER_RATE_AS_PERCENT
Property name "enterRateAsPercent"

See Also:
Constant Field Values

MESSAGE

public static final java.lang.String MESSAGE
Property name "message"

See Also:
Constant Field Values

pv

private PresentValue pv
Reference to the PresentValue object


fv

private FutureValue fv
Reference to the FutureValue object.


pmt

private Payment pmt
Reference to the Payment object.


iy

private InterestRate iy
Reference to the InterestRate object.


n

private NumberOfPeriods n
Reference to the NumberOfPeriods object.


opt

private Options opt
Reference to the Options object.


error

private ErrorSupport error
Reference to the ErrorSupport object.


change

private java.beans.PropertyChangeSupport change
Reference to the PropertChangeSupport object.


serialVersionUID

static final long serialVersionUID
See Also:
Constant Field Values
Constructor Detail

TVMu

public TVMu()
Create a new TVM object with default state. Initial state is set to default values by the reset method.

See Also:
reset()
Method Detail

setPresentValue

public void setPresentValue(java.math.BigDecimal presentValue)
Sets present value.

Events:

Parameters:
presentValue - Money that you have now, or the value of a promised future amount of money or series of payments that have been discounted to an equivalent value today. Money paid out is negative.

getPresentValue

public java.math.BigDecimal getPresentValue()
Gets Present Value.

Returns:
presentValue

computePresentValue

public void computePresentValue()
Computes the present value and sets the presentValue property. The futureValue, payment, interestRate, and numberOfPeriods properties must be set before this method is invoked.

Events:

See Also:
setFutureValue(java.math.BigDecimal), setPayment(java.math.BigDecimal), setInterestRate(java.math.BigDecimal), setNumberOfPeriods(java.math.BigDecimal)

setFutureValue

public void setFutureValue(java.math.BigDecimal futureValue)
Sets future value.

Events:

Parameters:
futureValue - The amount of money that an investment will grow to at some future date, or the balance of a loan remaining after the last payment. Money paid out is negative.

getFutureValue

public java.math.BigDecimal getFutureValue()
Gets future value.

Returns:
futureValue

computeFutureValue

public void computeFutureValue()
Computes the future value and sets the futureValue property. The presentValue, payment, interestRate, and numberOfPeriods properties must be set before this method is invoked.

Events:

See Also:
setPresentValue(java.math.BigDecimal), setPayment(java.math.BigDecimal), setInterestRate(java.math.BigDecimal), setNumberOfPeriods(java.math.BigDecimal)

setPayment

public void setPayment(java.math.BigDecimal payment)
Sets annuity payment.

Events:

Parameters:
payment - Payments (or dividends) must be all inflows or all outflows, occur at evenly spaced intervals, and represent the payment during one compounding (or discount) period. Money paid out is negative.

getPayment

public java.math.BigDecimal getPayment()
Gets annuity payment.

Returns:
payment

computePayment

public void computePayment()
Computes the annuity payment per period and sets the payment property. The presentValue, futureValue, interestRate, and numberOfPeriods properties must be set before this method is invoked.

Events:

See Also:
setPresentValue(java.math.BigDecimal), setFutureValue(java.math.BigDecimal), setInterestRate(java.math.BigDecimal), setNumberOfPeriods(java.math.BigDecimal)

setInterestRate

public void setInterestRate(java.math.BigDecimal interestRate)
Sets annual nominal interest rate. A 6.5% rate is entered as percent (6.5) or decimal (.065) depending on value of enterRateAsPercent property. The periodic rate is calculated from this property, paymentsPerYear, and compoundingPerYear.

Events:

Parameters:
interestRate - annual interest rate. Range is 0-999%
See Also:
setEnterRateAsPercent(boolean), setCompoundingPerYear(int), setPaymentsPerYear(int)

getInterestRate

public java.math.BigDecimal getInterestRate()
Gets annual nominal interest rate. A 6.5% rate is returned as percent (6.5) or decimal (.065) depending on value of enterRateAsPercent property.

Returns:
nominal annual interest rate
See Also:
setEnterRateAsPercent(boolean)

computeInterestRate

public void computeInterestRate()
Computes an approximation of the annual interest rate and sets the interestRate property. The presentValue, futureValue, payment, and numberOfPeriods properties must be set before this method is invoked. If the method fails to converge on a rate, try different values for the rateEstimate property.

Events:

See Also:
setPresentValue(java.math.BigDecimal), setFutureValue(java.math.BigDecimal), setPayment(java.math.BigDecimal), setNumberOfPeriods(java.math.BigDecimal), setRateEstimate(java.math.BigDecimal)

setEnterRateAsPercent

public void setEnterRateAsPercent(boolean enterRateAsPercent)
Sets interest rate representation (decimal or percent).

Events:

Parameters:
enterRateAsPercent -
  • true: interestRate is stored and recalled as a percent. (6.5% is entered as 6.5)
  • false: interestRate is stored and recalled as a decimal. (6.5% is entered as .065)

getEnterRateAsPercent

public boolean getEnterRateAsPercent()
Gets interest rate representation (decimal or percent)

Returns:
enterRateAsPercent

setRateEstimate

public void setRateEstimate(java.math.BigDecimal rateEstimate)
Sets interest rate estimate.

Events:

Parameters:
rateEstimate - Your best estimate of the annual nominal interest rate. If the computeInterestRate method cannot converge on rate, try changing this property. The default value of 10% is reasonable for rates between 0 and 100%. The property can be set to any value, but it should be close to the range of interestRate (0-999%).
See Also:
computeInterestRate()

getRateEstimate

public java.math.BigDecimal getRateEstimate()
Gets interest rate estimate.

Returns:
rateEstimate

setPaymentsPerYear

public void setPaymentsPerYear(int paymentsPerYear)
Sets payments per year.

Events:

Parameters:
paymentsPerYear - The number of equally-spaced payments made per year. Used with compoundingPerYear to compute the interest rate per period.
See Also:
setCompoundingPerYear(int)

getPaymentsPerYear

public int getPaymentsPerYear()
Gets payments per year.

Returns:
paymentsPerYear

setCompoundingPerYear

public void setCompoundingPerYear(int compoundingPerYear)
Sets compounding periods per year.

Events:

Parameters:
compoundingPerYear - The number of compounding periods per year. Used with paymentsPerYear to compute the interest rate per period.
See Also:
setPaymentsPerYear(int)

getCompoundingPerYear

public int getCompoundingPerYear()
Gets compounding periods per year.

Returns:
compoundingPeriodsPerYear

getEffectiveRate

public java.math.BigDecimal getEffectiveRate()
Gets an annual effective interest rate that is equivalent to the annual nominal rate. This is a read-only property. A 6.5% rate is returned as percent (6.5) or decimal (.065) depending on value of enterRateAsPercent property.

Events:

Returns:
effective annual interest rate (0 if error occurs)
Since:
TVM 1.1.0
See Also:
setEnterRateAsPercent(boolean), setInterestRate(java.math.BigDecimal), setCompoundingPerYear(int)

setNumberOfPeriods

public void setNumberOfPeriods(java.math.BigDecimal numberOfPeriods)
Sets number of periods.

Events:

Parameters:
numberOfPeriods - Number of Periods.

getNumberOfPeriods

public java.math.BigDecimal getNumberOfPeriods()
Gets number of periods.

Returns:
numberOfPeriods

setYears

public void setYears(java.math.BigDecimal years)
Sets the virtual property years. This is a convenience method that converts years to numberOfPeriods:
  1. multiplies the years parameter by the current value of paymentsPerYear
  2. rounds to an integer according to the value of the roundUp property
  3. sets the result into the numberOfPeriods property
Note that all subsequent calculations are performed using the integer value of numberOfPeriods, not years.

Events:

Parameters:
years - years.
Since:
TVM 1.2.1
See Also:
setNumberOfPeriods(java.math.BigDecimal), setPaymentsPerYear(int), setRoundUp(boolean)

getYears

public java.math.BigDecimal getYears()
Gets the virtual property years. This is a convenience method that converts numberOfPeriods to years:
  1. divides the current value of numberOfPeriods by paymentsPerYear
  2. scales and rounds the result according to the scale and roundUp properties

Returns:
numberOfPeriods / paymentsPerYear
Since:
TVM 1.2.1
See Also:
setNumberOfPeriods(java.math.BigDecimal), setPaymentsPerYear(int), setRoundUp(boolean), setScale(int)

computeNumberOfPeriods

public void computeNumberOfPeriods()
Computes number of periods and sets the numberOfPeriods property. The presentValue, futureValue, interestRate, and payment properties must be set before this method is invoked. The result will always be rounded to the nearest whole number since the setNumberOfPeriods methods requires that.

Events:

See Also:
setPresentValue(java.math.BigDecimal), setFutureValue(java.math.BigDecimal), setPayment(java.math.BigDecimal), setInterestRate(java.math.BigDecimal)

setPayAtEnd

public void setPayAtEnd(boolean payAtEnd)
Sets payment at beginning or end of period mode.

Events:

Parameters:
payAtEnd -
  • true: Payments are made at the end of each period.
  • false: Payments are made at the beginning of each period.

isPayAtEnd

public boolean isPayAtEnd()
Gets payAtEnd which indicates if payments are made at the beginning or end of each period.

Returns:
payAtEnd

setScale

public void setScale(int scale)
Sets scale.

Events:

Parameters:
scale - number of digits to the right of the decimal place.

getScale

public int getScale()
Gets scale.

Returns:
scale

setRoundUp

public void setRoundUp(boolean roundUp)
Sets Rounding mode.

Events:

Parameters:
roundUp - Rounding applied to subsequent computations.
  • true: Round half up. If the lost fraction is < .5 the value is rounded away from 0, else it is rounded toward 0.
  • false: Round down. The lost fraction is dropped and does not affect the new tail digit.

getRoundUp

public boolean getRoundUp()
Gets rounding mode.

Returns:
roundUp

getAmortizationSchedule

public AmortizationSchedule getAmortizationSchedule()
Gets an Amortization Schedule that divides each payment into interest and principal, and shows the ending balance for the period. Typically, the computePayment method will be invoked just prior to invoking this method.

The amortization schedule is based on the current values of:

This is a read-only property. A new schedule is created each time the method is invoked.

Events:

Returns:
Amortization Schedule An empty schedule is returned when an error event occurs.
Since:
TVM 1.2.0
See Also:
setPresentValue(java.math.BigDecimal), setPayment(java.math.BigDecimal), computePayment(), setInterestRate(java.math.BigDecimal), setCompoundingPerYear(int), setNumberOfPeriods(java.math.BigDecimal), setPayAtEnd(boolean)

clear

public void clear()
Clears the TVM fields and error message. Sets presentValue, futureValue, payment, interestRate, and numberOfPeriod to 0. Clears error message. Other properties are not affected.

Events:


reset

public void reset()
Resets the Calculator to defaults.

Events:

See Also:
clear()

getMessage

public java.lang.String getMessage()
Gets the last message (error, warning, or information) that was delivered by any ErrorEvent. In purely visual IDE's that cannot handle events, this property could be bound to a text field as an easy way to display exceptions. Note that it is not cleared when methods complete successfully.


clearMessage

public void clearMessage()
Clears the last message (error, warning, or information) that was delivered by any ErrorEvent.


setLocale

public void setLocale(java.util.Locale locale)
Sets the Locale. The current default locale is used if no specific Locale is set.

Since:
TVM 1.1.0

getLocale

public java.util.Locale getLocale()
Gets the locale.

Since:
TVM 1.1.0

toString

public java.lang.String toString()
Gets a string containing values of TVM properties.

Overrides:
toString in class java.lang.Object

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
Adds a PropertyChangeListener to the listener list. You should not assume that the property change events will be delivered to the registered listeners in any particular order (such as FIFO, LIFO, etc).

Parameters:
listener - The PropertyChangeListener to be added

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
Removes a PropertyChangeListener from the listener list.

Parameters:
listener - The PropertyChangeListener to be removed

addErrorListener

public void addErrorListener(ErrorListener listener)
Adds an ErrorListener to the listener list. You should not assume that the error events will be delivered to the registered listeners in any particular order (such as FIFO, LIFO, etc).

Parameters:
listener - The ErrorListener to be added

removeErrorListener

public void removeErrorListener(ErrorListener listener)
Removes an ErrorListener from the listener list.

Parameters:
listener - The ErrorListener to be removed

reportError

private void reportError(java.lang.String errorNumber)