dates.java

非常接近C/S操作方式的Java Ajax框架－ZK 用ZK框架使你的B/S应用程序更漂亮更易操作。 官网：www.zkoss.org

/*	Dates.java

{{IS_NOTE

	Purpose:
	Description:
	History:
		2001/12/3, Henri Chen: Created.

}}IS_NOTE

Copyright (C) 2001 Potix Corporation. All Rights Reserved.

{{IS_RIGHT
	This program is distributed under GPL Version 2.0 in the hope that
	it will be useful, but WITHOUT ANY WARRANTY.
}}IS_RIGHT
*/

package org.zkoss.util;

import java.util.Date;
import java.util.Calendar;
import java.util.TimeZone;
import java.util.Locale;

import org.zkoss.lang.SystemException;

/**
 * Utilities for java.util.Date
 *
 * @author henrichen
 * @author tomyeh
 */
public class Dates {
	/**
	 * Truncates date to the nearest precision milliseconds. MS SQLServer2000
	 * with only the maximum accuracy of 1/300 seconds would not be able to
	 * store up to one millisecond accurarcy. That is, User must round the
	 * millisecond to some less precisions; or the data in that db would be
	 * inconsistence with that in memory.
	 * It is useful to store a Date object in a database.
	 * Without rounding, if you want to get it back and compare with the
	 * one in the memory. See {@link #now} for details.
	 *
	 * @param precision the divider of the precision(e.g. 10 for precision
	 * of 10 milliseconds;i.e. all millisecond less than 10 would be truncated)
	 * @see #now
	 * @see #round(long, int)
	 */
	public static final Date round(Date date, int precision) {
		date.setTime(round(date.getTime(), precision));
		return date;
	}
	/**
	 * Rounds a date represented in long to the specified precision of
	 * milliseconds.
	 *
	 * @param time the date represented in long.
	 * @param precision the divider of the precision(e.g. 10 for precision
	 * of 10 milliseconds;i.e. all millisecond less than 10 would be truncated)
	 * @see #now
	 * @see #round(Date, int)
	 */
	public static final long round(long time, int precision) {
		return time - (time % precision);
	}
	/** Tests whether a date is rounded.
	 * It is mainly used for debugging.
	 */
	public static final boolean isRounded(Date date, int precision) {
		return (date.getTime() % precision) == 0;
	}
	/** Returns the current time but rounding to the specified precision
	 * of milliseconds. It is useful if you want to create the current time
	 * which will be stored in the database and want to compare it with
	 * something with what you store in the database. Otherwise, that you
	 * get back the one you store might be different, because the resolution
	 * of database timestamp is usually less than one milisecond,
	 * e.g., MS SQL: 0.003 second.
	 *
	 * <p>If you don't cache it in the memory (remember entity beans
	 * always cache by the container), you don't need to round. If you
	 * are not sure, round it.
	 *
	 * @see #round(Date, int)
	 */
	public static final Date now(int precision) {
		return new Date(round(System.currentTimeMillis(), precision));
	}
	/** Returns the current time without rounding.
	 */
	public static final Date now() {
		return new Date();
	}
	/** Returns today by setting time to 0:0:0.
	 */
	public static final Date today() {
		return beginOfDate(new Date(), null);
	}

	/**
	 * Given a date, return the previouse date of the given date (24 hrs before).
	 */
	final public static Date previousDate(Date when) {
		long time = when.getTime() - 24*60*60*1000;
		return new Date(time);
	}

	/**
	 * Return the beginning date of this month.
	 */
	final public static Date beginOfMonth() {
		return beginOfMonth(new Date(), null);
	}
	/**
	 * Given a date, a proper TimeZone, return the beginning date of the 
	 * month of the specified date and TimeZone.
	 * If TimeZone is null, meaning use default TimeZone of the JVM.
	 */
	final public static Date beginOfMonth(Date when, TimeZone tz) {
		if (tz == null)
			tz = TimeZones.getCurrent();
		final Calendar cal = Calendar.getInstance(tz);
		cal.setTimeInMillis(when.getTime()); //don't call cal.setTime(Date) which will reset the TimeZone.

		final int year = cal.get(Calendar.YEAR);
		final int month = cal.get(Calendar.MONTH);
		cal.clear();
		cal.set(year, month, 1);
		return cal.getTime();
	}
	
	/**
	 * Return the ending date of this month.
	 */
	final public static Date endOfMonth() {
		return endOfMonth(new Date(), null);
	}
	/**
	 * Given a date, a proper TimeZone, return the ending date of the 
	 * month of the specified date and TimeZone.
	 * If TimeZone is null, meaning use default TimeZone of the JVM.
	 */
	final public static Date endOfMonth(Date when, TimeZone tz) {
		if (tz == null)
			tz = TimeZones.getCurrent();
		final Calendar cal = Calendar.getInstance(tz);
		cal.setTimeInMillis(when.getTime()); //don't call cal.setTime(Date) which will reset the TimeZone.

		final int year = cal.get(Calendar.YEAR);
		final int month = cal.get(Calendar.MONTH);
		final int monthDays = cal.getActualMaximum(Calendar.DAY_OF_MONTH);
		cal.clear();
		cal.set(year, month, monthDays + 1);
		cal.setTimeInMillis(cal.getTimeInMillis() - 1);		
		return cal.getTime();
	}

