DateTransformerBase (JGUIraffe BOM 1.3.1 API)

java.lang.Object
- net.sf.jguiraffe.transform.DateTransformerBase

All Implemented Interfaces:: Transformer, Validator

Direct Known Subclasses:: DateTimeTransformer, DateTransformer, TimeTransformer

public abstract class DateTransformerBase
extends Object
implements Transformer, Validator

An abstract base class for date transformer objects.

Date transformers know how to handle certain kinds of date formats. They can

validate a string entered by a user to verify that it contains a valid date according to the supported format
perform certain semantic checks, e.g. whether the date is in the past or future
transform a valid string into a java.util.Date object
transform a java.util.Date object into a string representation.

This base class already implements the major part of the required functionality. Concrete sub classes are responsible of creating an appropriate DateFormat object that is able to parse the specific date format.

There are some properties for customizing the parsing of date strings. These properties can be set either through the set methods provided by this class or using a <properties> section in the builder script that declares the transformer. The following properties are supported:

Property	Description	Default
style	Defines the style of the date. This can be one of the style constants declared by the `java.text.DateFormat` class like `SHORT` or `FULL`.	SHORT
lenient	Specifies the lenient mode for parsing dates. The lenient flag has the same meaning as described in the documentation of the `java.text.DateFormat` class and controls how strict the parsing process is. Note that lenient mode is turned off per default.	false
referenceDate	With this property a reference date can be specified that is used for testing semantic correctness. For instance, if one of the `after` or `before` flags described below are set, it can be tested whether the entered date is after or before this reference date. The property must be a string conforming to one of the formats supported by `java.sql.Timestamp`, `java.sql.Date`, or `java.sql.Time`.	current date
after	If this boolean flag is set, the entered date must be after the reference date.	false
before	If this boolean flag is set, the entered date must be before the reference date. Note that the properties `before` and `after` are mutual exclusive.	false
equal	This flag is evaluated only if `after` or `before` is true. In this case, it controls whether the reference date is included in the comparison. So a comparison can be specified whether the entered date is before or equal a reference date.	false

Depending on the performed validations this validator implementation can create a bunch of error messages. The following table lists all supported error messages:

Message key	Description	Parameters
	The passed in string cannot be parsed to a date object.	{0} = the date string
	The entered date must be after the reference date.	{0} = the (formatted) reference date
	The entered date must be after or equal the reference date.	{0} = the (formatted) reference date
	The entered date must be before the reference date.	{0} = the (formatted) reference date
	The entered date must be before or equal the reference date.	{0} = the (formatted) reference date

This class implements both the Transformer and the Validator interfaces. The Transformer implementation can work in both directions: if a Date object is passed in, it will format the date to a string using the specified format. Otherwise the passed in object is tried to be converted to a date.

Instances can be shared between multiple input components. It is especially possible to use an instance as both (read and write) transformer and validator for an input component at the same time (provided that the same properties are used). However the class is not thread-safe.

Version:: $Id: DateTransformerBase.java 205 2012-01-29 18:29:57Z oheger $
Author:: Oliver Heger
See Also:: ValidationMessageConstants

Field Summary

Fields
Modifier and Type	Field and Description
`protected static String`	`PROP_AFTER` Constant for the after property.
`protected static String`	`PROP_BEFORE` Constant for the before property.
`protected static String`	`PROP_EQUAL` Constant for the equal property.
`protected static String`	`PROP_LENIENT` Constant for the lenient property.
`protected static String`	`PROP_REFERENCE_DATE` Constant for the referenceDate property.
`protected static String`	`PROP_STYLE` Constant for the style property.

Constructor Summary

Constructors
Modifier Constructor and Description

protected DateTransformerBase()
Creates a new instance of DateTransformerBase.

