svn commit: r700863 - /ofbiz/trunk/framework/base/src/org/ofbiz/base/util/DateRange.java

[adrianc]

Author: adrianc
Date: Wed Oct  1 11:41:37 2008
New Revision: 700863

URL: http://svn.apache.org/viewvc?rev=700863&view=rev
Log:
DateRange JavaDocs and code cleanups.

Modified:
    ofbiz/trunk/framework/base/src/org/ofbiz/base/util/DateRange.java

Modified: ofbiz/trunk/framework/base/src/org/ofbiz/base/util/DateRange.java
URL: http://svn.apache.org/viewvc/ofbiz/trunk/framework/base/src/org/ofbiz/base/util/DateRange.java?rev=700863&r1=700862&r2=700863&view=diff
==============================================================================
--- ofbiz/trunk/framework/base/src/org/ofbiz/base/util/DateRange.java (original)
+++ ofbiz/trunk/framework/base/src/org/ofbiz/base/util/DateRange.java Wed Oct  1 11:41:37 2008
@@ -22,19 +22,24 @@
 import java.sql.Timestamp;
 import java.util.Date;
 
-/** An immutable range of dates.
- */
+/** An immutable range of dates. */
 @SuppressWarnings("serial")
 public class DateRange implements Serializable {
+    /** A <code>Date</code> instance initialized to the earliest possible date.*/
     public static final Date MIN_DATE = new Date(Long.MIN_VALUE);
+    /** A <code>Date</code> instance initialized to the latest possible date.*/
     public static final Date MAX_DATE = new Date(Long.MAX_VALUE);
+    /** A <code>DateRange</code> instance initialized to the widest possible range of dates.*/
     public static final DateRange FullRange = new DateRange();
 
     protected Date start = MIN_DATE;
     protected Date end = MAX_DATE;
-
     protected DateRange() {}
 
+    /**
+     * @param start If null, defaults to <a href="#MIN_DATE">MIN_DATE</a>
+     * @param end If null, defaults to <a href="#MAX_DATE">MAX_DATE</a>
+     */
     public DateRange(Date start, Date end) {
         if (start != null) {
             this.start = new Date(start.getTime());
@@ -44,6 +49,9 @@
         }
     }
 
+    /** Returns this range's duration as a millisecond value.
+     * @return Range duration in milliseconds
+     */
     public long durationInMillis() {
         if (this.end.after(this.start)) {
             return this.end.getTime() - this.start.getTime();
@@ -60,30 +68,52 @@
         return this.start + " - " + this.end;
     }
 
+    /** Returns the starting date of this range.
+     * @return Range starting date
+     */
     public Date start() {
         return (Date) this.start.clone();
     }
 
+    /** Returns the starting date of this range as a <code>Timestamp</code> instance.
+     * @return Range starting date <code>Timestamp</code>
+     */
     public Timestamp startStamp() {
         return new Timestamp(this.start.getTime());
     }
 
+    /** Returns the ending date of this range.
+     * @return Range ending date
+     */
     public Date end() {
         return (Date) this.end.clone();
     }
 
+    /** Returns the ending date of this range as a <code>Timestamp</code> instance.
+     * @return Range ending date <code>Timestamp</code>
+     */
     public Timestamp endStamp() {
         return new Timestamp(this.end.getTime());
     }
 
+    /** Returns <code>true</code> if the ending date is later than the starting date.
+     * @return <code>true</code> if the ending date is later than the starting date
+     */
     public boolean isAscending() {
         return this.end.after(this.start) && !this.end.equals(this.start);
     }
 
+    /** Returns <code>true</code> if the starting and ending dates are equal.
+     * @return <code>true</code> if the starting and ending dates are equal
+     */
     public boolean isPoint() {
         return this.end.equals(this.start);
     }
 
+    /** Returns <code>true</code> if <code>date</code> occurs within this range.
+     * @param date
+     * @return <code>true</code> if <code>date</code> occurs within this range
+     */
     public boolean includesDate(Date date) {
         date = downcastTimestamp(date);
         if (isPoint()) {
@@ -96,15 +126,25 @@
         }
     }
 
+    /** Returns <code>true</code> if this range occurs before <code>date</code>.
+     * @param date
+     * @return <code>true</code> if this range occurs before <code>date</code>
+     */
     public boolean before(Date date) {
         date = downcastTimestamp(date);
         if (isAscending() || isPoint()) {
-            return this.start.before(date);
-        } else {
             return this.end.before(date);
+        } else {
+            return this.start.before(date);
         }
     }
 
+    /** Returns <code>true</code> if the latest date in this range
+     * occurs before the earliest date in <code>range</code>.
+     * @param range
+     * @return <code>true</code> if the latest date in this range
+     * occurs before the earliest date in <code>range</code>
+     */
     public boolean before(DateRange range) {
         if (isAscending() || isPoint()) {
             if (range.isAscending()) {
@@ -121,6 +161,10 @@
         }
     }
 
+    /** Returns <code>true</code> if this range occurs after <code>date</code>.
+     * @param date
+     * @return <code>true</code> if this range occurs after <code>date</code>
+     */
     public boolean after(Date date) {
         date = downcastTimestamp(date);
         if (isAscending() || isPoint()) {
@@ -130,6 +174,12 @@
         }
     }
 
+    /** Returns <code>true</code> if the earliest date in this range
+     * occurs after the latest date in <code>range</code>.
+     * @param range
+     * @return <code>true</code> if the earliest date in this range
+     * occurs after the latest date in <code>range</code>
+     */
     public boolean after(DateRange range) {
         if (isAscending() || isPoint()) {
             if (range.isAscending()) {
@@ -146,36 +196,31 @@
         }
     }
 
-    public boolean intersectsRange(DateRange dateRange) {
-        return intersectsRange(dateRange.start, dateRange.end);
-    }
-
+    /** Returns <code>true</code> if <code>range</code> intersects this range.
+     * @param range
+     * @return <code>true</code> if <code>range</code> intersects this range
+     */
+    public boolean intersectsRange(DateRange range) {
+        if (isPoint() && range.isPoint() && this.start.equals(range.start)) {
+            return true;
+        }
+        return !before(range) && !after(range);
+    }
+
+    /** Returns <code>true</code> if <code>start</code> and <code>end</code>
+     * intersect this range.
+     * @param start If null, defaults to <a href="#MIN_DATE">MIN_DATE</a>
+     * @param end If null, defaults to <a href="#MAX_DATE">MAX_DATE</a>
+     * @return <code>true</code> if <code>start</code> and <code>end</code>
+     * intersect this range
+     */
     public boolean intersectsRange(Date start, Date end) {
-        if (start == null) {
-            throw new IllegalArgumentException("start argument cannot be null");
-        }
-        if (end == null) {
-            throw new IllegalArgumentException("end argument cannot be null");
-        }
-        start = downcastTimestamp(start);
-        end = downcastTimestamp(end);
-        if (isPoint()) {
-            return end.equals(start) && this.start.equals(start);
-        }
-        if (isAscending()) {
-            if (start.after(end)) {
-                return false;
-            }
-            return (this.end.equals(start) || start.before(this.end)) && (this.start.equals(end) || end.after(this.start));
-        } else {
-            if (end.after(start)) {
-                return false;
-            }
-            return (this.end.equals(start) || start.after(this.end)) && (this.start.equals(end) || end.before(this.start));
-        }
+        return intersectsRange(new DateRange(start, end));
     }
 
     protected Date downcastTimestamp(Date date) {
+        // Testing for equality between a Date instance and a Timestamp instance
+        // will always return false.
         if (date instanceof Timestamp) {
             date = new Date(date.getTime());
         }