Thread: [Objectlabkit-svn] SF.net SVN: objectlabkit: [105] trunk/datecalc-common/src/main/java/net/ objectl

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Revision: 105
          http://svn.sourceforge.net/objectlabkit/?rev=105&view=rev
Author:   benoitx
Date:     2006-09-05 02:29:03 -0700 (Tue, 05 Sep 2006)

Log Message:
-----------
Better JavaDoc.

Modified Paths:
--------------
    trunk/datecalc-common/src/main/java/net/objectlab/kit/datecalc/common/DateCalculator.java
    trunk/datecalc-common/src/main/java/net/objectlab/kit/datecalc/common/IMMPeriod.java

Modified: trunk/datecalc-common/src/main/java/net/objectlab/kit/datecalc/common/DateCalculator.java
===================================================================

--- trunk/datecalc-common/src/main/java/net/objectlab/kit/datecalc/common/DateCalculator.java	2006-09-04 23:56:32 UTC (rev 104)
+++ trunk/datecalc-common/src/main/java/net/objectlab/kit/datecalc/common/DateCalculator.java	2006-09-05 09:29:03 UTC (rev 105)
@@ -21,10 +21,13 @@
 import java.util.Set;
 
 /**
- * A DateCalculator is a lightweight container with a reference(optional) to a
+ * A DateCalculator is a lightweight container with an optional reference to a
  * set of holidays, a WorkingWeek (Mon-Fri by default), a startDate and a
- * current date. The CurrentDate date is changed everytime that the addDays or
- * moveByBusinessDays methods are called.
+ * current business date. The Calculator also uses a HolidayHandler to determine what to
+ * do when the calculated current Business Date falls on a weekend or holiday (non-working day).
+ * The CurrentDate date is changed everytime that the moveByDays or moveByBusinessDays methods are called.
+ * 'E' will be parameterized to be a Date-like class, i.e. java.util.Date or java.util.Calendar (and LocalDate
+ * or YearMonthDay for Joda-time).
  * 
  * @author Benoit Xhenseval
  * @author $LastChangedBy$
@@ -33,48 +36,60 @@
 public interface DateCalculator<E> {
 
     /**
-     * @return Calendar name (Typically the name associated with the holiday
+     * This is typically the name of the associated set of holidays.
+     * @return calculator name (Typically the name associated with the holiday
      *         set).
      */
     String getName();
 
     /**
+     * Setting the start date also sets the current business date (and if this is a non-working day,
+     * the current business date will be moved to the next business day acording to the HolidayHandler
+     * algorithm given).
      * @param startDate
-     *            the reference date for this calendar, the current date is also
+     *            the reference date for this calculator, the current business date is also
      *            updated and may be moved if it falls on a non working day
      *            (holiday/weekend).
      */
     void setStartDate(final E startDate);
 
     /**
-     * @return startDate the reference date for this calendar.
+     * Gives the startDate of this calculator (immutable once set via setStartDate).
+     * @return startDate the reference date for this calculator.
      */
     E getStartDate();
 
     /**
-     * @param currentDate
-     *            held by the calendar.
+     * Gives the current business date held by the calculator.
+     * @return a date.
      */
     E getCurrentBusinessDate();
 
     /**
-     * is the given date on a weekend, according to the WorkingWeek
+     * Is the given date falling on a weekend, according to the WorkingWeek.
+     * @return true if the date falls on a weekend.
      */
     boolean isWeekend(final E date);
 
     /**
-     * is the given date a non working day, i.e. either a "weekend" or a
+     * Is the given date a non working day, i.e. either a "weekend" or a
      * holiday?
+     * @return true if the given date is non-working.
      */
     boolean isNonWorkingDay(final E date);
 
     /**
+     * Is the current business day a non-working day, this is useful if the
+     * calculator does not have any algorithm to change the date when it falls
+     * on a non-working day.  This method can then be used to show a warning to the
+     * user.
      * @return true if the current date is either a weekend or a holiday.
      */
     boolean isCurrentDateNonWorking();
 
     /**
-     * This is typically used at the construction of a DateCalculator.
+     * This is typically used at the construction of a DateCalculator to give
+     * a reference to a set of holidays.
      * 
      * @param holidays
      *            the holiday (if null, an empty set will be put in place)
@@ -82,61 +97,72 @@
     void setNonWorkingDays(final Set<E> holidays);
 
     /**
+     * Gives a immutable copy of the set of registered holidays.
      * @return an immutable copy of the holiday set.
      */
     Set<E> getNonWorkingDays();
 
     /**
-     * Allow user to define what their Working Week should be (default is
+     * Allows user to define what their Working Week should be (default is
      * Mon-Fri).
      * 
-     * @param week
+     * @param week an immutable definition of a week.
      */
     void setWorkingWeek(final WorkingWeek week);
 
     /**
-     * give a current business date which may be moved if it falls on a non
-     * working day.
+     * Gives a current business date, it may be moved acording to the HolidayHandler algorithm
+     * if it falls on a non-working day.
      * 
      * @param date
-     * @return new current date if moved.
+     * @return new current business date if moved.
      */
     E setCurrentBusinessDate(final E date);
 
     /**
+     * Gives the name of the holiday handler algorithm, see HolidayHandlerType for some standard values.
      * @return the holiday handler type, can be null
      */
     String getHolidayHandlerType();
 
     /**
-     * move the current date by the number of days and, if it falls on a weekend
-     * or holiday, move it according to the HolidayHandler given in this
+     * This changes the current business date held in the calculator, it moves the 
+     * new current business date by the number of days and, if it falls on a weekend
+     * or holiday, moves it further according to the HolidayHandler given in this
      * DateCalculator.
      * 
      * @param days
-     *            number of day
+     *            number of days (can be <0 or >0)
      * @return the businessCalendar (so one can do
      *         calendar.moveByDays(-2).getCurrentBusinessDate();)
      */
     DateCalculator<E> moveByDays(final int days);
 
     /**
-     * move the current date by a number of business days, this means that if a
-     * date is either a 'weekend' or holiday, it will be skipped acording to the
+     * This changes the current business date held in the calculator, it moves the 
+     * current date by a number of business days, this means that if a
+     * date is either a 'weekend' or holiday along the way, it will be skipped acording to the
      * holiday handler and not count towards the number of days to move.
      * 
-     * @param businessDays
+     * @param businessDays (can be <0 or >0)
      * @return the current businessCalendar (so one can do
      *         calendar.moveByBusinessDays(2).getCurrentBusinessDate();)
+     * @exception IllegalArgumentException if the HolidayHandlerType is (MODIFIED_PRECEEDING or BACKWARD) and businessDays > 0
+     *          or (MODIFIED_FOLLOWING or FORWARD) and businessDays < 0
      */
     DateCalculator<E> moveByBusinessDays(final int businessDays);
 
     /**
-     * By combining several calendars, we take into account several set of
-     * holidays.
+     * Allows DateCalculators to be combined into a new one, the startDate and
+     * currentBusinessDate will be the ones from the existing calendar (not the
+     * parameter one). The name will be combined name1+"/"+calendar.getName().
      * 
-     * @param calculator
-     * @return a new DateCalculator
+     * @param calendar,
+     *            return the same DateCalculator if calender is null or the
+     *            original calendar (but why would you want to do that?)
+     * @throws IllegalArgumentException
+     *             if both calendars have different types of HolidayHandlers or
+     *             WorkingWeek;
      */
     DateCalculator<E> combine(DateCalculator<E> calculator);
 
