bb.util
Class DateConstraint

java.lang.Object
  extended by bb.util.DateConstraint

public class DateConstraint
extends Object

Stores information which defines date constraints, and offers the accepts method to test a given Date.

Supports these types of constraints:

  1. absolute date bounds (dateMin and dateMax)
  2. day of week bounds (dayOfWeekMin and dayOfWeekMax)
  3. time of day bounds (timeOfDayMin and timeOfDayMax)
All these bounds are always inclusive, as explained further in accepts.

Examples of how to construct DateConstraint instances:

  1. accepts every Date: new DateConstraint(null, null, -1, -1, -1, -1)
  2. accepts every weekday whose time of day is 9:30 am thru 4 pm: new DateConstraint(null, null, Calendar.MONDAY, Calendar.FRIDAY, 9*TimeLength.hour + 30*TimeLength.minute, 16*TimeLength.hour)

This class is multithread safe: it is immutable. In particular, it is always properly constructed, all of its fields are final, and none of their state can be changed after construction. See p. 53 of Java Concurrency In Practice for more discussion.

Author:
Brent Boyer

Nested Class Summary
static class DateConstraint.UnitTest
          See the Overview page of the project's javadocs for a general description of this unit test class.
 
Field Summary
private  Date2 dateMax
          Specifies the maximum Date value.
private  Date2 dateMin
          Specifies the minimum Date value.
private  int dayOfWeekMax
          Specifies the maximum day of week value.
private  int dayOfWeekMin
          Specifies the minimum day of week value.
private  long timeOfDayMax
          Specifies the maximum time of day value (where the time is measured in milliseconds).
private  long timeOfDayMin
          Specifies the minimum time of day value (where the time is measured in milliseconds).
 
Constructor Summary
DateConstraint(Date dateMin, Date dateMax, int dayOfWeekMin, int dayOfWeekMax, long timeOfDayMin, long timeOfDayMax)
          Constructor.
 
Method Summary
 boolean accepts(Date date)
          Returns true if date passes all of the constraints specified by this instance, false otherwise.
private  boolean equalDates(Date date1, Date date2)
           
 boolean equals(Object obj)
          Immediately returns true if this == obj, or false if obj == null or !
 Date2 getDateMax()
          Returns the dateMax field.
 Date2 getDateMin()
          Returns the dateMin field.
 int getDayOfWeekMax()
          Returns the dayOfWeekMax field.
 int getDayOfWeekMin()
          Returns the dayOfWeekMin field.
 long getTimeOfDayMax()
          Returns the timeOfDayMax field.
 long getTimeOfDayMin()
          Returns the timeOfDayMin field.
 int hashCode()
          Returns a value based on all of the fields.
 String toString()
          Returns toString(", ").
 String toString(String separator)
          Returns a String representation of this instance.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

dateMin

private final Date2 dateMin
Specifies the minimum Date value. If equals null, then there is no Date lower bound. Is a Date2 instance for that class's partial immutability (e.g. so this field's accessor need not return a copy).

Contract: may be null. Otherwise, must occur on or before dateMax if dateMax is also non-null.


dateMax

private final Date2 dateMax
Specifies the maximum Date value. If equals null, then there is no Date upper bound. Is a Date2 instance for that class's partial immutability (e.g. so this field's accessor need not return a copy).

Contract: may be null. Otherwise, must occur on or after dateMin if dateMin is also non-null.


dayOfWeekMin

private final int dayOfWeekMin
Specifies the minimum day of week value. If equals -1, then there is no day of week lower bound.

Contract: may be -1. Otherwise, must (i) be in the range [Calendar.SUNDAY, Calendar.SATURDAY] = [1, 7] and (ii) must be <= dayOfWeekMax if dayOfWeekMax is also != -1.


dayOfWeekMax

private final int dayOfWeekMax
Specifies the maximum day of week value. If equals -1, then there is no day of week upper bound.

Contract: may be -1. Otherwise, must (i) be in the range [Calendar.SUNDAY, Calendar.SATURDAY] = [1, 7] and (ii) must be >= dayOfWeekMin if dayOfWeekMin is also != -1.


timeOfDayMin

private final long timeOfDayMin
Specifies the minimum time of day value (where the time is measured in milliseconds). If equals -1, then there is no time of day lower bound.

Contract: may be -1. Otherwise, must (i) be in the range [0, TimeLength.dayMax] and (ii) must be <= timeOfDayMax if timeOfDayMax is also != -1.


timeOfDayMax

private final long timeOfDayMax
Specifies the maximum time of day value (where the time is measured in milliseconds). If equals -1, then there is no time of day upper bound.

Contract: may be -1. Otherwise, must (i) be in the range [0, TimeLength.dayMax] and (ii) must be >= timeOfDayMin if timeOfDayMin is also != -1.

Constructor Detail

DateConstraint

public DateConstraint(Date dateMin,
                      Date dateMax,
                      int dayOfWeekMin,
                      int dayOfWeekMax,
                      long timeOfDayMin,
                      long timeOfDayMax)
               throws IllegalArgumentException
Constructor.

Throws:
IllegalArgumentException - if any of the params violate the corresponding field's contract
Method Detail

getDateMin

public Date2 getDateMin()
Returns the dateMin field.


getDateMax

public Date2 getDateMax()
Returns the dateMax field.


getDayOfWeekMin

public int getDayOfWeekMin()
Returns the dayOfWeekMin field.


getDayOfWeekMax

public int getDayOfWeekMax()
Returns the dayOfWeekMax field.


getTimeOfDayMin

public long getTimeOfDayMin()
Returns the timeOfDayMin field.


getTimeOfDayMax

public long getTimeOfDayMax()
Returns the timeOfDayMax field.


accepts

public boolean accepts(Date date)
                throws IllegalArgumentException
Returns true if date passes all of the constraints specified by this instance, false otherwise.

The tests are:

  1. if dateMin != null, then returns false if date.getTime() < dateMin.getTime()
  2. if dateMax != null, then returns false if date.getTime() > dateMax.getTime()
  3. if dayOfWeekMin != -1, then returns false if date's dayOfWeek < dayOfWeekMin
  4. if dayOfWeekMax != -1, then returns false if date's dayOfWeek > dayOfWeekMax
  5. if timeOfDayMin != -1, then returns false if date's timeOfDay < timeOfDayMin
  6. if timeOfDayMax != -1, then returns false if date's timeOfDay > timeOfDayMax
This method only returns true if all of these tests are passed.

Note that the logic above means that all of the bounds (both min and max) act as inclusive bounds (i.e. let f be some field of date; then f is accepted if min <= f <= max, so that the acceptance range is the closed interval [min, max]).

Throws:
IllegalArgumentException - if date == null

equals

public boolean equals(Object obj)
Immediately returns true if this == obj, or false if obj == null or !this.getClass().equals( obj.getClass() ). Otherwise, determines equality based on whether or not obj (which now must be a DateConstraint instance) has every field equals to that of this instance.

The class equals criteria mentioned above is required because there exist subclasses of this class which contain new "aspects" (state that affects equality), so these subclasses must override this method. For more discussion, see the essay stored in the file equalsImplementation.txt

Overrides:
equals in class Object

equalDates

private boolean equalDates(Date date1,
                           Date date2)

hashCode

public final int hashCode()
Returns a value based on all of the fields.

Overrides:
hashCode in class Object

toString

public String toString()
Returns toString(", ").

Overrides:
toString in class Object

toString

public String toString(String separator)
                throws IllegalArgumentException
Returns a String representation of this instance. Each field is labeled, and separator appears between each field.

Throws:
IllegalArgumentException - if separator == null