org.apache.solr.util

## Class DateMathParser

- java.lang.Object
- - org.apache.solr.util.DateMathParser

-     public class DateMathParser
      extends Object

  A Simple Utility class for parsing "math" like strings relating to Dates.

  The basic syntax support addition, subtraction and rounding at various levels of granularity (or "units"). Commands can be chained together and are parsed from left to right. '+' and '-' denote addition and subtraction, while '/' denotes "round". Round requires only a unit, while addition/subtraction require an integer value and a unit. Command strings must not include white space, but the "No-Op" command (empty string) is allowed....

         /HOUR
            ... Round to the start of the current hour
         /DAY
            ... Round to the start of the current day
         +2YEARS
            ... Exactly two years in the future from now
         -1DAY
            ... Exactly 1 day prior to now
         /DAY+6MONTHS+3DAYS
            ... 6 months and 3 days in the future from the start of
                the current day
         +6MONTHS+3DAYS/DAY
            ... 6 months and 3 days in the future from now, rounded
                down to nearest day

  (Multiple aliases exist for the various units of time (ie: `MINUTE` and `MINUTES`; `MILLI`, `MILLIS`, `MILLISECOND`, and `MILLISECONDS`.) The complete list can be found by inspecting the keySet of `CALENDAR_UNITS`)

  All commands are relative to a "now" which is fixed in an instance of DateMathParser such that `p.parseMath("+0MILLISECOND").equals(p.parseMath("+0MILLISECOND"))` no matter how many wall clock milliseconds elapse between the two distinct calls to parse (Assuming no other thread calls "`setNow`" in the interim). The default value of 'now' is the time at the moment the `DateMathParser` instance is constructed, unless overridden by the `NOW` request param.

  All commands are also affected to the rules of a specified `TimeZone` (including the start/end of DST if any) which determine when each arbitrary day starts. This not only impacts rounding/adding of DAYs, but also cascades to rounding of HOUR, MIN, MONTH, YEAR as well. The default `TimeZone` used is `UTC` unless overridden by the `TZ` request param.

  Historical dates: The calendar computation is completely done with the Gregorian system/algorithm. It does not switch to Julian or anything else, unlike the default `GregorianCalendar`.

  See Also:
    `SolrRequestInfo.getClientTimeZone()`, `SolrRequestInfo.getNOW()`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static Map<String,ChronoUnit>` | `CALENDAR_UNITS` A mapping from (uppercased) String labels identifying time units, to the corresponding `ChronoUnit` enum (e.g.
    `static TimeZone` | `DEFAULT_MATH_TZ` Default TimeZone for DateMath rounding (UTC)
    `static DateTimeFormatter` | `PARSER` Differs by `DateTimeFormatter.ISO_INSTANT` in that it's lenient.
    `static TimeZone` | `UTC`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DateMathParser()` Default constructor that assumes UTC should be used for rounding unless otherwise specified in the SolrRequestInfo
    `DateMathParser(TimeZone tz)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `Date` | `getNow()` Returns a clone of this instance's concept of "now" (never null).
    `TimeZone` | `getTimeZone()`
    `static Date` | `parseMath(Date now, String val)` Parses a String which may be a date (in the standard ISO-8601 format) followed by an optional math expression.
    `Date` | `parseMath(String math)` Parses a string of commands relative "now" are returns the resulting Date.
    `void` | `setNow(Date n)` Defines this instance's concept of "now".

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### UTC

          public static final TimeZone UTC

    - #### DEFAULT_MATH_TZ

          public static final TimeZone DEFAULT_MATH_TZ

      Default TimeZone for DateMath rounding (UTC)

    - #### PARSER

          public static final DateTimeFormatter PARSER

      Differs by `DateTimeFormatter.ISO_INSTANT` in that it's lenient.
      See Also:
        `parseNoMath(String)`

    - #### CALENDAR_UNITS

          public static final Map<String,ChronoUnit> CALENDAR_UNITS

      A mapping from (uppercased) String labels identifying time units, to the corresponding `ChronoUnit` enum (e.g. "YEARS") used to set/add/roll that unit of measurement.

      A single logical unit of time might be represented by multiple labels for convenience (ie: `DATE==DAYS`, `MILLI==MILLIS`)

      See Also:
        `Calendar`

  - ### Constructor Detail

    - #### DateMathParser

          public DateMathParser()

      Default constructor that assumes UTC should be used for rounding unless otherwise specified in the SolrRequestInfo
      See Also:
        `SolrRequestInfo.getClientTimeZone()`

    - #### DateMathParser

          public DateMathParser(TimeZone tz)

      Parameters:
        `tz` - The TimeZone used for rounding (to determine when hours/days begin). If null, then this method defaults to the value dictated by the SolrRequestInfo if it exists -- otherwise it uses UTC.
      See Also:
        `DEFAULT_MATH_TZ`, `Calendar.getInstance(TimeZone,Locale)`, `SolrRequestInfo.getClientTimeZone()`

  - ### Method Detail

    - #### parseMath

          public static Date parseMath(Date now,
                                       String val)

      Parses a String which may be a date (in the standard ISO-8601 format) followed by an optional math expression.
      Parameters:
        `now` - an optional fixed date to use as "NOW"
        `val` - the string to parse

    - #### getTimeZone

          public TimeZone getTimeZone()

      Returns:
        the time zone

    - #### setNow

          public void setNow(Date n)

      Defines this instance's concept of "now".
      See Also:
        `getNow()`

    - #### getNow

          public Date getNow()

      Returns a clone of this instance's concept of "now" (never null). If setNow was never called (or if null was specified) then this method first defines 'now' as the value dictated by the SolrRequestInfo if it exists -- otherwise it uses a new Date instance at the moment getNow() is first called.
      See Also:
        `setNow(java.util.Date)`, `SolrRequestInfo.getNOW()`

    - #### parseMath

          public Date parseMath(String math)
                         throws ParseException

      Parses a string of commands relative "now" are returns the resulting Date.
      Throws:
        `ParseException` - positions in ParseExceptions are token positions, not character positions.

Copyright © 2000-2016 Apache Software Foundation. All Rights Reserved.