Skip to main content
Kinetic Community

Time Helper

  1. Getting Started
    1. Configuration
    2. Usage
  2. Methods
    1. add(Date date, long number, String unit, ZoneId timeZone) add(Date date, long number, String unit, String timeZoneString) add(Instant instant, long number, String unit, ZoneId timeZone) add(Instant instant, long number, String unit, String timeZoneString) add(String dateString, long number, String unit, ZoneId timeZone) add(String dateString, long number, String unit, String timeZoneString)
    2. endOf(Date date, String unit, ZoneId timeZone) endOf(Date date, String unit, String timeZoneString) endOf(Instant instant, String unit, ZoneId timeZone) endOf(Instant instant, String unit, String timeZoneString) endOf(String dateString, String unit, ZoneId timeZone) endOf(String dateString, String unit, String timeZoneString) endOf(Date date, String unit, ZoneId timeZone, long offset) endOf(Date date, String unit, String timeZoneString, long offset) endOf(Instant instant, String unit, ZoneId timeZone, long offset) endOf(Instant instant, String unit, String timeZoneString, long offset) endOf(String dateString, String unit, ZoneId timeZone, long offset) endOf(String dateString, String unit, String timeZoneString, long offset)
    3. format(Date date) format(Instant instant) format(String dateString) format(Date date, String formatString, ZoneId timeZone, Locale locale) format(Date date, String formatString, String timeZoneString, Locale locale) format(Instant instant, String formatString, ZoneId timeZone, Locale locale) format(Instant instant, String formatString, String timeZoneString, Locale locale) format(String dateString, String formatString, ZoneId timeZone, Locale locale) format(String dateString, String formatString, String timeZoneString, Locale locale)
    4. fromEpochMillisecond(long epochMillesecond)
    5. fromEpochSecond(long epochSecond)
    6. now()
    7. parse(String dateString) parse(String dateString, String formatString, ZoneId timeZone, Locale locale) parse(String dateString, String formatString, String timeZoneString, Locale locale)
    8. range(Date date, String unit, ZoneId timeZone) range(Date date, String unit, String timeZoneString) range(Instant instant, String unit, ZoneId timeZone) range(Instant instant, String unit, String timeZoneString) range(String dateString, String unit, ZoneId timeZone) range(String dateString, String unit, String timeZoneString) range(Date date, String unit, ZoneId timeZone, long offset) range(Date date, String unit, String timeZoneString, long offset) range(Instant instant, String unit, ZoneId timeZone, long offset) range(Instant instant, String unit, String timeZoneString, long offset) range(String dateString, String unit, ZoneId timeZone, long offset) range(String dateString, String unit, String timeZoneString, long offset)
    9. startOf(Date date, String unit, ZoneId timeZone) startOf(Date date, String unit, String timeZoneString) startOf(Instant instant, String unit, ZoneId timeZone) startOf(Instant instant, String unit, String timeZoneString) startOf(String dateString, String unit, ZoneId timeZone) startOf(String dateString, String unit, String timeZoneString) startOf(Date date, String unit, ZoneId timeZone, long offset) startOf(Date date, String unit, String timeZoneString, long offset) startOf(Instant instant, String unit, ZoneId timeZone, long offset) startOf(Instant instant, String unit, String timeZoneString, long offset) startOf(String dateString, String unit, ZoneId timeZone, long offset) startOf(String dateString, String unit, String timeZoneString, long offset)
    10. subtract(Date date, long number, String unit, ZoneId timeZone) subtract(Date date, long number, String unit, String timeZoneString) subtract(Instant instant, long number, String unit, ZoneId timeZone) subtract(Instant instant, long number, String unit, String timeZoneString) subtract(String dateString, long number, String unit, ZoneId timeZone) subtract(String dateString, long number, String unit, String timeZoneString)
    11. toEpochMillisecond(Date date) toEpochMillisecond(Instant instant) toEpochMillisecond(String dateString)
    12. toEpochSecond(Date date) toEpochSecond(Instant instant) toEpochSecond(String dateString)
  3. Related

The Time Helper contains many useful methods for using and manipulating date and time objects within the bundle.

There are two classes that share the same methods:

  • com.kineticdata.bundles.TimeHelper must be initialized in the bundle/initialization.jspf file and can then be used in JSTL expressions.
  • com.kineticdata.bundles.Time is a static class that can be used in JSP scriptlets and declarations (this is primarily useful in custom bundle helper declarations).

Getting Started

Configuration

