com.standbysoft.component.date
Interface DateSelectionModel

All Known Implementing Classes:

AbstractDateSelectionModel

public interface DateSelectionModel

The date selection model defines basic operations needed by date components like JDatePicker to make valid date selections; it abstracts everything there is about date selection.

This model tries to be flexible enough to offer powerful date selection operations and this makes its interface rather big. Next, an overview of the problems it tries to solve is presented:

1. Selection type (single, interval, multiple)
2. Empty selection (null dates)
3. Date restriction
4. Date selection
5. Events listening

Before delving more into the API, here is a possible scenario that presents the methods it is most likely you will use.

1. Specify a selection type
2. Decide whether you need null dates
3. Register an event listener
4. Select one or more dates

Selection type (single, interval, multiple)

Whenever working with dates, users might need to select more that just one date. Perhaps they need to select a whole range of dates. To suit these needs, the date selection model can be configured for a specific type of selection.

• Single allows the selection of only one date at a time
• Single interval allows the selection of only one range of dates
• Multiple interval allows the selection of multiple date ranges

Use setSelectionMode(DateSelectionModel.SelectionMode) and getSelectionMode() methods in order to specify and determine the selection mode that is used. Note that if the model is set on single selection type, for instance, there is no chance you could select more than one date.

Empty selection (null dates)

Date selection means not only selecting one or more dates, but also selecting no date at all. By empty selection we mean no selected date. Empty selection is also known as null date selection.

So, if you need to allow empty selection (null dates), just use setEmptySelectionAllowed(boolean) and set it to true. To find out whether empty selection is allowed use isEmptySelectionAllowed().

To clear all the selected dates use removeAllDates() method.

Date restriction

Often the business logic imposes restrictions on the dates that can be selected by users. Possible solutions are to validate the selected dates against the list of selectable dates or to make it impossible in the first place for those dates to be selected. The date selection model helps you implement the second approach in a flexible manner.

Date selection restrictions may refer to one of:

• Selection type (see above)
• Empty selection (null dates) (see above)
• Semantically valid dates

By date restriction, we mean allowing only semantically valid dates to be selected. A possible client of this model can determine if a date can be selected or not by calling the isDateSelectable(Date) method.

Of course, various implementations of this interface may use whatever logic to determine which dates are selectable and which are not.

The model can also specify an interval of valid dates contained between getMinimumAllowed() and getMaximumAllowed().

Date selection

As its name says, this model is about date selection. This means that you can easily specify and determine which dates are selected. The basic operations are:

• Determine whether a date is selected or not,
• Determine which dates are selected,
• Specify some dates as selected,
• Remove all selected dates.

To control the selected dates, one can also use addDateSelectionInterval(Date, Date) and removeDateSelectionInterval(Date, Date).

The methods getAnchorSelectionDate(), setAnchorSelectionDate(Date), getLeadSelectionDate() and setLeadSelectionDate(Date) are intended to be used internally.

Events listening

Sometimes you might just want to check what happens with the selection model. Perhaps to see when the selected dates change.

For all these situations you must create a class that implements DateSelectionListener and then register it using addDateSelectionListener(DateSelectionListener) to receive notifications. Use removeDateSelectionListener(DateSelectionListener) to stop a listener receiving notifications.

Nested Class Summary

static class

DateSelectionModel.SelectionMode The type of selection for the selection model that allows to choose from single, interval or multiple interval selection.

Method Summary

