datetool.java

一个用于java web页面开发的开源包

package org.apache.velocity.tools.generic;

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */

import java.lang.reflect.Field;
import java.text.DateFormat;
import java.text.SimpleDateFormat;
import java.util.Date;
import java.util.Calendar;
import java.util.Locale;
import java.util.Map;
import java.util.TimeZone;


/**
 * Tool for working with {@link Date} and {@link Calendar}
 * in Velocity templates.  It is useful for accessing and
 * formatting the "current" date as well as for formatting
 * arbitrary {@link Date} and {@link Calendar} objects. Also
 * the tool can be used to retrieve {@link DateFormat} instances
 * or make conversions to and from various date types.
 * <p><pre>
 * Example of formatting the "current" date:
 *  $date                         -> Oct 19, 2003 9:54:50 PM
 *  $date.long                    -> October 19, 2003 9:54:50 PM PDT
 *  $date.medium_time             -> 9:54:50 PM
 *  $date.full_date               -> Sunday, October 19, 2003
 *  $date.get('default','short')  -> Oct 19, 2003 9:54 PM
 *  $date.get('yyyy-M-d H:m:s')   -> 2003-10-19 21:54:50
 *
 * Example of formatting an arbitrary date:
 *  $myDate                        -> Tue Oct 07 03:14:50 PDT 2003
 *  $date.format('medium',$myDate) -> Oct 7, 2003 3:14:50 AM
 *
 * Example toolbox.xml config (if you want to use this with VelocityView):
 * &lt;tool&gt;
 *   &lt;key&gt;date&lt;/key&gt;
 *   &lt;scope&gt;application&lt;/scope&gt;
 *   &lt;class&gt;org.apache.velocity.tools.generic.DateTool&lt;/class&gt;
 *   &lt;parameter name="format" value="yyyy-M-d"/&gt;
 * &lt;/tool&gt;
 * </pre></p>
 *
 * <p>The methods of this tool are highly interconnected, and overriding
 * key methods provides an easy way to create subclasses that use
 * a non-default format, calendar, locale, or timezone.</p>
 *
 * @author Nathan Bubna
 * @since VelocityTools 1.0
 * @version $Revision: 493081 $ $Date: 2007-01-05 08:48:09 -0800 (Fri, 05 Jan 2007) $
 */
public class DateTool
{

    /**
     * The default format to be used when none is specified.
     * @since VelocityTools 1.1
     */
    public static final String DEFAULT_FORMAT = "default";

    /**
     * The key used for specifying a default format via toolbox params.
     * @since VelocityTools 1.3
     */
    public static final String DEFAULT_FORMAT_KEY = "format";

    private String format = DEFAULT_FORMAT;

    /**
     * Default constructor.
     */
    public DateTool()
    {
        // do nothing
    }

    /**
     * Looks for a default format value in the given params.
     * @since VelocityTools 1.3
     */
    public void configure(Map params)
    {
        ValueParser parser = new ValueParser(params);
        String format = parser.getString(DEFAULT_FORMAT_KEY);
        if (format != null)
        {
            setFormat(format);
        }
    }



    // ------------------------- system date access ------------------

    /**
     * @return the system's current time as the number of milliseconds
     * elapsed since January 1, 1970, 00:00:00 GMT.
     */
    public static final long getSystemTime()
    {
        return getSystemCalendar().getTime().getTime();
    }

    /**
     * @return the system's current time as a {@link Date}
     */
    public static final Date getSystemDate()
    {
        return getSystemCalendar().getTime();
    }


    /**
     * @return the system's current time as a {@link Calendar}
     */
    public static final Calendar getSystemCalendar()
    {
        return Calendar.getInstance();
    }


    // ------------------------- default parameter access ----------------

    /**
     * This implementation returns the default locale. Subclasses
     * may override this to return alternate locales. Please note that
     * doing so will affect all formatting methods where no locale is
     * specified in the parameters.
     *
     * @return the default {@link Locale}
     */
    public Locale getLocale()
    {
        return Locale.getDefault();
    }