	/**
	 * Whether the given date in the specified TimeZone is the last day of that 
	 * month. If TimeZone is null, meaning use default TimeZone of the JVM.
	 */
	final public static boolean isEndOfMonth(Date when, TimeZone tz) {
		if (tz == null)
			tz = TimeZones.getCurrent();
		final Calendar cal = Calendar.getInstance(tz);
		cal.setTimeInMillis(when.getTime()); //don't call cal.setTime(Date) which will reset the TimeZone.

		final int day = cal.get(Calendar.DAY_OF_MONTH);
		final int maxDay = cal.getActualMaximum(Calendar.DAY_OF_MONTH);
		return day == maxDay;
	}


	/**
	 * Whether the given date in the specified TimeZone is the first day of that 
	 * month. If TimeZone is null, meaning use default TimeZone of the JVM.
	 */
	final public static boolean isBeginOfMonth(Date when, TimeZone tz) {
		if (tz == null)
			tz = TimeZones.getCurrent();
		final Calendar cal = Calendar.getInstance(tz);
		cal.setTimeInMillis(when.getTime()); //don't call cal.setTime(Date) which will reset the TimeZone.

		final int day = cal.get(Calendar.DAY_OF_MONTH);
		return day == 1;
	}
	/**
	 * Given a date, a proper TimeZone, return the beginning date of 
	 * the specified date and TimeZone. If TimeZone is null, meaning use Defult
	 * TimeZone of the JVM.
	 */
	final public static Date beginOfDate(Date when, TimeZone tz) {
		if (tz == null)
			tz = TimeZones.getCurrent();

		final Calendar cal = Calendar.getInstance(tz);
		cal.setTimeInMillis(when.getTime());//don't call cal.setTime(Date) which will reset the TimeZone.
		final int day = cal.get(Calendar.DAY_OF_MONTH);
		final int year = cal.get(Calendar.YEAR);
		final int month = cal.get(Calendar.MONTH);
		cal.clear();
		cal.set(year, month, day);
		
		return cal.getTime();
	}

	/**
	 * Given a date, a proper TimeZone, return the last millisecond date of 
	 * the specified date and TimeZone. If TimeZone is null, meaning use Defult
	 * TimeZone of the JVM.
	 */
	final public static Date endOfDate(Date when, TimeZone tz) {
		if (tz == null)
			tz = TimeZones.getCurrent();

		final Calendar cal = Calendar.getInstance(tz);
		cal.setTimeInMillis(when.getTime());//don't call cal.setTime(Date) which will reset the TimeZone.
		final int day = cal.get(Calendar.DAY_OF_MONTH);
		final int year = cal.get(Calendar.YEAR);
		final int month = cal.get(Calendar.MONTH);
		cal.clear();
		cal.set(year, month, day + 1);
		cal.setTimeInMillis(cal.getTimeInMillis() - 1);
		
		return cal.getTime();
	}
	
	/**
	 * Return the beginning date of this year.
	 */
	final public static Date beginOfYear() {
		return beginOfYear(new Date(), null);
	}
	/**
	 * Given a date, a proper TimeZone, return the beginning date of the 
	 * month of the specified date and TimeZone.
	 * If TimeZone is null, meaning use default TimeZone of the JVM.
	 */
	final public static Date beginOfYear(Date when, TimeZone tz) {
		if (tz == null)
			tz = TimeZones.getCurrent();
		final Calendar cal = Calendar.getInstance(tz);
		cal.setTimeInMillis(when.getTime()); //don't call cal.setTime(Date) which will reset the TimeZone.

		final int year = cal.get(Calendar.YEAR);
		cal.clear();
		cal.set(year, Calendar.JANUARY, 1);
		return cal.getTime();
	}	
	/**
	 * Return the ending date of this year.
	 */
	final public static Date endOfYear() {
		return endOfYear(new Date(), null);
	}
	/**
	 * Given a date, a proper TimeZone, return the ending date of the 
	 * month of the specified date and TimeZone.
	 * If TimeZone is null, meaning use default TimeZone of the JVM.
	 */
	final public static Date endOfYear(Date when, TimeZone tz) {
		if (tz == null)
			tz = TimeZones.getCurrent();
		final Calendar cal = Calendar.getInstance(tz);
		cal.setTimeInMillis(when.getTime()); //don't call cal.setTime(Date) which will reset the TimeZone.

		final int year = cal.get(Calendar.YEAR);
		cal.clear();
		cal.set(year + 1, Calendar.JANUARY, 1);