In order to use the text helper in a bundle, it must be loaded in the bundle/initialization.jspf file as shown below

<% request.setAttribute("time", new com.kineticdata.bundles.TimeHelper()) %>

For a complete bundle/initialization.jspf example, see the default bundle implementation athttps://github.com/kineticdata/request-ce-bundle-default.

Usage

<%-- partials/sample.jsp --%>
${time.format(submission.submittedAt)}
<%-- bundle/BundleHelper.jspf --%>
<%!
  public static class BundleHelper {
    public static final String ISO_8601_FORMAT = "yyyy-MM-dd'T'HH:mm:ss.SSSXXX"
    private ZoneId timeZone
    private Locale locale
    public BundleHelper(ZoneId timeZone, Locale locale) {
        this.timeZone = timeZone
        this.locale = locale
    }
    public String iso8601WithOffset(Instant instant) {
      return com.kineticdata.bundles.Time.format(instant, ISO_8601_FORMAT, timeZone, locale)
    }
  }
%>

Methods

add(Date date, long number, String unit, ZoneId timeZone)
add(Date date, long number, String unit, String timeZoneString)
add(Instant instant, long number, String unit, ZoneId timeZone)
add(Instant instant, long number, String unit, String timeZoneString)
add(String dateString, long number, String unit, ZoneId timeZone)
add(String dateString, long number, String unit, String timeZoneString)

Returns a new java.time.Instant representing an instant with the specified number of time units added (the number can be negative, which effectively subtracts a number of time units from the specified date).

time.add(EPOCH, 1, "milliseconds", ZoneId.of("America/Chicago")) // 1970-01-01T00:00:00.001Z
time.add(EPOCH, 1, "seconds", "America/Chicago")                 // 1970-01-01T00:00:01Z
time.add(EPOCH, 1, "minutes", "America/Chicago")                 // 1970-01-01T00:01:00Z
time.add(EPOCH, 1, "hours", "America/Chicago")                   // 1970-01-01T01:00:00Z
time.add(EPOCH, 1, "days", "America/Chicago")                    // 1970-01-02T00:00:00Z
time.add(EPOCH, 1, "weeks", "America/Chicago")                   // 1970-01-08T00:00:00Z
time.add(EPOCH, 1, "months", "America/Chicago")                  // 1970-02-01T00:00:00Z
time.add(EPOCH, 1, "years", "America/Chicago")                   // 1971-01-01T00:00:00Z

endOf(Date date, String unit, ZoneId timeZone)
endOf(Date date, String unit, String timeZoneString)
endOf(Instant instant, String unit, ZoneId timeZone)
endOf(Instant instant, String unit, String timeZoneString)
endOf(String dateString, String unit, ZoneId timeZone)
endOf(String dateString, String unit, String timeZoneString)
endOf(Date date, String unit, ZoneId timeZone, long offset)
endOf(Date date, String unit, String timeZoneString, long offset)
endOf(Instant instant, String unit, ZoneId timeZone, long offset)
endOf(Instant instant, String unit, String timeZoneString, long offset)
endOf(String dateString, String unit, ZoneId timeZone, long offset)
endOf(String dateString, String unit, String timeZoneString, long offset)

Returns a new java.time.Instant representing the end of the specified time unit. A time zone is required to correctly comput the end of a day/week/month/year (which have boundaries defined by the offset at that time).