    /**
     * This implementation returns the default TimeZone. Subclasses
     * may override this to return alternate timezones. Please note that
     * doing so will affect all formatting methods where no timezone is
     * specified in the parameters.
     *
     * @return the default {@link TimeZone}
     */
    public TimeZone getTimeZone()
    {
        return TimeZone.getDefault();
    }

    /**
     * Returns a {@link Date} derived from the result of {@link #getCalendar}
     *
     * @return a {@link Date} derived from the result of {@link #getCalendar}
     */
    public Date getDate()
    {
        return getCalendar().getTime();
    }

    /**
     * Returns a {@link Calendar} instance created using the timezone and
     * locale returned by getTimeZone() and getLocale().  This allows subclasses
     * to easily override the default locale and timezone used by this tool.
     *
     * <p>Sub-classes may override this method to return a Calendar instance
     * not based on the system date.
     * Doing so will also cause the getDate(), get(String), get(String,String),
     * and toString() methods to return dates equivalent to the Calendar
     * returned by this method, because those methods return values derived
     * from the result of this method.</p>
     *
     * @return a {@link Calendar} instance created using the results of
     *         {@link #getTimeZone()} and {@link #getLocale()}.
     * @see Calendar#getInstance(TimeZone zone, Locale aLocale)
     */
    public Calendar getCalendar()
    {
        return Calendar.getInstance(getTimeZone(), getLocale());
    }

    /**
     * Return the pattern or style to be used for formatting dates when none
     * is specified. This implementation gives a 'default' date-time format.
     * Subclasses may override this to provide a different default format.
     *
     * <p>This can now be configured via the toolbox definition.
     * Add a <code>&lt;parameter name="format" value="short"/&gt;<code>
     * to your date tool configuration.</p>
     *
     * @since VelocityTools 1.1
     */
    public String getFormat()
    {
        return format;
    }

    /**
     * Sets the default format for this instance. This is protected,
     * because templates ought not to be using it; hat would not
     * be threadsafe so far as templates are concerned.
     *
     * @since VelocityTools 1.3
     */
    protected void setFormat(String format)
    {
        this.format = format;
    }

    // ------------------------- date value access ---------------------------

    /**
     * Returns the year value of the date returned by {@link #getCalendar()}.
     *
     * @since VelocityTools 1.2
     */
    public Integer getYear()
    {
        return getYear(getCalendar());
    }

    /**
     * Returns the year value of the specified date.
     *
     * @since VelocityTools 1.2
     */
    public Integer getYear(Object date)
    {
        return getValue(Calendar.YEAR, date);
    }

    /**
     * Returns the month value of the date returned by {@link #getCalendar()}.
     *
     * @since VelocityTools 1.2
     */
    public Integer getMonth()
    {
        return getMonth(getCalendar());
    }

    /**
     * Returns the month value of the specified date.
     *
     * @since VelocityTools 1.2
     */
    public Integer getMonth(Object date)
    {
        return getValue(Calendar.MONTH, date);
    }

    /**
     * Returns the day (of the month) value of the date
     * returned by {@link #getCalendar()}.
     * <br><br>
     * NOTE: Unlike java.util.Date, this returns the day of the month.
     * It is equivalent to Date.getDate() and
     * Calendar.get(Calendar.DAY_OF_MONTH).  We could not call this method
     * getDate() because that already exists in this class with a different
     * function.
     *
     * @since VelocityTools 1.2
     */
    public Integer getDay()
    {
        return getDay(getCalendar());
    }

    /**
     * Returns the day (of the month) value for the specified date.
     * <br><br>
     * NOTE: Unlike java.util.Date, this returns the day of the month.
     * It is equivalent to Date.getDate() and
     * Calendar.get(Calendar.DAY_OF_MONTH).  We could not call this method
     * getDate() because that already exists in this class with a different
     * function.
     *
     * @since VelocityTools 1.2
     */
    public Integer getDay(Object date)
    {
        return getValue(Calendar.DAY_OF_MONTH, date);
    }

    /**
     * Return the specified value of the date returned by
     * {@link #getCalendar()} or null if the field is invalid.
     *
     * @since VelocityTools 1.2
     */
    public Integer getValue(Object field)