com.standbysoft.component.date
Interface DateModel

All Known Implementing Classes:

DateEditComponentBinding, DefaultDateModel

public interface DateModel

The date model is a convenient way to represent extended information about a date; it is extremely useful for date editing components.

It wraps a date and allows date field changes. One can also clear a field to indicate that it is contains no value. Interested parties can register for notifications about date or date field changes. This model even allows to specify which date fields are used to build the date.

The values of the date fields depend on the current time zone.

As a special feature, it can accept years in a short form. This means that you could set a year like 1980 by just using the short form 80.

Method Summary

void	addDateListener(DateListener listener) Registers a new date listener to the model.
void	clear(int field) Clears a specified field, meaning that it contains no value.
int	get(int field) Returns the value of a specified field.
int	getAutoCenturyYear() Determines the reference year used to build the long year from a short one.
java.util.Date	getDate() Returns the date wrapped by this model.
int	getMaximumAllowed(int field, java.util.Date date) Returns the highest acceptable value for a certain field.
int	getMinimumAllowed(int field, java.util.Date date) Returns the lowest acceptable value for a certain field.
java.util.TimeZone	getTimeZone() Returns the time zone used by this model.
boolean	isAutoCentury() Determines whether century is automatically added to the year field if its value is less than 100.
boolean	isDateValid() Determines whether the date represented by this model is valid or not.
boolean	isSet(int field) Determines whether a specified field is cleared or not.
boolean	isUsed(int field) Determines whether a specified field is part of the date.
void	removeDateListener(DateListener listener) Removes a specified date listener from this model.
void	set(int field, int value) Modifies the value of a specified date field.
void	setAutoCentury(boolean auto) Specifies whether century is automatically added to the year field if its value is less than 100.
void	setAutoCenturyYear(int year) Specifies the year used to build the long year when short years are used.
void	setDate(java.util.Date date) Specifies a new date to be represented by this model that can later be modified field by field.
void	setTimeZone(java.util.TimeZone zone) Specifies the time zone for this model.
void	setUsed(int field, boolean used) Specifies whether a certain field is used to construct the actual date represented here.

Method Detail

setDate

public void setDate(java.util.Date date)

Specifies a new date to be represented by this model that can later be modified field by field. A null date will clear all the basic fields like Calendar.YEAR, Calendar.MONTH, Calendar.DATE, Calendar.HOUR, Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND.

Parameters:

date - date wrapped by the model

See Also:

clear(int)

getDate

public java.util.Date getDate()

Returns the date wrapped by this model. If there are missing fields and the date cannot be computed then a null date is returned.

Returns:

date wrapped by this model.

See Also:

setDate(Date), isSet(int)

setTimeZone

public void setTimeZone(java.util.TimeZone zone)

Specifies the time zone for this model. This parameter is very important if you need to know the values of the date fields in a certain time zone. If no time zone is specified, then the default one is used.

The dates that come in and out of this model are standard (GMT) while the values of the date fields depend on the time zone. If the time zone is changed, so do the internal date fields in order to reflect this change.

Parameters:

zone - new time zone for this model

See Also:

get(int)

getTimeZone

public java.util.TimeZone getTimeZone()

Returns the time zone used by this model.

Returns:

time zone used by this model.

See Also:

setTimeZone(TimeZone)

set

public void set(int field,
                int value)

Modifies the value of a specified date field.

Parameters:

field - date field that is modified. Possible values are: Calendar.YEAR, Calendar.MONTH, Calendar.MINUTE, etc.

value - the new date field value. Various implementations could handle this value differently. Some may allow and some may not allow out of range values.

See Also:

getMinimumAllowed(int, Date), getMaximumAllowed(int, Date)

get

public int get(int field)

Returns the value of a specified field.

Parameters:

field - date field that is tested. Possible values are: Calendar.YEAR, Calendar.MONTH, Calendar.MINUTE, etc.

Returns:

value of the specified field.

See Also:

setTimeZone(TimeZone)

clear

public void clear(int field)

Clears a specified field, meaning that it contains no value.

Parameters:

field - field that is cleared. Possible values are: Calendar.YEAR, Calendar.MONTH, Calendar.MINUTE, etc.

See Also:

isSet(int)

isSet

public boolean isSet(int field)

Determines whether a specified field is cleared or not.

Parameters:

field - field that is tested. Possible values are: Calendar.YEAR, Calendar.MONTH, Calendar.MINUTE, etc.

Returns:

true if the field is not cleared; false otherwise

See Also:

clear(int)

setUsed

public void setUsed(int field,
                    boolean used)

Specifies whether a certain field is used to construct the actual date represented here. When the date is evaluated, all the fields that it uses (marked with this method as used) must contain a value. Otherwise, the date is considered incomplete and it is in fact a null date.

This method is mainly intended for use by date editing components that restrict the represented date only to some of its fields.

Parameters:

field - specified field that is marked as used or unused

used - true if the field is part of the date; false otherwise

See Also:

clear(int), getDate()

isUsed

public boolean isUsed(int field)

Determines whether a specified field is part of the date.

Parameters:

field - field that is tested

Returns:

true if the field is part of the date; false otherwise

See Also:

setUsed(int, boolean)

setAutoCentury

public void setAutoCentury(boolean auto)

Specifies whether century is automatically added to the year field if its value is less than 100.

Parameters:

auto - true if century is automatically added; false otherwise

See Also:

setAutoCenturyYear(int)

isAutoCentury

public boolean isAutoCentury()

Determines whether century is automatically added to the year field if its value is less than 100.

Returns:

true if century is automatically added; false otherwise.

See Also:

setAutoCentury(boolean)

setAutoCenturyYear

public void setAutoCenturyYear(int year)

Specifies the year used to build the long year when short years are used. One can use short years which range from 0..99 when the autoCentury property is enabled. This means that instead of typing 1980 you can just use 80.

The short year is converted into a long year after it is compared with the last two digits of the autoCenturyYear year. Here are some examples that show how this mechanism works:

short	autoCenturyYear	long
30	1930	1930
56	1930	1956
11	1930	2011

Parameters:

year - reference year used to build the long year from a short one

See Also:

setAutoCentury(boolean)

getAutoCenturyYear

public int getAutoCenturyYear()

Determines the reference year used to build the long year from a short one. By default, this year is 1930.

Returns:

reference year used to build the long year from a short one.

See Also:

setAutoCenturyYear(int)

isDateValid

public boolean isDateValid()

Determines whether the date represented by this model is valid or not.

Returns:

true if the date is valid; false otherwise

getMinimumAllowed

public int getMinimumAllowed(int field,
                             java.util.Date date)

Returns the lowest acceptable value for a certain field. For some fields this value might depend on other date fields.

Parameters:

field - field that is tested

date - context object that can offer additional information about the other date fields

Returns:

lowest acceptable value for a certain field, like 0 for the minute field

See Also:

set(int, int)

getMaximumAllowed

public int getMaximumAllowed(int field,
                             java.util.Date date)

Returns the highest acceptable value for a certain field. For some fields like day of month, this value might depend on other date fields. For instance, the days in a month depend on the month and in the case of February, they also depend on the year.

Parameters:

field - field that is tested

date - context object that can offer additional information about the other date fields

Returns:

highest acceptable value for a certain field, like 59 for the minute field

See Also:

set(int, int)

addDateListener

public void addDateListener(DateListener listener)

Registers a new date listener to the model.

Parameters:

listener - listener to be registered

removeDateListener

public void removeDateListener(DateListener listener)

Removes a specified date listener from this model.

Parameters:

listener - listener to be removed