Constructors
Modifier	Constructor and Description
`protected`	`DateTransformerBase()` Creates a new instance of `DateTransformerBase`.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`protected abstract DateFormat`	`createFormat(Locale locale, int style, org.apache.commons.configuration.Configuration config)` Creates a `DateFormat` object for parsing dates of the supported format.
`protected ValidationResult`	`errorResult(String errorKey, TransformerContext ctx, Object... params)` Creates a validation result if an error occurred.
`protected Date`	`getDefaultReferenceDate()` Creates a new default reference date.
`String`	`getReferenceDate()` Returns the reference date.
`protected Date`	`getReferenceDateProperty(org.apache.commons.configuration.Configuration config)` Returns the reference date to be used.
`int`	`getStyle()` Returns the style for the date to be parsed.
`protected DateFormat`	`initializeFormat(Locale locale, org.apache.commons.configuration.Configuration config)` Returns an initialized format object.
`boolean`	`isAfter()` Returns the after flag.
`boolean`	`isBefore()` Returns the before flag.
`protected ValidationResult`	`isDateValid(Date date, DateFormat fmt, TransformerContext ctx, org.apache.commons.configuration.Configuration config)` Checks the specified date.
`boolean`	`isEqual()` Returns the equal flag.
`boolean`	`isLenient()` Returns the lenient flag.
`ValidationResult`	`isValid(Object o, TransformerContext ctx)` Validates the passed in object.
`void`	`setAfter(boolean after)` Sets the after flag.
`void`	`setBefore(boolean before)` Sets the before flag.
`void`	`setEqual(boolean equal)` Sets the equal flag.
`void`	`setLenient(boolean lenient)` Sets the lenient flag.
`void`	`setReferenceDate(String referenceDate)` Sets the reference date.
`void`	`setStyle(int dateStyle)` Sets the style for the date to be parsed.
`Object`	`transform(Object o, TransformerContext ctx)` Transforms the specified object.
`protected Date`	`transformDate(String date, DateFormat fmt)` Parses the specified date string.
`protected Date`	`transformSqlDate(String strDate)` Transforms a date in string form to a date object.
`protected Object`	`transformToDate(Object o, TransformerContext ctx)` Performs a transformation to a date object.
`protected Object`	`transformToString(Date dt, TransformerContext ctx)` Performs a transformation from a date to string.
`static Date`	`updateDatePart(Date dateTime, Date datePart)` Writes the given date part into the specified date object.
`static Date`	`updateTimePart(Date dateTime, Date timePart)` Writes the given time part into the specified date object.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - PROP_STYLE
```
protected static final String PROP_STYLE
```
    Constant for the style property.
    
    See Also:
    
    Constant Field Values
  - PROP_LENIENT
```
protected static final String PROP_LENIENT
```
    Constant for the lenient property.
    
    See Also:
    
    Constant Field Values
  - PROP_REFERENCE_DATE
```
protected static final String PROP_REFERENCE_DATE
```
    Constant for the referenceDate property.
    
    See Also:
    
    Constant Field Values
  - PROP_BEFORE
```
protected static final String PROP_BEFORE
```
    Constant for the before property.
    
    See Also:
    
    Constant Field Values
  - PROP_AFTER
```
protected static final String PROP_AFTER
```
    Constant for the after property.
    
    See Also:
    
    Constant Field Values
  - PROP_EQUAL
```
protected static final String PROP_EQUAL
```
    Constant for the equal property.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - DateTransformerBase
```
protected DateTransformerBase()
```
    Creates a new instance of DateTransformerBase.
- Method Detail
  - getStyle
```
public int getStyle()
```
    Returns the style for the date to be parsed.
    
    Returns:
    
    the date style
  - setStyle
```
public void setStyle(int dateStyle)
```
    Sets the style for the date to be parsed. This is one of the style constants defined by the DateFormat class, e.g. DateFormat.SHORT or DateFormat.MEDIUM.
    
    Parameters:
    
    dateStyle - the style for the date
  - isLenient
```
public boolean isLenient()
```
    Returns the lenient flag.
    
    Returns:
    
    the lenient flag
  - setLenient
```
public void setLenient(boolean lenient)
```
    Sets the lenient flag.
    
    Parameters:
    
    lenient - the lenient flag
  - getReferenceDate
```
public String getReferenceDate()
```
    Returns the reference date.
    
    Returns:
    
    the reference date
  - setReferenceDate
```
public void setReferenceDate(String referenceDate)
```
    Sets the reference date. This date will be used for before or after comparisons. The date is set as a string. This string must conform to the format supported by the date classes in the java.sql package.
    
    Parameters:
    
    referenceDate - the reference date
    
    Throws:
    
    IllegalArgumentException - if the date has not the expected format
  - isBefore