time.endOf(EPOCH, "millisecond", ZoneId.of("America/Chicago") // 1970-01-01T00:00:00.001Z
time.endOf(EPOCH, "second", "America/Chicago")                // 1970-01-01T00:00:01Z
time.endOf(EPOCH, "minute", "America/Chicago")                // 1970-01-01T00:01:00Z
time.endOf(EPOCH, "hour", "America/Chicago")                  // 1970-01-01T01:00:00Z
time.endOf(EPOCH, "day", "America/Chicago")                   // 1970-01-01T06:00:00Z
time.endOf(EPOCH, "week", "America/Chicago")                  // 1970-01-05T06:00:00Z
time.endOf(EPOCH, "month", "America/Chicago")                 // 1970-01-01T06:00:00Z
time.endOf(EPOCH, "year", "America/Chicago")                  // 1970-01-01T06:00:00Z

format(Date date)
format(Instant instant)
format(String dateString)
format(Date date, String formatString, ZoneId timeZone, Locale locale)
format(Date date, String formatString, String timeZoneString, Locale locale)
format(Instant instant, String formatString, ZoneId timeZone, Locale locale)
format(Instant instant, String formatString, String timeZoneString, Locale locale)
format(String dateString, String formatString, ZoneId timeZone, Locale locale)
format(String dateString, String formatString, String timeZoneString, Locale locale)

Returns the java.lang.String representation of the formatted date/time. If only the date/time is passed, the format will be in ISO8601 format using UTC.

time.format(EPOCH)                                                                    // 1970-01-01T00:00:00Z
time.format(EPOCH, "yyyy-MM-dd'T'HH:mm:ss.SSSXXX", "America/Chicago", Locale.ENGLISH) // 1969-12-31T18:00:00.000-06:00
time.format(EPOCH, "yyyy-MM-dd'T'HH:mm:ss.SSSXXX", "America/New_York", Locale.FRENCH) // 1969-12-31T19:00:00.000-05:00
time.format(EPOCH, "EEEE, MMM dd, uuuu", ZoneIf.of("America/Chicago"), Locale.ENGLISH)// Wednesday, Dec 31, 1969
time.format(EPOCH, "EEEE, MMM dd, uuuu", "America/Chicago", Locale.FRENCH)            // mercredi, déc. 31, 1969

fromEpochMillisecond(long epochMillesecond)

Returns a new java.time.Instant representing the instant a number of milliseconds from epoch (January 1st, 1970).

time.fromEpochMillisecond(0)             // 1970-01-01T00:00:00Z
time.fromEpochMillisecond(1446361199001) // 2015-11-01T06:59:59.001Z

fromEpochSecond(long epochSecond)

Returns a new java.time.Instant representing the instant a number of seconds from epoch (January 1st, 1970).

time.fromEpochSecond(0)          // 1970-01-01T00:00:00Z
time.fromEpochSecond(1446361199) // 2015-11-01T06:59:59Z

now()

Returns a new java.time.Instant representing the current server time.

time.now() // CURRENT SERVER TIME

parse(String dateString)
parse(String dateString, String formatString, ZoneId timeZone, Locale locale)
parse(String dateString, String formatString, String timeZoneString, Locale locale)

Parses the specified date/time string and returns a new java.time.Instant instance. If only the dateString is passed, it is assumed that the string is formatted as ISO8601 (or ISO8601 with the time zone id instead of the offset, as shown below).

time.parse("1970-01-01")                                                        // 1970-01-01T00:00:00Z
time.parse("1969-12-31T18:00:00-06")                                            // 1970-01-01T00:00:00Z
time.parse("1969-12-31T18:00:00.000-0600")                                      // 1970-01-01T00:00:00Z
time.parse("1969-12-31T18:00:00.000000000-06:00")                               // 1970-01-01T00:00:00Z
time.parse("1970-01-01 UTC")                                                    // 1970-01-01T00:00:00Z
time.parse("1969-12-31T18:00:00 America/Chicago")                               // 1970-01-01T00:00:00Z
time.parse("1970-01-01TZ")                                                      // 1970-01-01T00:00:00Z
time.parse("1970-01-01T00:00:00Z")                                              // 1970-01-01T00:00:00Z
time.parse("jeudi, janv. 01, 1970", "EEEE, MMM dd, uuuu", "UTC", Locale.FRENCH) // 1970-01-01T00:00:00Z

range(Date date, String unit, ZoneId timeZone)
range(Date date, String unit, String timeZoneString)
range(Instant instant, String unit, ZoneId timeZone)
range(Instant instant, String unit, String timeZoneString)
range(String dateString, String unit, ZoneId timeZone)
range(String dateString, String unit, String timeZoneString)
range(Date date, String unit, ZoneId timeZone, long offset)
range(Date date, String unit, String timeZoneString, long offset)
range(Instant instant, String unit, ZoneId timeZone, long offset)
range(Instant instant, String unit, String timeZoneString, long offset)
range(String dateString, String unit, ZoneId timeZone, long offset)
range(String dateString, String unit, String timeZoneString, long offset)

Returns a new com.kineticdata.bundles.Time.Range instance representing the start and end of the specified time unit. If an offset is passed, it is applied to the reference date prior to calculating the start and end (so, passing a unit of "month" and an offset of -1 would return a range representing the start and end of "last month" and using an offset of +1 would return a range representing the start and end of "next month").

time.range("2015-11-01T06:59:59.000Z", "day", "America/Chicago")    // 2015-11-01T05:00:00Z -> 2015-11-02T06:00:00Z
time.range("2015-11-01T06:59:59.000Z", "day", "America/Chicago", 1) // 2015-11-02T05:00:00Z -> 2015-11-03T06:00:00Z
<c:set var="range" value="${time.range('2015-11-01T06:59:59Z', 'day', 'America/Chicago')}"/>
${time.format(range.start)} -> ${time.format(range.end)}

startOf(Date date, String unit, ZoneId timeZone)
startOf(Date date, String unit, String timeZoneString)
startOf(Instant instant, String unit, ZoneId timeZone)
startOf(Instant instant, String unit, String timeZoneString)
startOf(String dateString, String unit, ZoneId timeZone)
startOf(String dateString, String unit, String timeZoneString)
startOf(Date date, String unit, ZoneId timeZone, long offset)
startOf(Date date, String unit, String timeZoneString, long offset)
startOf(Instant instant, String unit, ZoneId timeZone, long offset)
startOf(Instant instant, String unit, String timeZoneString, long offset)
startOf(String dateString, String unit, ZoneId timeZone, long offset)
startOf(String dateString, String unit, String timeZoneString, long offset)

Returns a new java.time.Instant representing the start of the specified time unit. A time zone is required to correctly comput the end of a day/week/month/year (which have boundaries defined by the offset at that time).

time.startOf("2015-11-01T06:59:59.000Z", "millisecond", "America/Chicago") // 2015-11-01T06:59:59Z
time.startOf("2015-11-01T06:59:59.000Z", "second", "America/Chicago")      // 2015-11-01T06:59:59Z
time.startOf("2015-11-01T06:59:59.000Z", "minute", "America/Chicago")      // 2015-11-01T06:59:00Z
time.startOf("2015-11-01T06:59:59.000Z", "hour", "America/Chicago")        // 2015-11-01T06:00:00Z
time.startOf("2015-11-01T06:59:59.000Z", "day", "America/Chicago")         // 2015-11-01T05:00:00Z
time.startOf("2015-11-01T06:59:59.000Z", "week", "America/Chicago")        // 2015-10-26T05:00:00Z
time.startOf("2015-11-01T06:59:59.000Z", "month", "America/Chicago")       // 2015-11-01T05:00:00Z
time.startOf("2015-11-01T06:59:59.000Z", "year", "America/Chicago")        // 2015-01-01T06:00:00Z

subtract(Date date, long number, String unit, ZoneId timeZone)
subtract(Date date, long number, String unit, String timeZoneString)
subtract(Instant instant, long number, String unit, ZoneId timeZone)
subtract(Instant instant, long number, String unit, String timeZoneString)
subtract(String dateString, long number, String unit, ZoneId timeZone)
subtract(String dateString, long number, String unit, String timeZoneString)

Returns a new java.time.Instant representing an instant with the specified number of time units subtracted (the number can be negative, which effectively adds a number of time units from the specified date).

time.subtract(EPOCH, 1, "milliseconds", "America/Chicago") // 1969-12-31T23:59:59.999Z
time.subtract(EPOCH, 1, "seconds", "America/Chicago")      // 1969-12-31T23:59:59Z
time.subtract(EPOCH, 1, "minutes", "America/Chicago")      // 1969-12-31T23:59:00Z
time.subtract(EPOCH, 1, "hours", "America/Chicago")        // 1969-12-31T23:00:00Z
time.subtract(EPOCH, 1, "days", "America/Chicago")         // 1969-12-31T00:00:00Z
time.subtract(EPOCH, 1, "weeks", "America/Chicago")        // 1969-12-25T00:00:00Z
time.subtract(EPOCH, 1, "months", "America/Chicago")       // 1969-12-01T00:00:00Z
time.subtract(EPOCH, 1, "years", "America/Chicago")        // 1969-01-01T00:00:00Z

toEpochMillisecond(Date date)
toEpochMillisecond(Instant instant)
toEpochMillisecond(String dateString)

Returns a java.lang.Long representing the number of milliseconds that have passed between epoch (January 1st, 1970) and the specified date.

time.toEpochMillisecond(EPOCH)                      // 0
time.toEpochMillisecond("2015-11-01T06:59:59.000Z") // 1446361199000

toEpochSecond(Date date)
toEpochSecond(Instant instant)
toEpochSecond(String dateString)

Returns a java.lang.Long representing the number of seconds that have passed between epoch (January 1st, 1970) and the specified date.

time.toEpochSecond(EPOCH)                      // 0
time.toEpochSecond("2015-11-01T06:59:59.000Z") // 1446361199

Related