void	addDateSelectionInterval(java.util.Date date1, java.util.Date date2) Change the selection to be the set union of the current date selection and the dates between date1 and date2 inclusive.
void	addDateSelectionListener(DateSelectionListener listener) Registers a new date selection listener to the model.
java.util.Date	getAnchorSelectionDate() Returns the anchor selection date.
java.util.Date	getLeadSelectionDate() Returns the lead selection date.
java.util.Date	getMaximumAllowed() Returns the maximum allowed date.
java.util.Date	getMinimumAllowed() Returns the minimum allowed date.
java.util.Date[]	getSelectedDates() Returns the selected dates.
DateSelectionModel.SelectionMode	getSelectionMode() Returns the selection mode used by this model.
java.util.TimeZone	getTimeZone() Returns the time zone used to calculate date interval dates.
boolean	isDateSelectable(java.util.Date date) Determines whether a specified date can be selected from this model or not.
boolean	isDateSelected(java.util.Date date) Determines whether a specified date has been selected.
boolean	isEmptySelectionAllowed() Determines whether empty selection is allowed.
void	removeAllDates() Removes all selected dates from this model.
void	removeDateSelectionInterval(java.util.Date date1, java.util.Date date2) Change the selection to be the set difference of the current selection and the dates between date1 and date2 inclusive.
void	removeDateSelectionListener(DateSelectionListener listener) Removes a specified date selection listener from this model.
void	setAnchorSelectionDate(java.util.Date date) Sets the anchor selection date.
void	setDateSelectionIterval(java.util.Date date1, java.util.Date date2) Changes the date selection interval to be between date1 and date2 inclusive.
void	setEmptySelectionAllowed(boolean allowed) Specifies whether the model supports empty date selections that is no date can be selected at one time.
void	setLeadSelectionDate(java.util.Date date) Sets the lead selection date.
void	setSelectedDates(java.util.Date[] dates) Specifies what dates are selected by this model.
void	setSelectionMode(DateSelectionModel.SelectionMode mode) Specifies a new selection mode to be used by this model.
void	setTimeZone(java.util.TimeZone timezone) Specifies the time zone used to properly calculate the dates of a date interval.

Method Detail

setTimeZone

public void setTimeZone(java.util.TimeZone timezone)

Specifies the time zone used to properly calculate the dates of a date interval. This property is used internally by the date components to synchronize their time zone with this model so that it can calculate proper dates when interval selections are made.

Parameters:

timezone - new time zone

getTimeZone

public java.util.TimeZone getTimeZone()

Returns the time zone used to calculate date interval dates.

Returns:

time zone used to calculate date interval dates

See Also:

setTimeZone(TimeZone)

setSelectionMode

public void setSelectionMode(DateSelectionModel.SelectionMode mode)

Specifies a new selection mode to be used by this model. The selection mode tells whether a single date, a date interval or multiple date intervals can be selected.

Parameters:

mode - selection mode to be used by this model

See Also:

selection type overview, setEmptySelectionAllowed(boolean)

getSelectionMode

public DateSelectionModel.SelectionMode getSelectionMode()

Returns the selection mode used by this model.

Returns:

the selection mode used by this model.

See Also:

selection type overview

setEmptySelectionAllowed

public void setEmptySelectionAllowed(boolean allowed)
                              throws DateSelectionException

Specifies whether the model supports empty date selections that is no date can be selected at one time. This feature is also known as null date selection. When changing from true to false there must be at least one date selected because otherwise the model would be in an inconsistent state. If that does not happen, the operation fails throwing an exception.

Parameters:

allowed - true if empty selection is allowed or false otherwise

Throws:

DateSelectionException - exception thrown when the model is set to not allow empty selections but it does not contain any selected date.

See Also:

empty selection (null dates) overview

isEmptySelectionAllowed

public boolean isEmptySelectionAllowed()

Determines whether empty selection is allowed.

Returns:

true if empty selection is allowed or false otherwise.

See Also:

empty selection (null dates) overview, setEmptySelectionAllowed(boolean)

isDateSelectable

public boolean isDateSelectable(java.util.Date date)

Determines whether a specified date can be selected from this model or not. The dates that can not be selected appear as disabled in the calendar.

Parameters:

date - the date to be tested; if null is the same as asking whether empty date selection is allowed

Returns:

true if the date can be selected; false otherwise.

See Also:

restricted dates overview, isEmptySelectionAllowed()

getMinimumAllowed

public java.util.Date getMinimumAllowed()

Returns the minimum allowed date. Dates below the minimum allowed date should not be selected. If the minimum allowed date is null then there is no restriction.

Returns:

the minimum allowed date or null.

See Also:

restricted dates overview, isDateSelectable(Date)

getMaximumAllowed

public java.util.Date getMaximumAllowed()

Returns the maximum allowed date. Dates above the maximum allowed date should not be selected. If the maximum allowed date is null then there is no restriction.

Returns:

the maximum allowed date or null.

See Also:

