com.miginfocom.util.dates
Interface MutableDateRange

All Superinterfaces:
java.lang.Comparable, DateRangeI, PropertyObservable, java.io.Serializable, TimeSpan
All Known Implementing Classes:
DateRange

public interface MutableDateRange
extends DateRangeI, PropertyObservable

Extends DateRangeI with methods to change the date range.

See Also:
DateRangeI

Field Summary
static int ALIGN_CENTER_DOWN
          Alignment to center, rounded down if exactly 0.5.
static NameValuePair ALIGN_CENTER_DOWN_NVP
           
static int ALIGN_CENTER_UP
          Alignment to center, rounded up if exactly 0.5.
static NameValuePair ALIGN_CENTER_UP_NVP
           
static int ALIGN_EARLIEST
          Aligns to the earliest of start and end or start if same.
static NameValuePair ALIGN_EARLIEST_NVP
           
static int ALIGN_END
          Aligns to end date, even if end date is before start date (I.e.
static NameValuePair ALIGN_END_NVP
           
static int ALIGN_LATEST
          Aligns to the latest of start and end or end if same.
static NameValuePair ALIGN_LATEST_NVP
           
static int ALIGN_START
          Aligns to start date, even if start date is after end date (I.e.
static NameValuePair ALIGN_START_NVP
           
static NameValuePair[] ALIGN_VNPS
          Name value pairs of all date ranges except DateRangeI.RANGE_TYPE_CUSTOM
static java.lang.String PROPERTY_NAME
          The name of the property that this date range will fire when changed.
 
Fields inherited from interface com.miginfocom.util.dates.DateRangeI
CUSTOM_NVP, DATE_RANGE_NAMES, DATE_RANGES, DATE_RANGES_CUSTOM, DATE_RANGES_FROM_DAY, DAY_NVP, HOUR_NVP, MINUTE_NVP, MONTH_NVP, RANGE_TYPE_CUSTOM, RANGE_TYPE_DAY, RANGE_TYPE_HOUR, RANGE_TYPE_MINUTE, RANGE_TYPE_MONTH, RANGE_TYPE_OFFSET, RANGE_TYPE_SECOND, RANGE_TYPE_WEEK, RANGE_TYPE_YEAR_MONTHS, RANGE_TYPE_YEAR_WEEKS, RANGE_TYPES_MILLIS, SECOND_NVP, WEEK_NVP, YEAR_MONTHS_NVP, YEAR_WEEKS_NVP
 
Method Summary
 MutableDateRange add(int field, long amount, boolean preserveLength, boolean lengthDSTSafe)
          Directly passed on to start and end Calendars without any intervention
 void add(int field, long delta, boolean start, boolean end, DateRangeRounder dateRangeRounder)
          Add/move the start and/or end time of this range.
 void addEnd(int field, long amount)
          Forwarded to Calendar.add(int, int) for the end date.
 void addMillis(long amount)
          Adds amount number of milliseconds to both start and end date.
 void addMillisDSTSafe(long amount)
          Adds amount number of milliseconds to both start and end date.
 MutableDateRange addRange(DateRangeI range)
          Adds range to this range.
 void addStart(int field, long amount)
          Forwarded to Calendar.add(int, int)
 void allowEvents()
          Decreases the postpone count and if it reaches 0 an event is fired automatically.
Throws an IllegalStateException if the postpone count is alread at 0 and the date range has actually changed.
 MutableDateRange cut(DateRangeI maxBounds)
          Cuts of the start and/or end dates to the start or end dates in maxBounds if maxBounds is "inside" or this date range.
Note that if maxBounds doesn't overlap this then the resulting range (this) will span no time and probably be unsorted.
 MutableDateRange expandRange(int field, int amount)
          Expands the range by adding and substracting the amount to field for end and start date, respectively.
 MutableDateRange move(int field, long amount, int boundaryType)
          Adds/moves the range by using a "middle point add and expand" algorithm.
 void postponeEvents()
          Increase the postpone count.
 void roll(int field, int amount)
          Directly passed on to start and end Calendars without any intervention
 MutableDateRange roundExpand(int boundaryType)
          Sets the start and end date to the first and last millisecond of a specific boundary by expanding the range.
 MutableDateRange roundReduce(int boundaryType)
          Sets the start and end date to the first and last millisecond of a specific boundary by reducing the range.
 MutableDateRange setDateFromRange(DateRangeI dateRange)
          Copies date (yeas, day of year) from dateRange's start and end date and sets in this's start and end date making the date of day match but not necessary the time.
 void setEndField(int field, int value)
          Forwarded to Calendar.set(int, int) for the end date.
 void setEndMillis(long millis, boolean isExcluding)
          Sets the milliseconds of the end date directly
 void setEndToBoundaryExpand(int boundaryType)
          Sets the end date/time to boundaryType by expanding it to that boundary.
 void setEndToBoundaryReduce(int boundaryType)
          Sets the end date/time to boundaryType by reducing it to that boundary.
 void setHasDate(boolean b)
          A simple settable property that does nothing for the contained values or calculations.
 void setHasTime(boolean b)
          A simple settable property that does nothing for the contained values or calculations.
 void setMillisSpanned(long millis, boolean dSTSafe, boolean excluding)
          Changes end date so the total duration becomes millis.
 MutableDateRange setSize(int boundaryType, int size, AtRefRangeNumber align)
          Resizes the range to a specified number of a certain type (e.g.
 MutableDateRange setSize(int boundaryType, int size, int alignment)
          Resizes the range to a specified number of a certain type (e.g.
 void setStartField(int field, int value)
          Forwarded to Calendar.set(int, int) for the start field
 void setStartMillis(long millis)
          Sets the milliseconds of the start date directly
 void setStartToBoundaryExpand(int boundaryType)
          Sets the start date/time to boundaryType by expanding it to that boundary.
 void setStartToBoundaryReduce(int boundaryType)
          Sets the start date/time to boundaryType by reducing it to that boundary.
 MutableDateRange setTimeFromRange(DateRangeI dateRange)
          Copies time (hour, min, sec, millis) from dateRange's start and end date and sets in this's start and end date making the time of day match but not necessary the date.
 MutableDateRange setToRange(DateRangeI dateRange)
          Sets this range to the same start and end date/time as dateRange.
 MutableDateRange sort()
          Sorts this range by swapping start and end date references if needed.
 MutableDateRange sort(boolean forward)
          Sorts or unsorts this range by swapping start and end date references if needed.
 MutableDateRange union(DateRangeI dateRange)
          Sets this range so that it's start date is the earliest of the two and the end date is the latest of the two.
 
Methods inherited from interface com.miginfocom.util.dates.DateRangeI
getDurationString, getEnd, getEnd, getEndField, getEndField, getEndInstant, getEndInstant, getEndMillis, getEndMillis, getEndTime, getEndTime, getHasDate, getHasTime, getImmutable, getLocale, getMiddle, getMiddleMillis, getMillisSpanned, getRangeType, getRelative, getRelativeMillis, getRelativeRange, getSize, getStart, getStartField, getStartInstant, getStartMillis, getStartTime, getSubDateList, getTimeZone, isContaining, isContaining, isContinuous, isInSame, isOverlapping, isOverlapping, isSorted, isSpanningTime, iterator, iterator, toString
 
Methods inherited from interface com.miginfocom.util.dates.TimeSpan
getDateRangeClone, getDateRangeForReading, getWritableDateRange
 
Methods inherited from interface java.lang.Comparable
compareTo
 
Methods inherited from interface com.miginfocom.util.PropertyObservable
addPropertyListener, addPropertyListener, isIgnorePropertyEvents, removePropertyListener, setIgnorePropertyEvents
 

Field Detail

ALIGN_CENTER_DOWN

static final int ALIGN_CENTER_DOWN
Alignment to center, rounded down if exactly 0.5.

See Also:
Constant Field Values

ALIGN_CENTER_UP

static final int ALIGN_CENTER_UP
Alignment to center, rounded up if exactly 0.5.

See Also:
Constant Field Values

ALIGN_START

static final int ALIGN_START
Aligns to start date, even if start date is after end date (I.e. unsorted)

See Also:
Constant Field Values

ALIGN_END

static final int ALIGN_END
Aligns to end date, even if end date is before start date (I.e. unsorted)

See Also:
Constant Field Values

ALIGN_EARLIEST

static final int ALIGN_EARLIEST
Aligns to the earliest of start and end or start if same.

See Also:
Constant Field Values

ALIGN_LATEST

static final int ALIGN_LATEST
Aligns to the latest of start and end or end if same.

See Also:
Constant Field Values

ALIGN_CENTER_DOWN_NVP

static final NameValuePair ALIGN_CENTER_DOWN_NVP

ALIGN_CENTER_UP_NVP

static final NameValuePair ALIGN_CENTER_UP_NVP

ALIGN_START_NVP

static final NameValuePair ALIGN_START_NVP

ALIGN_END_NVP

static final NameValuePair ALIGN_END_NVP

ALIGN_EARLIEST_NVP

static final NameValuePair ALIGN_EARLIEST_NVP

ALIGN_LATEST_NVP

static final NameValuePair ALIGN_LATEST_NVP

ALIGN_VNPS

static final NameValuePair[] ALIGN_VNPS
Name value pairs of all date ranges except DateRangeI.RANGE_TYPE_CUSTOM


PROPERTY_NAME

static final java.lang.String PROPERTY_NAME
The name of the property that this date range will fire when changed.

See Also:
Constant Field Values
Method Detail

setToRange

MutableDateRange setToRange(DateRangeI dateRange)
Sets this range to the same start and end date/time as dateRange. Will not copy time zone or locale! Will copy hasTime and hasDate.

dateRange will not be referenced in any way after this method, free to change.

Parameters:
dateRange - The range containing the date/time. Won't be change.
Returns:
this

setTimeFromRange

MutableDateRange setTimeFromRange(DateRangeI dateRange)
Copies time (hour, min, sec, millis) from dateRange's start and end date and sets in this's start and end date making the time of day match but not necessary the date.

Parameters:
dateRange - The range to copy the time of day from
Returns:
this.

setDateFromRange

MutableDateRange setDateFromRange(DateRangeI dateRange)
Copies date (yeas, day of year) from dateRange's start and end date and sets in this's start and end date making the date of day match but not necessary the time.

Parameters:
dateRange - The range to copy the time of day from
Returns:
this.

setMillisSpanned

void setMillisSpanned(long millis,
                      boolean dSTSafe,
                      boolean excluding)
Changes end date so the total duration becomes millis.

Parameters:
millis - The duration in milliseconds.
dSTSafe - If true transitions over a DST border will be compensated for the offset (clock will always move x millis). false is just set the millisecond different. false is as UTC-mode.
excluding - If true the setted value will have one millisecond added first. Depending on how the returned value should be used this might, or might not, be desirable.Basically setting to true will set one second spanned for 1000 millis and setting to false will need 999 to set one second spanned.

sort

MutableDateRange sort(boolean forward)
Sorts or unsorts this range by swapping start and end date references if needed. A sorted range is one that start <= end.

Parameters:
forward - If true the range will be sorted. If false the range will be "unsorted" so that the end date will change place, if necessary, so that the end date will be before the start date.
Returns:
this

sort

MutableDateRange sort()
Sorts this range by swapping start and end date references if needed. A sorted range is one that start <= end.

Exactly the same as .sort(true);.

Returns:
this

roundExpand

MutableDateRange roundExpand(int boundaryType)
Sets the start and end date to the first and last millisecond of a specific boundary by expanding the range. If the range isn't sorted (startDate > endDate) the boundaries are reversed. For instance endDate would be set to the FIRST millisecond of boundaryField if startDate %gt endDate.

Parameters:
boundaryType - Both dates will be changed to the start/end boundary indicated by 'boundaryType'. i.e. RANGE_TYPE_xxx
Returns:
this as a convenience

roundReduce

MutableDateRange roundReduce(int boundaryType)
Sets the start and end date to the first and last millisecond of a specific boundary by reducing the range. If the range isn't sorted (startDate > endDate) the boundaries are reversed. For instance endDate would be set to the FIRST millisecond of boundaryField if startDate %gt endDate.

Parameters:
boundaryType - Both dates will be changed to the start/end boundary indicated by 'boundaryType'. i.e. RANGE_TYPE_xxx
Returns:
this as a convenience

setStartToBoundaryExpand

void setStartToBoundaryExpand(int boundaryType)
Sets the start date/time to boundaryType by expanding it to that boundary. If sorted to the earlier edge of the boundary and vice versa.

Parameters:
boundaryType - The boundary type to round to. E.g. DateRangeI.DateRangeI.RANGE_TYPE_WEEK.

setStartToBoundaryReduce

void setStartToBoundaryReduce(int boundaryType)
Sets the start date/time to boundaryType by reducing it to that boundary. If sorted to the earlier edge of the boundary and vice versa.
Note that the date range might change sorting after this method, that means that start and end might "pass" eachother. Also note that if the start is alread at the first millisecond of indicated boundaryType noting will happen.

Parameters:
boundaryType - The boundary type to round to. E.g. DateRangeI.DateRangeI.RANGE_TYPE_WEEK.

setEndToBoundaryExpand

void setEndToBoundaryExpand(int boundaryType)
Sets the end date/time to boundaryType by expanding it to that boundary. If sorted to the later edge of the boundary and vice versa.

Parameters:
boundaryType - The boundary type to round to. E.g. DateRangeI.DateRangeI.RANGE_TYPE_HOUR.

setEndToBoundaryReduce

void setEndToBoundaryReduce(int boundaryType)
Sets the end date/time to boundaryType by reducing it to that boundary. If sorted to the later edge of the boundary and vice versa.
Note that the date range might change sorting after this method, that means that start and end might "pass" eachother. Also note that if the end is alread at the last millisecond of indicated boundaryType noting will happen.

Parameters:
boundaryType - The boundary type to round to. E.g. DateRangeI.DateRangeI.RANGE_TYPE_HOUR.

move

MutableDateRange move(int field,
                      long amount,
                      int boundaryType)
Adds/moves the range by using a "middle point add and expand" algorithm. This is what's happens:
1) The middle point between start and end dates are moved (added) by field/amount
2) A new DateRange is expanded around this new middle point to the specified boundary.
Not that the size might change and will always be ONE boundaryType!

Parameters:
field - See Calendar fields.
amount - The amount of 'field's to add.
boundaryType - Both dates will be changed to the start/end boundary indicated by 'boundaryType'. E.e. DateRangeI.RANGE_TYPE_WEEK.
Returns:
this
See Also:
roundExpand(int), DateRangeI.getMiddle()

add

MutableDateRange add(int field,
                     long amount,
                     boolean preserveLength,
                     boolean lengthDSTSafe)
Directly passed on to start and end Calendars without any intervention

Parameters:
field - Same as for Calendar.add(int, int)
amount - Same as for Calendar.add(int, int)
preserveLength - If true the the length (i.e. spanned DST-corrected millis) will be same as before the call. The length can change if some rounding occur, for instande in this case (2003-01-28 - 2003-02-01).add(Month, 1) the range will change to (2003-02-28 - 2003-03-01) which spannes two days instead of four. The end date/time is adjusted to get the correct length.
false will just add the same to both start and end date and length might change.
lengthDSTSafe - If true additions over a DST border will be compensated for the offset. false is just make sure the actual (UTC) length is the same.
Returns:
this
See Also:
Calendar.add(int, int)

addMillis

void addMillis(long amount)
Adds amount number of milliseconds to both start and end date. Separate from add(int field, int amount) since a long has to be used to hold the amount.
NOTE! this method does not compensate for jumps over Daylight Savings Time boundary. This means that one millisecond added may actually make the local time one hour less (minus one millisecond of course).

Parameters:
amount - The number of milliseconds to add. Can be negative.
See Also:
addMillisDSTSafe(long)

addMillisDSTSafe

void addMillisDSTSafe(long amount)
Adds amount number of milliseconds to both start and end date. Separate from add(int field, int amount) since a long has to be used to hold the amount.

Parameters:
amount - The number of milliseconds to add. Can be negative.
See Also:
DateUtil.addMillisDSTSafe(long, java.util.TimeZone, long)

roll

void roll(int field,
          int amount)
Directly passed on to start and end Calendars without any intervention

Parameters:
field - see Calendar
amount - see Calendar
See Also:
Calendar.roll(int, int)

expandRange

MutableDateRange expandRange(int field,
                             int amount)
Expands the range by adding and substracting the amount to field for end and start date, respectively.

Parameters:
field - The field, eq Calendar.WEEK_OF_YEAR, to expand the range with
amount - The number of 'field's that the range should be expanded with. negative values reduces the range.
Returns:
this

setSize

MutableDateRange setSize(int boundaryType,
                         int size,
                         int alignment)
Resizes the range to a specified number of a certain type (e.g. weeks). The range can be unsorted and it will be handeled correctly.

For instance a range can be set to span "five days", or "three hours". The alignment decides where to put the extra time or where to cut time from (start, end or both).

Parameters:
boundaryType - The unit that 'newSize' is specified in. Eg RANGE_TYPE_WEEK.
size - The size in 'rangeType' units that the range will be set to.
alignment - Specifies is extra time, or cut of time, will be taken/given from the start, end pr both. See the different alignment options, They are:
ALIGN_CENTER_DOWN, ALIGN_CENTER_UP, ALIGN_START, ALIGN_END, ALIGN_EARLIEST, ALIGN_LATEST.
Returns:
this For chaining.
See Also:
roundExpand(int)

setSize

MutableDateRange setSize(int boundaryType,
                         int size,
                         AtRefRangeNumber align)
Resizes the range to a specified number of a certain type (e.g. weeks).The range can be unsorted and it will be handeled correctly.

For instance a range can be set to span "four weeks", or "three days". The alignment decides where to put the extra time or where to cut time from (start, end or both).

Parameters:
boundaryType - The unit that 'newSize' is specified in. Eg RANGE_TYPE_WEEK.
size - The size in 'rangeType' units that the range will be set to.
align - Specifies how to align the new time range relative to the old one. If null the alignment will be centered.

The most usable types are probably:

  • AtStart Align it so that the start will be the specified amount of boundaryType from the old start. For instance two weeks, if boundaryType is DateRangeI.RANGE_TYPE_WEEK and the argument is new AtStart(2f).
  • AtEnd Align it so that the end will be the specified amount of boundaryType from the old end. Most logically a negative value will be used. E.g. new AtEnd(-1f).
  • AtFraction 0f will align starts, 0.5f will center and 1f will align ends. All values in between is also valid of course.
Returns:
this For chaining.

cut

MutableDateRange cut(DateRangeI maxBounds)
Cuts of the start and/or end dates to the start or end dates in maxBounds if maxBounds is "inside" or this date range.
Note that if maxBounds doesn't overlap this then the resulting range (this) will span no time and probably be unsorted.

Parameters:
maxBounds - The bounds which to cut with
Returns:
this
See Also:
DateRangeI.isSorted(), DateRangeI.isSpanningTime(), DateRangeI.isOverlapping(com.miginfocom.util.dates.DateRangeI)

add

void add(int field,
         long delta,
         boolean start,
         boolean end,
         DateRangeRounder dateRangeRounder)
Add/move the start and/or end time of this range.

Parameters:
field - see Calendar.add(int, int)
delta - see Calendar.add(int, int)
start - If true the start date will change.
end - If true the end date will change.
dateRangeRounder - The object responsible for snapping/rounding time/date. Can be null.

union

MutableDateRange union(DateRangeI dateRange)
Sets this range so that it's start date is the earliest of the two and the end date is the latest of the two. Do a union of the ranges.

Parameters:
dateRange - The range to expand with. Will not be changed. If null nothing will be changed.
Returns:
this.

addRange

MutableDateRange addRange(DateRangeI range)
Adds range to this range. The resulting range will be spanning the smallest date range that can contain both ranges. The difference from union(DateRangeI) is that this method can leave this range unsorted. The returned date range will be unsorted (unsorted == start > end) if range's middle point is before (in time) the this range's middle point. The sorting of either range or this is thus NOT taken into account.

Parameters:
range - The range to add. Not null.
Returns:
this For chaining.

setEndMillis

void setEndMillis(long millis,
                  boolean isExcluding)
Sets the milliseconds of the end date directly

Parameters:
millis - The milliseconds.
isExcluding - If field should be excluded form the range, set to true.

setStartMillis

void setStartMillis(long millis)
Sets the milliseconds of the start date directly

Parameters:
millis - The milliseconds.

setEndField

void setEndField(int field,
                 int value)
Forwarded to Calendar.set(int, int) for the end date.

Parameters:
field - The field
value - The value to set
See Also:
Calendar.set(int, int)

setStartField

void setStartField(int field,
                   int value)
Forwarded to Calendar.set(int, int) for the start field

Parameters:
field - The field
value - The value to set
See Also:
Calendar.set(int, int)

addEnd

void addEnd(int field,
            long amount)
Forwarded to Calendar.add(int, int) for the end date.

Parameters:
field - The field
amount - The value to set
See Also:
Calendar.add(int, int)

addStart

void addStart(int field,
              long amount)
Forwarded to Calendar.add(int, int)

Parameters:
field - The field
amount - The value to set
See Also:
Calendar.add(int, int)

setHasDate

void setHasDate(boolean b)
A simple settable property that does nothing for the contained values or calculations. It is just a "tag"-boolean that can be interpreted by users of this class. Will NOT fire a property change event.

Parameters:
b - If the range's date should be considered. Default is true.

setHasTime

void setHasTime(boolean b)
A simple settable property that does nothing for the contained values or calculations. It is just a "tag"-boolean that can be interpreted by users of this class. Will NOT fire a property change event.

Parameters:
b - If the range's date should be considered. Default is true.

postponeEvents

void postponeEvents()
Increase the postpone count. If postpone count > 1 (it will always be after a call to this method) events abount this date range changes will be postponed until the postpone count is down to 0 again. Can be used if multiple changes is to be made to the date range and only one property event should be fired when its all done.
It's important to always match incPostponeCount() with an decPostponeCount() for all possible paths or no events will be fired.
Throws an exception if the postpone count > 100 since that is probably due to a bug.

See Also:
allowEvents(), PropertyObservable.addPropertyListener(java.beans.PropertyChangeListener, boolean)

allowEvents

void allowEvents()
Decreases the postpone count and if it reaches 0 an event is fired automatically.
Throws an IllegalStateException if the postpone count is alread at 0 and the date range has actually changed.

See Also:
postponeEvents(), PropertyObservable.addPropertyListener(java.beans.PropertyChangeListener, boolean)


Copyright © 2009 MiG InfoCom AB. All Rights Reserved.