@@ -152,20 +178,23 @@
     DateCalculator<E> moveByTenor(final Tenor tenor);
 
     /**
+     * Checks if a given date is an official IMM Date (3rd Wednesdays of March/June/Sept/Dec.
      * @param date
      * @return true if that date is an IMM date.
      */
     boolean isIMMDate(E date);
 
     /**
-     * Even if the current date is an IMM date, it will return the next one.
+     * Starting from the current business date, it will return the next IMM Date, even if the 
+     * current business date is an IMM date (same as calling getNextIMMDate(IMMPeriod.QUARTERLY)).
      * 
-     * @return the next IMMDate based on current date.
+     * @return the next IMMDate based on current business date.
      */
     E getNextIMMDate();
 
     /**
-     * Even if the current date is an IMM date, it will return the next one.
+     * Starting from the current business date, it will return the next IMM Date based on the IMMPeriod,
+     * even if the current business date is an IMM date.
      * 
      * @param period
      *            specify when the "next" IMM is, if quarterly then it is the
@@ -175,14 +204,16 @@
     E getNextIMMDate(IMMPeriod period);
 
     /**
-     * Even if the current date is an IMM date, it will return the previous one.
+     * Starting from the current business date, it will return the previous IMM Date, even if the 
+     * current business date is an IMM date.
      * 
      * @return the previous IMMDate based on current date.
      */
     E getPreviousIMMDate();
 
     /**
-     * Even if the current date is an IMM date, it will return the previous one.
+     * Starting from the current business date, it will return the previous IMM Date based on the IMMPeriod,
+     * even if the current business date is an IMM date.
      * 
      * @param period
      *            specify when the "previous" IMM is, if quarterly then it is
@@ -194,7 +225,7 @@
     /**
      * Returns a list of IMM dates between 2 dates, it will exclude the start
      * date if it is an IMM date but would include the end date if it is an IMM
-     * (same as IMMPeriod.QUARTERLY).
+     * (same as as calling getIMMDates(start,end,IMMPeriod.QUARTERLY)).
      * 
      * @param start
      *            start of the interval, excluded

Modified: trunk/datecalc-common/src/main/java/net/objectlab/kit/datecalc/common/IMMPeriod.java
===================================================================
--- trunk/datecalc-common/src/main/java/net/objectlab/kit/datecalc/common/IMMPeriod.java	2006-09-04 23:56:32 UTC (rev 104)
+++ trunk/datecalc-common/src/main/java/net/objectlab/kit/datecalc/common/IMMPeriod.java	2006-09-05 09:29:03 UTC (rev 105)
@@ -28,7 +28,7 @@
 public enum IMMPeriod {
     /** Bi annually March and September */
     BI_ANNUALY_MAR_SEP,
-    /** Bi annually March and September */
+    /** Bi annually June and December */
     BI_ANNUALY_JUN_DEC,
     /** Quarterly: eg March, June, September, December */
     QUARTERLY    


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.




Thread: [Objectlabkit-svn] SF.net SVN: objectlabkit: [105] trunk/datecalc-common/src/main/java/net/ objectl

We MOVED to GITHUB!

objectlabkit-svn