restricted dates overview, isDateSelectable(Date)

isDateSelected

public boolean isDateSelected(java.util.Date date)

Determines whether a specified date has been selected.

Parameters:

date - date to be tested; if null then it tests if the selection is empty (when empty date selection is allowed)

Returns:

true if the date has been selected; false otherwise.

See Also:

date selection overview, isEmptySelectionAllowed(), getSelectedDates()

setSelectedDates

public void setSelectedDates(java.util.Date[] dates)

Specifies what dates are selected by this model. This method selects all the dates only when a multiple selection mode is used. Otherwise, only the first date is selected.

Parameters:

dates - dates that will be selected. They can be zero, one or more. If empty selection is off and the selected dates array is empty, then no date is selected; the selected dates remain unchanged. On a null array of dates, nothing happens.

See Also:

setEmptySelectionAllowed(boolean), setSelectionMode(DateSelectionModel.SelectionMode)

getSelectedDates

public java.util.Date[] getSelectedDates()

Returns the selected dates. Depending on the selection mode, zero, one or more dates are returned. There can be returned zero dates when empty date selection is allowed.

Returns:

the selected dates; the array can be empty when empty selection is allowed

See Also:

date selection overview, setEmptySelectionAllowed(boolean)

getAnchorSelectionDate

public java.util.Date getAnchorSelectionDate()

Returns the anchor selection date.

Returns:

the anchor selection date or null when the selection is empty.

See Also:

date selection overview, setAnchorSelectionDate(Date)

setAnchorSelectionDate

public void setAnchorSelectionDate(java.util.Date date)

Sets the anchor selection date. The anchor selection date is the first selected date in the selected range. If only one date is selected then it corresponds to that date. When no date is selected, this date is null.

Parameters:

date - anchor date to be set; ignored when null

See Also:

date selection overview

getLeadSelectionDate

public java.util.Date getLeadSelectionDate()

Returns the lead selection date.

Returns:

the lead selection date or null when the selection is empty.

See Also:

setAnchorSelectionDate(Date), date selection overview

setLeadSelectionDate

public void setLeadSelectionDate(java.util.Date date)

Sets the lead selection date. The lead selection date is the second selected date in the selected range. If only one date is selected then it corresponds to that date. When no date is selected, this date is null.

Parameters:

date - lead date to be set; ignored when null

See Also:

date selection overview

setDateSelectionIterval

public void setDateSelectionIterval(java.util.Date date1,
                                    java.util.Date date2)

Changes the date selection interval to be between date1 and date2 inclusive. Note that date1 doesn't have to be less than or equal to date2. Nothing happens when one of the dates is null.

Parameters:

date1 - one end of the date interval

date2 - other end of the date interval

See Also:

date selection overview

addDateSelectionInterval

public void addDateSelectionInterval(java.util.Date date1,
                                     java.util.Date date2)

Change the selection to be the set union of the current date selection and the dates between date1 and date2 inclusive. If this represents a change to the current date selection, then notify each DateSelectionListener. Note that date1 doesn't have to be less than or equal to date2. Nothing happens when one of the dates is null.

Parameters:

date1 - one end of the date interval

date2 - other end of the date interval

See Also:

date selection overview

removeDateSelectionInterval

public void removeDateSelectionInterval(java.util.Date date1,
                                        java.util.Date date2)

Change the selection to be the set difference of the current selection and the dates between date1 and date2 inclusive. If this represents a change to the current date selection, then notify each DateSelectionListener. Note that date1 doesn't have to be less than or equal to date2. Nothing happens when one of the dates is null.

Parameters:

date1 - one end of the date interval

date2 - other end of the date interval

See Also:

date selection overview

removeAllDates

public void removeAllDates()

Removes all selected dates from this model. When empty selection is not allowed, the anchor date is kept as selected.

See Also:

date selection overview

addDateSelectionListener

public void addDateSelectionListener(DateSelectionListener listener)

Registers a new date selection listener to the model.

Parameters:

listener - listener to be registered

See Also:

events listening overview

removeDateSelectionListener

public void removeDateSelectionListener(DateSelectionListener listener)

Removes a specified date selection listener from this model.

Parameters:

listener - listener to be removed

See Also:

events listening overview