Module org.omnifaces
Package org.omnifaces.el.functions

Class Dates

  • public final class Dates
extends Object

    Collection of EL functions for date and time: of:formatDate(), of:formatDateWithTimezone(), of:addXxx() like of:addDays(), of:xxxBetween() like of:daysBetween(), of:getMonths(), of:getShortMonths(), of:getDaysOfWeek(), of:getShortDaysOfWeek(), of:getMonth(), of:getShortMonth(), of:getDayOfWeek() and of:getShortDayOfWeek().

    Historical note: before OmniFaces 3.6, these functions accepted java.util.Date and java.util.TimeZone only. Since OmniFaces 3.6, these functions also accept java.time.Temporal and java.time.ZoneId.

    Author:
    Bauke Scholtz

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static <D> D addDays​(D date, int days)
      Returns a new date instance which is a sum of the given date and the given amount of days.
      static <D> D addHours​(D date, int hours)
      Returns a new date instance which is a sum of the given date and the given amount of hours.
      static <D> D addMinutes​(D date, int minutes)
      Returns a new date instance which is a sum of the given date and the given amount of minutes.
      static <D> D addMonths​(D date, int months)
      Returns a new date instance which is a sum of the given date and the given amount of months.
      static <D> D addSeconds​(D date, int seconds)
      Returns a new date instance which is a sum of the given date and the given amount of seconds.
      static <D> D addWeeks​(D date, int weeks)
      Returns a new date instance which is a sum of the given date and the given amount of weeks.
      static <D> D addYears​(D date, int years)
      Returns a new date instance which is a sum of the given date and the given amount of years.
      static <D> int daysBetween​(D start, D end)
      Returns the amount of days between two given dates.
      static <D> String formatDate​(D date, String pattern)
      Format the given date in the given pattern with the default timezone.
      static <D,​Z>
      String      		 formatDateWithTimezone​(D date, String pattern, Z timezone)
      Format the given date in the given pattern with the given timezone.
      static String getDayOfWeek​(Integer dayOfWeekNumber)
      Returns the day of week name from the mapping associated with the given day of week number in ISO 8601 order (Monday first) for the current locale.
      static Map<String,​Integer> getDaysOfWeek()
      Returns a mapping of day of week names in ISO 8601 order (Monday first) for the current locale.
      static String getMonth​(Integer monthNumber)
      Returns the month name from the mapping associated with the given month number for the current locale.
      static Map<String,​Integer> getMonths()
      Returns a mapping of month names by month numbers for the current locale.
      static String getShortDayOfWeek​(Integer dayOfWeekNumber)
      Returns the short day of week name from the mapping associated with the given day of week number in ISO 8601 order (Monday first) for the current locale.
      static Map<String,​Integer> getShortDaysOfWeek()
      Returns a mapping of short day of week names in ISO 8601 order (Monday first) for the current locale.
      static String getShortMonth​(Integer monthNumber)
      Returns the short month name from the mapping associated with the given month number for the current locale.
      static Map<String,​Integer> getShortMonths()
      Returns a mapping of short month names by month numbers for the current locale.
      static <D> long hoursBetween​(D start, D end)
      Returns the amount of hours between two given dates.
      static <D> long minutesBetween​(D start, D end)
      Returns the amount of minutes between two given dates.
      static <D> int monthsBetween​(D start, D end)
      Returns the amount of months between two given dates.
      static <D> long secondsBetween​(D start, D end)
      Returns the amount of seconds between two given dates.
      static <D> int weeksBetween​(D start, D end)
      Returns the amount of weeks between two given dates.
      static <D> int yearsBetween​(D start, D end)
      Returns the amount of years between two given dates.

    • Method Detail

      • formatDate

        public static <D> String formatDate​(D date,
                                    String pattern)
        Format the given date in the given pattern with the default timezone. This is useful when you want to format dates in for example the title attribute of an UI component, or the itemLabel attribute of select item, or wherever you can't use the <f:convertDateTime> tag. The format locale will be set to the one as obtained by Faces.getLocale().
        Type Parameters:
        D - The date type, can be Date, Calendar or Temporal.
        Parameters:
        date - The date to be formatted in the given pattern.
        pattern - The pattern to format the given date in.
        Returns:
        The date which is formatted in the given pattern.
        Throws:
        NullPointerException - When the pattern is null.
        IllegalArgumentException - When date is not Date, Calendar or Temporal.
        See Also:
        formatDateWithTimezone(Object, String, Object)

      • formatDateWithTimezone

        public static <D,​Z> String formatDateWithTimezone​(D date,
                                                        String pattern,
                                                        Z timezone)
        Format the given date in the given pattern with the given timezone. This is useful when you want to format dates in for example the title attribute of an UI component, or the itemLabel attribute of select item, or wherever you can't use the <f:convertDateTime> tag. The format locale will be set to the one as obtained by Faces.getLocale().
        Type Parameters:
        D - The date type, can be Date, Calendar or Temporal.
        Z - The timezone type, can be either String, TimeZone or ZoneId.
        Parameters:
        date - The date to be formatted in the given pattern.
        pattern - The pattern to format the given date in.
        timezone - The timezone to format the given date with.
        Returns:
        The date which is formatted in the given pattern.
        Throws:
        NullPointerException - When the pattern is null.
        IllegalArgumentException - When date is not Date, Calendar or Temporal, or when timezone is not String, TimeZone or ZoneId.

      • addYears

        public static <D> D addYears​(D date,
                             int years)
        Returns a new date instance which is a sum of the given date and the given amount of years.
        Type Parameters:
        D - The date type, can be Date, Calendar or Temporal.
        Parameters:
        date - The date to add the given amount of years to.
        years - The amount of years to be added to the given date. It can be negative.
        Returns:
        A new date instance which is a sum of the given date and the given amount of years.
        Throws:
        NullPointerException - When the date is null.
        IllegalArgumentException - When date is not Date, Calendar or Temporal.

      • addMonths

        public static <D> D addMonths​(D date,
                              int months)
        Returns a new date instance which is a sum of the given date and the given amount of months.
        Type Parameters:
        D - The date type, can be Date, Calendar or Temporal.
        Parameters:
        date - The date to add the given amount of months to.
        months - The amount of months to be added to the given date. It can be negative.
        Returns:
        A new date instance which is a sum of the given date and the given amount of months.
        Throws:
        NullPointerException - When the date is null.
        IllegalArgumentException - When date is not Date, Calendar or Temporal.

      • addWeeks

        public static <D> D addWeeks​(D date,
                             int weeks)
        Returns a new date instance which is a sum of the given date and the given amount of weeks.
        Type Parameters:
        D - The date type, can be Date, Calendar or Temporal.
        Parameters:
        date - The date to add the given amount of weeks to.
        weeks - The amount of weeks to be added to the given date. It can be negative.
        Returns:
        A new date instance which is a sum of the given date and the given amount of weeks.
        Throws:
        NullPointerException - When the date is null.
        IllegalArgumentException - When date is not Date, Calendar or Temporal.

      • addDays

        public static <D> D addDays​(D date,
                            int days)
        Returns a new date instance which is a sum of the given date and the given amount of days.
        Type Parameters:
        D - The date type, can be Date, Calendar or Temporal.
        Parameters:
        date - The date to add the given amount of days to.
        days - The amount of days to be added to the given date. It can be negative.
        Returns:
        A new date instance which is a sum of the given date and the given amount of days.
        Throws:
        NullPointerException - When the date is null.
        IllegalArgumentException - When date is not Date, Calendar or Temporal.

      • addHours

        public static <D> D addHours​(D date,
                             int hours)
        Returns a new date instance which is a sum of the given date and the given amount of hours.
        Type Parameters:
        D - The date type, can be Date, Calendar or Temporal.
        Parameters:
        date - The date to add the given amount of hours to.
        hours - The amount of hours to be added to the given date. It can be negative.
        Returns:
        A new date instance which is a sum of the given date and the given amount of hours.
        Throws:
        NullPointerException - When the date is null.
        IllegalArgumentException - When date is not Date, Calendar or Temporal.

      • addMinutes

        public static <D> D addMinutes​(D date,
                               int minutes)
        Returns a new date instance which is a sum of the given date and the given amount of minutes.
        Type Parameters:
        D - The date type, can be Date, Calendar or Temporal.
        Parameters:
        date - The date to add the given amount of minutes to.
        minutes - The amount of minutes to be added to the given date. It can be negative.
        Returns:
        A new date instance which is a sum of the given date and the given amount of minutes.
        Throws:
        NullPointerException - When the date is null.
        IllegalArgumentException - When date is not Date, Calendar or Temporal.

      • addSeconds

        public static <D> D addSeconds​(D date,
                               int seconds)
        Returns a new date instance which is a sum of the given date and the given amount of seconds.
        Type Parameters:
        D - The date type, can be Date, Calendar or Temporal.
        Parameters:
        date - The date to add the given amount of seconds to.
        seconds - The amount of seconds to be added to the given date. It can be negative.
        Returns:
        A new date instance which is a sum of the given date and the given amount of seconds.
        Throws:
        NullPointerException - When the date is null.
        IllegalArgumentException - When date is not Date, Calendar or Temporal.

      • yearsBetween

        public static <D> int yearsBetween​(D start,
                                   D end)
        Returns the amount of years between two given dates. This will be negative when the end date is before the start date.
        Type Parameters:
        D - The date type, can be Date, Calendar or Temporal.
        Parameters:
        start - The start date.
        end - The end date.
        Returns:
        The amount of years between two given dates.
        Throws:
        NullPointerException - When a date is null.
        IllegalArgumentException - When date is not Date, Calendar or Temporal.

      • monthsBetween

        public static <D> int monthsBetween​(D start,
                                    D end)
        Returns the amount of months between two given dates. This will be negative when the end date is before the start date.
        Type Parameters:
        D - The date type, can be Date, Calendar or Temporal.
        Parameters:
        start - The start date.
        end - The end date.
        Returns:
        The amount of months between two given dates.
        Throws:
        NullPointerException - When a date is null.
        IllegalArgumentException - When date is not Date, Calendar or Temporal.

      • weeksBetween

        public static <D> int weeksBetween​(D start,
                                   D end)
        Returns the amount of weeks between two given dates. This will be negative when the end date is before the start date.
        Type Parameters:
        D - The date type, can be Date, Calendar or Temporal.
        Parameters:
        start - The start date.
        end - The end date.
        Returns:
        The amount of weeks between two given dates.
        Throws:
        NullPointerException - When a date is null.
        IllegalArgumentException - When date is not Date, Calendar or Temporal.

      • daysBetween

        public static <D> int daysBetween​(D start,
                                  D end)
        Returns the amount of days between two given dates. This will be negative when the end date is before the start date.
        Type Parameters:
        D - The date type, can be Date, Calendar or Temporal.
        Parameters:
        start - The start date.
        end - The end date.
        Returns:
        The amount of days between two given dates.
        Throws:
        NullPointerException - When a date is null.
        IllegalArgumentException - When date is not Date, Calendar or Temporal.

      • hoursBetween

        public static <D> long hoursBetween​(D start,
                                    D end)
        Returns the amount of hours between two given dates. This will be negative when the end date is before the start date.
        Type Parameters:
        D - The date type, can be Date, Calendar or Temporal.
        Parameters:
        start - The start date.
        end - The end date.
        Returns:
        The amount of hours between two given dates.
        Throws:
        NullPointerException - When a date is null.
        IllegalArgumentException - When date is not Date, Calendar or Temporal.

      • minutesBetween

        public static <D> long minutesBetween​(D start,
                                      D end)
        Returns the amount of minutes between two given dates. This will be negative when the end date is before the start date.
        Type Parameters:
        D - The date type, can be Date, Calendar or Temporal.
        Parameters:
        start - The start date.
        end - The end date.
        Returns:
        The amount of minutes between two given dates.
        Throws:
        NullPointerException - When a date is null.
        IllegalArgumentException - When date is not Date, Calendar or Temporal.

      • secondsBetween

        public static <D> long secondsBetween​(D start,
                                      D end)
        Returns the amount of seconds between two given dates. This will be negative when the end date is before the start date.
        Type Parameters:
        D - The date type, can be Date, Calendar or Temporal.
        Parameters:
        start - The start date.
        end - The end date.
        Returns:
        The amount of seconds between two given dates.
        Throws:
        NullPointerException - When a date is null.
        IllegalArgumentException - When date is not Date, Calendar or Temporal.

      • getMonths

        public static Map<String,​Integer> getMonths()
        Returns a mapping of month names by month numbers for the current locale. For example: "January=1", "February=2", etc. This is useful if you want to for example populate a <f:selectItems> which shows all months. The locale is obtained by Faces.getLocale(). The mapping is per locale stored in a local cache to improve retrieving performance.
        Returns:
        Month names for the current locale.
        See Also:
        DateFormatSymbols.getMonths()

      • getShortMonths

        public static Map<String,​Integer> getShortMonths()
        Returns a mapping of short month names by month numbers for the current locale. For example: "Jan=1", "Feb=2", etc. This is useful if you want to for example populate a <f:selectItems> which shows all short months. The locale is obtained by Faces.getLocale(). The mapping is per locale stored in a local cache to improve retrieving performance.
        Returns:
        Short month names for the current locale.
        See Also:
        DateFormatSymbols.getShortMonths()

      • getDaysOfWeek

        public static Map<String,​Integer> getDaysOfWeek()
        Returns a mapping of day of week names in ISO 8601 order (Monday first) for the current locale. For example: "Monday=1", "Tuesday=2", etc. This is useful if you want to for example populate a <f:selectItems> which shows all days of week. The locale is obtained by Faces.getLocale(). The mapping is per locale stored in a local cache to improve retrieving performance.
        Returns:
        Day of week names for the current locale.
        See Also:
        DateFormatSymbols.getWeekdays()

      • getShortDaysOfWeek

        public static Map<String,​Integer> getShortDaysOfWeek()
        Returns a mapping of short day of week names in ISO 8601 order (Monday first) for the current locale. For example: "Mon=1", "Tue=2", etc. This is useful if you want to for example populate a <f:selectItems> which shows all short days of week. The locale is obtained by Faces.getLocale(). The mapping is per locale stored in a local cache to improve retrieving performance.
        Returns:
        Short day of week names for the current locale.
        See Also:
        DateFormatSymbols.getShortWeekdays()

      • getMonth

        public static String getMonth​(Integer monthNumber)
        Returns the month name from the mapping associated with the given month number for the current locale. For example: "1=January", "2=February", etc. The locale is obtained by Faces.getLocale().
        Parameters:
        monthNumber - The month number to return the month name from the mapping for.
        Returns:
        The month name form the mapping associated with the given month number.
        Since:
        1.4

      • getShortMonth

        public static String getShortMonth​(Integer monthNumber)
        Returns the short month name from the mapping associated with the given month number for the current locale. For example: "1=Jan", "2=Feb", etc. The locale is obtained by Faces.getLocale().
        Parameters:
        monthNumber - The month number to return the short month name from the mapping for.
        Returns:
        The short month name form the mapping associated with the given month number.
        Since:
        1.4

      • getDayOfWeek

        public static String getDayOfWeek​(Integer dayOfWeekNumber)
        Returns the day of week name from the mapping associated with the given day of week number in ISO 8601 order (Monday first) for the current locale. For example: "1=Monday", "2=Tuesday", etc. The locale is obtained by Faces.getLocale().
        Parameters:
        dayOfWeekNumber - The day of week number to return the day of week name from the mapping for.
        Returns:
        The day of week name from the mapping associated with the given day of week number.
        Since:
        1.4

      • getShortDayOfWeek

        public static String getShortDayOfWeek​(Integer dayOfWeekNumber)
        Returns the short day of week name from the mapping associated with the given day of week number in ISO 8601 order (Monday first) for the current locale. For example: "1=Mon", "2=Tue", etc. The locale is obtained by Faces.getLocale().
        Parameters:
        dayOfWeekNumber - The day of week number to return the short day of week name from the mapping for.
        Returns:
        The short day of week name from the mapping associated with the given day of week number.
        Since:
        1.4