```
public boolean isBefore()
```
    Returns the before flag.
    
    Returns:
    
    the before flag
  - setBefore
```
public void setBefore(boolean before)
```
    Sets the before flag. If set, the validate method checks whether the passed in date is before the reference date.
    
    Parameters:
    
    before - the before flag
  - isAfter
```
public boolean isAfter()
```
    Returns the after flag.
    
    Returns:
    
    the after flag
  - setAfter
```
public void setAfter(boolean after)
```
    Sets the after flag. If set, the validate method checks whether the passed in date is after the reference date.
    
    Parameters:
    
    after - the after flag
  - isEqual
```
public boolean isEqual()
```
    Returns the equal flag.
    
    Returns:
    
    the equal flag
  - setEqual
```
public void setEqual(boolean equal)
```
    Sets the equal flag. This flag is evaluated if one of the before or after flags is set. In this case the reference date is included into the comparison.
    
    Parameters:
    
    equal - the value of the equal flag
  - transform
```
public Object transform(Object o,
                        TransformerContext ctx)
                 throws Exception
```
    Transforms the specified object. This implementation is able to transform a date in string form to a java.util.Date object. If the date is invalid, an exception is thrown. The method does not perform any additional validity checks. This means that any valid date will be returned, even if it conflicts with a reference date.
    
    Specified by:
    
    transform in interface Transformer
    
    Parameters:
    
    o - the object to be transformed
    
    ctx - the transformer context
    
    Returns:
    
    the transformed object
    
    Throws:
    
    Exception - if an error occurs
  - isValid
```
public ValidationResult isValid(Object o,
                                TransformerContext ctx)
```
    Validates the passed in object. This implementation transforms the object into a string and checks whether it represents a valid date. If the before or after flags have been set, the date will also be compared to a reference date. A null input will be considered valid.
    
    Specified by:
    
    isValid in interface Validator
    
    Parameters:
    
    o - the object to be validated
    
    ctx - the transformer context
    
    Returns:
    
    an object with the results of the validation
  - updateDatePart
```
public static Date updateDatePart(Date dateTime,
                                  Date datePart)
```
    Writes the given date part into the specified date object. This method will write the date component into a combined date/time object leaving the time component untouched. This is useful for instance if a GUI has different input fields for the date and the time, but in the data model only a single Date object is used. For example, if the dateTime parameter has the value 2008-01-29 22:17:59 and datePart is 2008-02-05, the result will be 2008-02-05 22:17:59.
    
    Parameters:
    
    dateTime - the combined date/time object
    
    datePart - the date part
    
    Returns:
    
    the changed date/time object
    
    Throws:
    
    IllegalArgumentException - if one of the date parameters is null
  - updateTimePart
```
public static Date updateTimePart(Date dateTime,
                                  Date timePart)
```
    Writes the given time part into the specified date object. This method will write the time component into a combined date/time object leaving the date component untouched. This is useful for instance if a GUI has different input fields for the date and the time, but in the data model only a single Date object is used. For example, if the dateTime parameter has the value 2008-01-29 22:17:59 and timePart is 10:22:05, the result will be 2008-02-05 10:22:05.
    
    Parameters:
    
    dateTime - the combined date/time object
    
    timePart - the time part
    
    Returns:
    
    the changed date/time object
    
    Throws:
    
    IllegalArgumentException - if one of the date parameters is null
  - transformToDate
```
protected Object transformToDate(Object o,
                                 TransformerContext ctx)
                          throws Exception
```
    Performs a transformation to a date object. Tries to parse the string representation of the parsed in object.
    
    Parameters:
    
    o - the object to be transformed
    
    ctx - the transformer context
    
    Returns:
    
    the transformed object
    
    Throws:
    
    Exception - if an error occurs
  - transformToString
```
protected Object transformToString(Date dt,
                                   TransformerContext ctx)
                            throws Exception
```
    Performs a transformation from a date to string. This method is called if the object to be transformed is already a date. In this case this transformer class works in the opposite direction.
    
    Parameters:
    
    dt - the date to be transformed
    
    ctx - the transformer context
    
    Returns:
    
    the transformed object
    
    Throws:
    
    Exception - if an error occurs
  - getReferenceDateProperty
