001: package org.apache.lucene.document;
002:
003: /**
004: * Licensed to the Apache Software Foundation (ASF) under one or more
005: * contributor license agreements. See the NOTICE file distributed with
006: * this work for additional information regarding copyright ownership.
007: * The ASF licenses this file to You under the Apache License, Version 2.0
008: * (the "License"); you may not use this file except in compliance with
009: * the License. You may obtain a copy of the License at
010: *
011: * http://www.apache.org/licenses/LICENSE-2.0
012: *
013: * Unless required by applicable law or agreed to in writing, software
014: * distributed under the License is distributed on an "AS IS" BASIS,
015: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
016: * See the License for the specific language governing permissions and
017: * limitations under the License.
018: */
019:
020: import java.text.ParseException;
021: import java.text.SimpleDateFormat;
022: import java.util.Calendar;
023: import java.util.Date;
024: import java.util.TimeZone;
025:
026: /**
027: * Provides support for converting dates to strings and vice-versa.
028: * The strings are structured so that lexicographic sorting orders
029: * them by date, which makes them suitable for use as field values
030: * and search terms.
031: *
032: * <P>This class also helps you to limit the resolution of your dates. Do not
033: * save dates with a finer resolution than you really need, as then
034: * RangeQuery and PrefixQuery will require more memory and become slower.
035: *
036: * <P>Compared to {@link DateField} the strings generated by the methods
037: * in this class take slightly more space, unless your selected resolution
038: * is set to <code>Resolution.DAY</code> or lower.
039: */
040: public class DateTools {
041:
042: private final static TimeZone GMT = TimeZone.getTimeZone("GMT");
043:
044: private static final SimpleDateFormat YEAR_FORMAT = new SimpleDateFormat(
045: "yyyy");
046: private static final SimpleDateFormat MONTH_FORMAT = new SimpleDateFormat(
047: "yyyyMM");
048: private static final SimpleDateFormat DAY_FORMAT = new SimpleDateFormat(
049: "yyyyMMdd");
050: private static final SimpleDateFormat HOUR_FORMAT = new SimpleDateFormat(
051: "yyyyMMddHH");
052: private static final SimpleDateFormat MINUTE_FORMAT = new SimpleDateFormat(
053: "yyyyMMddHHmm");
054: private static final SimpleDateFormat SECOND_FORMAT = new SimpleDateFormat(
055: "yyyyMMddHHmmss");
056: private static final SimpleDateFormat MILLISECOND_FORMAT = new SimpleDateFormat(
057: "yyyyMMddHHmmssSSS");
058: static {
059: // times need to be normalized so the value doesn't depend on the
060: // location the index is created/used:
061: YEAR_FORMAT.setTimeZone(GMT);
062: MONTH_FORMAT.setTimeZone(GMT);
063: DAY_FORMAT.setTimeZone(GMT);
064: HOUR_FORMAT.setTimeZone(GMT);
065: MINUTE_FORMAT.setTimeZone(GMT);
066: SECOND_FORMAT.setTimeZone(GMT);
067: MILLISECOND_FORMAT.setTimeZone(GMT);
068: }
069:
070: // cannot create, the class has static methods only
071: private DateTools() {
072: }
073:
074: /**
075: * Converts a Date to a string suitable for indexing.
076: *
077: * @param date the date to be converted
078: * @param resolution the desired resolution, see
079: * {@link #round(Date, DateTools.Resolution)}
080: * @return a string in format <code>yyyyMMddHHmmssSSS</code> or shorter,
081: * depeding on <code>resolution</code>; using UTC as timezone
082: */
083: public static String dateToString(Date date, Resolution resolution) {
084: return timeToString(date.getTime(), resolution);
085: }
086:
087: /**
088: * Converts a millisecond time to a string suitable for indexing.
089: *
090: * @param time the date expressed as milliseconds since January 1, 1970, 00:00:00 GMT
091: * @param resolution the desired resolution, see
092: * {@link #round(long, DateTools.Resolution)}
093: * @return a string in format <code>yyyyMMddHHmmssSSS</code> or shorter,
094: * depeding on <code>resolution</code>; using UTC as timezone
095: */
096: public static String timeToString(long time, Resolution resolution) {
097: Calendar cal = Calendar.getInstance(GMT);
098:
099: //protected in JDK's prior to 1.4
100: //cal.setTimeInMillis(round(time, resolution));
101:
102: cal.setTime(new Date(round(time, resolution)));
103:
104: String result;
105: if (resolution == Resolution.YEAR) {
106: synchronized (YEAR_FORMAT) {
107: result = YEAR_FORMAT.format(cal.getTime());
108: }
109: } else if (resolution == Resolution.MONTH) {
110: synchronized (MONTH_FORMAT) {
111: result = MONTH_FORMAT.format(cal.getTime());
112: }
113: } else if (resolution == Resolution.DAY) {
114: synchronized (DAY_FORMAT) {
115: result = DAY_FORMAT.format(cal.getTime());
116: }
117: } else if (resolution == Resolution.HOUR) {
118: synchronized (HOUR_FORMAT) {
119: result = HOUR_FORMAT.format(cal.getTime());
120: }
121: } else if (resolution == Resolution.MINUTE) {
122: synchronized (MINUTE_FORMAT) {
123: result = MINUTE_FORMAT.format(cal.getTime());
124: }
125: } else if (resolution == Resolution.SECOND) {
126: synchronized (SECOND_FORMAT) {
127: result = SECOND_FORMAT.format(cal.getTime());
128: }
129: } else if (resolution == Resolution.MILLISECOND) {
130: synchronized (MILLISECOND_FORMAT) {
131: result = MILLISECOND_FORMAT.format(cal.getTime());
132: }
133: } else {
134: throw new IllegalArgumentException("unknown resolution "
135: + resolution);
136: }
137: return result;
138: }
139:
140: /**
141: * Converts a string produced by <code>timeToString</code> or
142: * <code>dateToString</code> back to a time, represented as the
143: * number of milliseconds since January 1, 1970, 00:00:00 GMT.
144: *
145: * @param dateString the date string to be converted
146: * @return the number of milliseconds since January 1, 1970, 00:00:00 GMT
147: * @throws ParseException if <code>dateString</code> is not in the
148: * expected format
149: */
150: public static long stringToTime(String dateString)
151: throws ParseException {
152: return stringToDate(dateString).getTime();
153: }
154:
155: /**
156: * Converts a string produced by <code>timeToString</code> or
157: * <code>dateToString</code> back to a time, represented as a
158: * Date object.
159: *
160: * @param dateString the date string to be converted
161: * @return the parsed time as a Date object
162: * @throws ParseException if <code>dateString</code> is not in the
163: * expected format
164: */
165: public static Date stringToDate(String dateString)
166: throws ParseException {
167: Date date;
168: if (dateString.length() == 4) {
169: synchronized (YEAR_FORMAT) {
170: date = YEAR_FORMAT.parse(dateString);
171: }
172: } else if (dateString.length() == 6) {
173: synchronized (MONTH_FORMAT) {
174: date = MONTH_FORMAT.parse(dateString);
175: }
176: } else if (dateString.length() == 8) {
177: synchronized (DAY_FORMAT) {
178: date = DAY_FORMAT.parse(dateString);
179: }
180: } else if (dateString.length() == 10) {
181: synchronized (HOUR_FORMAT) {
182: date = HOUR_FORMAT.parse(dateString);
183: }
184: } else if (dateString.length() == 12) {
185: synchronized (MINUTE_FORMAT) {
186: date = MINUTE_FORMAT.parse(dateString);
187: }
188: } else if (dateString.length() == 14) {
189: synchronized (SECOND_FORMAT) {
190: date = SECOND_FORMAT.parse(dateString);
191: }
192: } else if (dateString.length() == 17) {
193: synchronized (MILLISECOND_FORMAT) {
194: date = MILLISECOND_FORMAT.parse(dateString);
195: }
196: } else {
197: throw new ParseException("Input is not valid date string: "
198: + dateString, 0);
199: }
200: return date;
201: }
202:
203: /**
204: * Limit a date's resolution. For example, the date <code>2004-09-21 13:50:11</code>
205: * will be changed to <code>2004-09-01 00:00:00</code> when using
206: * <code>Resolution.MONTH</code>.
207: *
208: * @param resolution The desired resolution of the date to be returned
209: * @return the date with all values more precise than <code>resolution</code>
210: * set to 0 or 1
211: */
212: public static Date round(Date date, Resolution resolution) {
213: return new Date(round(date.getTime(), resolution));
214: }
215:
216: /**
217: * Limit a date's resolution. For example, the date <code>1095767411000</code>
218: * (which represents 2004-09-21 13:50:11) will be changed to
219: * <code>1093989600000</code> (2004-09-01 00:00:00) when using
220: * <code>Resolution.MONTH</code>.
221: *
222: * @param resolution The desired resolution of the date to be returned
223: * @return the date with all values more precise than <code>resolution</code>
224: * set to 0 or 1, expressed as milliseconds since January 1, 1970, 00:00:00 GMT
225: */
226: public static long round(long time, Resolution resolution) {
227: Calendar cal = Calendar.getInstance(GMT);
228:
229: // protected in JDK's prior to 1.4
230: //cal.setTimeInMillis(time);
231:
232: cal.setTime(new Date(time));
233:
234: if (resolution == Resolution.YEAR) {
235: cal.set(Calendar.MONTH, 0);
236: cal.set(Calendar.DAY_OF_MONTH, 1);
237: cal.set(Calendar.HOUR_OF_DAY, 0);
238: cal.set(Calendar.MINUTE, 0);
239: cal.set(Calendar.SECOND, 0);
240: cal.set(Calendar.MILLISECOND, 0);
241: } else if (resolution == Resolution.MONTH) {
242: cal.set(Calendar.DAY_OF_MONTH, 1);
243: cal.set(Calendar.HOUR_OF_DAY, 0);
244: cal.set(Calendar.MINUTE, 0);
245: cal.set(Calendar.SECOND, 0);
246: cal.set(Calendar.MILLISECOND, 0);
247: } else if (resolution == Resolution.DAY) {
248: cal.set(Calendar.HOUR_OF_DAY, 0);
249: cal.set(Calendar.MINUTE, 0);
250: cal.set(Calendar.SECOND, 0);
251: cal.set(Calendar.MILLISECOND, 0);
252: } else if (resolution == Resolution.HOUR) {
253: cal.set(Calendar.MINUTE, 0);
254: cal.set(Calendar.SECOND, 0);
255: cal.set(Calendar.MILLISECOND, 0);
256: } else if (resolution == Resolution.MINUTE) {
257: cal.set(Calendar.SECOND, 0);
258: cal.set(Calendar.MILLISECOND, 0);
259: } else if (resolution == Resolution.SECOND) {
260: cal.set(Calendar.MILLISECOND, 0);
261: } else if (resolution == Resolution.MILLISECOND) {
262: // don't cut off anything
263: } else {
264: throw new IllegalArgumentException("unknown resolution "
265: + resolution);
266: }
267: return cal.getTime().getTime();
268: }
269:
270: /** Specifies the time granularity. */
271: public static class Resolution {
272:
273: public static final Resolution YEAR = new Resolution("year");
274: public static final Resolution MONTH = new Resolution("month");
275: public static final Resolution DAY = new Resolution("day");
276: public static final Resolution HOUR = new Resolution("hour");
277: public static final Resolution MINUTE = new Resolution("minute");
278: public static final Resolution SECOND = new Resolution("second");
279: public static final Resolution MILLISECOND = new Resolution(
280: "millisecond");
281:
282: private String resolution;
283:
284: private Resolution() {
285: }
286:
287: private Resolution(String resolution) {
288: this .resolution = resolution;
289: }
290:
291: public String toString() {
292: return resolution;
293: }
294:
295: }
296:
297: }
|