Class 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
    "ERR_INVALID_DATE" The passed in string cannot be parsed to a date object. {0} = the date string
    "ERR_DATE_AFTER" The entered date must be after the reference date. {0} = the (formatted) reference date
    "ERR_DATE_AFTER_EQUAL" The entered date must be after or equal the reference date. {0} = the (formatted) reference date
    "ERR_DATE_BEFORE" The entered date must be before the reference date. {0} = the (formatted) reference date
    "ERR_DATE_BEFORE_EQUAL" 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
    • 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