001/* ===========================================================
002 * JFreeChart : a free chart library for the Java(tm) platform
003 * ===========================================================
004 *
005 * (C) Copyright 2000-present, by David Gilbert and Contributors.
006 *
007 * Project Info:  http://www.jfree.org/jfreechart/index.html
008 *
009 * This library is free software; you can redistribute it and/or modify it
010 * under the terms of the GNU Lesser General Public License as published by
011 * the Free Software Foundation; either version 2.1 of the License, or
012 * (at your option) any later version.
013 *
014 * This library is distributed in the hope that it will be useful, but
015 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
016 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
017 * License for more details.
018 *
019 * You should have received a copy of the GNU Lesser General Public
020 * License along with this library; if not, write to the Free Software
021 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301,
022 * USA.
023 *
024 * [Oracle and Java are registered trademarks of Oracle and/or its affiliates. 
025 * Other names may be trademarks of their respective owners.]
026 *
027 * ----------------------
028 * QuarterDateFormat.java
029 * ----------------------
030 * (C) Copyright 2005-present, by David Gilbert and Contributors.
031 *
032 * Original Author:  David Gilbert;
033 * Contributor(s):   -;
034 *
035 */
036
037package org.jfree.chart.axis;
038
039import java.io.Serializable;
040import java.text.DateFormat;
041import java.text.FieldPosition;
042import java.text.NumberFormat;
043import java.text.ParsePosition;
044import java.util.Arrays;
045import java.util.Calendar;
046import java.util.Date;
047import java.util.GregorianCalendar;
048import java.util.TimeZone;
049import org.jfree.chart.util.Args;
050
051/**
052 * A formatter that formats dates to show the year and quarter (for example,
053 * '2004 IV' for the last quarter of 2004.
054 */
055public class QuarterDateFormat extends DateFormat
056        implements Cloneable, Serializable {
057
058    /** For serialization. */
059    private static final long serialVersionUID = -6738465248529797176L;
060
061    /** Symbols for regular quarters. */
062    public static final String[] REGULAR_QUARTERS = new String[] {"1", "2",
063            "3", "4"};
064
065    /** Symbols for roman numbered quarters. */
066    public static final String[] ROMAN_QUARTERS  = new String[] {"I", "II",
067            "III", "IV"};
068
069    /** Symbols for greek numbered quarters. */
070    public static final String[] GREEK_QUARTERS = new String[] {"\u0391",
071            "\u0392", "\u0393", "\u0394"};
072
073    /** The strings. */
074    private String[] quarters = REGULAR_QUARTERS;
075
076    /** A flag that controls whether the quarter or the year goes first. */
077    private boolean quarterFirst;
078
079    /**
080     * Creates a new instance for the default time zone.
081     */
082    public QuarterDateFormat() {
083        this(TimeZone.getDefault());
084    }
085
086    /**
087     * Creates a new instance for the specified time zone.
088     *
089     * @param zone  the time zone ({@code null} not permitted).
090     */
091    public QuarterDateFormat(TimeZone zone) {
092        this(zone, REGULAR_QUARTERS);
093    }
094
095    /**
096     * Creates a new instance for the specified time zone.
097     *
098     * @param zone  the time zone ({@code null} not permitted).
099     * @param quarterSymbols  the quarter symbols.
100     */
101    public QuarterDateFormat(TimeZone zone, String[] quarterSymbols) {
102        this(zone, quarterSymbols, false);
103    }
104
105    /**
106     * Creates a new instance for the specified time zone.
107     *
108     * @param zone  the time zone ({@code null} not permitted).
109     * @param quarterSymbols  the quarter symbols.
110     * @param quarterFirst  a flag that controls whether the quarter or the
111     *         year is displayed first.
112     */
113    public QuarterDateFormat(TimeZone zone, String[] quarterSymbols,
114            boolean quarterFirst) {
115        Args.nullNotPermitted(zone, "zone");
116        this.calendar = new GregorianCalendar(zone);
117        this.quarters = quarterSymbols;
118        this.quarterFirst = quarterFirst;
119
120        // the following is never used, but it seems that DateFormat requires
121        // it to be non-null.  It isn't well covered in the spec, refer to
122        // bug parade 5061189 for more info.
123        this.numberFormat = NumberFormat.getNumberInstance();
124
125    }
126
127    /**
128     * Formats the given date.
129     *
130     * @param date  the date.
131     * @param toAppendTo  the string buffer.
132     * @param fieldPosition  the field position.
133     *
134     * @return The formatted date.
135     */
136    @Override
137    public StringBuffer format(Date date, StringBuffer toAppendTo,
138                               FieldPosition fieldPosition) {
139        this.calendar.setTime(date);
140        int year = this.calendar.get(Calendar.YEAR);
141        int month = this.calendar.get(Calendar.MONTH);
142        int quarter = month / 3;
143        if (this.quarterFirst) {
144            toAppendTo.append(this.quarters[quarter]);
145            toAppendTo.append(" ");
146            toAppendTo.append(year);
147        }
148        else {
149            toAppendTo.append(year);
150            toAppendTo.append(" ");
151            toAppendTo.append(this.quarters[quarter]);
152        }
153        return toAppendTo;
154    }
155
156    /**
157     * Parses the given string (not implemented).
158     *
159     * @param source  the date string.
160     * @param pos  the parse position.
161     *
162     * @return {@code null}, as this method has not been implemented.
163     */
164    @Override
165    public Date parse(String source, ParsePosition pos) {
166        return null;
167    }
168
169    /**
170     * Tests this formatter for equality with an arbitrary object.
171     *
172     * @param obj  the object ({@code null} permitted).
173     *
174     * @return A boolean.
175     */
176    @Override
177    public boolean equals(Object obj) {
178        if (obj == this) {
179            return true;
180        }
181        if (!(obj instanceof QuarterDateFormat)) {
182            return false;
183        }
184        QuarterDateFormat that = (QuarterDateFormat) obj;
185        if (!Arrays.equals(this.quarters, that.quarters)) {
186            return false;
187        }
188        if (this.quarterFirst != that.quarterFirst) {
189            return false;
190        }
191        return super.equals(obj);
192    }
193
194}