Package org.apache.lucene.document

Class DateTools

  • public class DateTools
extends java.lang.Object
    Provides support for converting dates to strings and vice-versa. The strings are structured so that lexicographic sorting orders them by date, which makes them suitable for use as field values and search terms.

    This class also helps you to limit the resolution of your dates. Do not save dates with a finer resolution than you really need, as then TermRangeQuery and PrefixQuery will require more memory and become slower.

    Another approach is NumericUtils, which provides a sortable binary representation (prefix encoded) of numeric values, which date/time are. For indexing a Date or Calendar, just get the unix timestamp as long using Date.getTime() or Calendar.getTimeInMillis() and index this as a numeric value with LongField and use NumericRangeQuery to query it.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  DateTools.Resolution
      Specifies the time granularity.

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static java.lang.String dateToString​(java.util.Date date, DateTools.Resolution resolution)
      Converts a Date to a string suitable for indexing.
      static long round​(long time, DateTools.Resolution resolution)
      Limit a date's resolution.
      static java.util.Date round​(java.util.Date date, DateTools.Resolution resolution)
      Limit a date's resolution.
      static java.util.Date stringToDate​(java.lang.String dateString)
      Converts a string produced by timeToString or dateToString back to a time, represented as a Date object.
      static long stringToTime​(java.lang.String dateString)
      Converts a string produced by timeToString or dateToString back to a time, represented as the number of milliseconds since January 1, 1970, 00:00:00 GMT.
      static java.lang.String timeToString​(long time, DateTools.Resolution resolution)
      Converts a millisecond time to a string suitable for indexing.

      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • dateToString

        public static java.lang.String dateToString​(java.util.Date date,
                                            DateTools.Resolution resolution)
        Converts a Date to a string suitable for indexing.
        Parameters:
        date - the date to be converted
        resolution - the desired resolution, see round(Date, DateTools.Resolution)
        Returns:
        a string in format yyyyMMddHHmmssSSS or shorter, depending on resolution; using GMT as timezone

      • timeToString

        public static java.lang.String timeToString​(long time,
                                            DateTools.Resolution resolution)
        Converts a millisecond time to a string suitable for indexing.
        Parameters:
        time - the date expressed as milliseconds since January 1, 1970, 00:00:00 GMT
        resolution - the desired resolution, see round(long, DateTools.Resolution)
        Returns:
        a string in format yyyyMMddHHmmssSSS or shorter, depending on resolution; using GMT as timezone

      • stringToTime

        public static long stringToTime​(java.lang.String dateString)
                         throws java.text.ParseException
        Converts a string produced by timeToString or dateToString back to a time, represented as the number of milliseconds since January 1, 1970, 00:00:00 GMT.
        Parameters:
        dateString - the date string to be converted
        Returns:
        the number of milliseconds since January 1, 1970, 00:00:00 GMT
        Throws:
        java.text.ParseException - if dateString is not in the expected format

      • stringToDate

        public static java.util.Date stringToDate​(java.lang.String dateString)
                                   throws java.text.ParseException
        Converts a string produced by timeToString or dateToString back to a time, represented as a Date object.
        Parameters:
        dateString - the date string to be converted
        Returns:
        the parsed time as a Date object
        Throws:
        java.text.ParseException - if dateString is not in the expected format

      • round

        public static java.util.Date round​(java.util.Date date,
                                   DateTools.Resolution resolution)
        Limit a date's resolution. For example, the date 2004-09-21 13:50:11 will be changed to 2004-09-01 00:00:00 when using Resolution.MONTH.
        Parameters:
        resolution - The desired resolution of the date to be returned
        Returns:
        the date with all values more precise than resolution set to 0 or 1

      • round

        public static long round​(long time,
                         DateTools.Resolution resolution)
        Limit a date's resolution. For example, the date 1095767411000 (which represents 2004-09-21 13:50:11) will be changed to 1093989600000 (2004-09-01 00:00:00) when using Resolution.MONTH.
        Parameters:
        resolution - The desired resolution of the date to be returned
        Returns:
        the date with all values more precise than resolution set to 0 or 1, expressed as milliseconds since January 1, 1970, 00:00:00 GMT