```
protected Date getReferenceDateProperty(org.apache.commons.configuration.Configuration config)
```
    Returns the reference date to be used. If a reference date is defined in the configuration, it is used. Otherwise the internally set reference date will be returned. If no reference date has been set, the getDefaultReferenceDate() method is called.
    
    Parameters:
    
    config - the configuration with the current properties
    
    Returns:
    
    the reference date
    
    Throws:
    
    IllegalArgumentException - if the reference date is in an incorrect format
  - getDefaultReferenceDate
```
protected Date getDefaultReferenceDate()
```
    Creates a new default reference date. This method is invoked when before or after comparisons have to be performed, but no reference date has been set. This implementation returns a Date object for the current date (only date, no time portion).
    
    Returns:
    
    the default reference date
  - transformSqlDate
```
protected Date transformSqlDate(String strDate)
```
    Transforms a date in string form to a date object. This method expects that the date is in a java.sql compatible format.
    
    Parameters:
    
    strDate - the date as a string
    
    Returns:
    
    the converted date object
    
    Throws:
    
    IllegalArgumentException - if the date cannot be converted
  - transformDate
```
protected Date transformDate(String date,
                             DateFormat fmt)
                      throws ParseException
```
    Parses the specified date string. This implementation uses the passed in DateFormat object for this purpose.
    
    Parameters:
    
    date - the date to be parsed
    
    fmt - the DateFormat to be used
    
    Returns:
    
    the parsed date
    
    Throws:
    
    ParseException - if the date cannot be parsed
  - initializeFormat
```
protected DateFormat initializeFormat(Locale locale,
                                      org.apache.commons.configuration.Configuration config)
```
    Returns an initialized format object. This implementation calls createFormat() for obtaining a new format object. Then the object is initialized based on the currently set properties.
    
    Parameters:
    
    locale - the locale
    
    config - the properties associated with the current context
    
    Returns:
    
    the initialized format object
  - isDateValid
```
protected ValidationResult isDateValid(Date date,
                                       DateFormat fmt,
                                       TransformerContext ctx,
                                       org.apache.commons.configuration.Configuration config)
```
    Checks the specified date. This method is called by isValid() if the entered date is syntactically correct. It checks for semantic correctness, e.g. whether the date is in correct relation to the reference date.
    
    Parameters:
    
    date - the date to check
    
    fmt - the date format object to be used
    
    ctx - the transformer context
    
    config - the configuration with the properties
    
    Returns:
    
    a ValidationResult object with the result of the validation
  - errorResult
```
protected ValidationResult errorResult(String errorKey,
                                       TransformerContext ctx,
                                       Object... params)
```
    Creates a validation result if an error occurred.
    
    Parameters:
    
    errorKey - the key of the error message
    
    ctx - the transformer context
    
    params - optional parameters for the error message
    
    Returns:
    
    the validation result with this error
  - createFormat
```
protected abstract DateFormat createFormat(Locale locale,
                                           int style,
                                           org.apache.commons.configuration.Configuration config)
```
    Creates a DateFormat object for parsing dates of the supported format. Concrete sub classes have to return an appropriate instance of DateFormat (an implementation will probably call the correct getXXXInstance() factory method of DateFormat).
    
    Parameters:
    
    locale - the locale
    
    style - the style to be used
    
    config - a configuration object for accessing the current properties
    
    Returns:
    
    the DateFormat object to be used for parsing

Class DateTransformerBase

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

PROP_STYLE

PROP_LENIENT

PROP_REFERENCE_DATE

PROP_BEFORE

PROP_AFTER

PROP_EQUAL

Constructor Detail

DateTransformerBase

Method Detail

getStyle

setStyle

isLenient

setLenient

getReferenceDate

setReferenceDate

isBefore

setBefore

isAfter

setAfter

isEqual

setEqual

transform

isValid

updateDatePart

updateTimePart

transformToDate

transformToString

getReferenceDateProperty

getDefaultReferenceDate

transformSqlDate

transformDate

initializeFormat

isDateValid

errorResult

createFormat