001/* ===========================================================
002 * JFreeChart : a free chart library for the Java(tm) platform
003 * ===========================================================
004 *
005 * (C) Copyright 2000-2020, by Object Refinery Limited 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 * MonthDateFormat.java
029 * --------------------
030 * (C) Copyright 2005-2016, by Object Refinery Limited and Contributors.
031 *
032 * Original Author:  David Gilbert (for Object Refinery Limited);
033 * Contributor(s):   -;
034 *
035 * Changes:
036 * --------
037 * 10-May-2005 : Version 1 (DG);
038 * 02-Jul-2013 : Use ParamChecks (DG);
039 *
040 */
041
042package org.jfree.chart.axis;
043
044import java.text.DateFormat;
045import java.text.DateFormatSymbols;
046import java.text.FieldPosition;
047import java.text.NumberFormat;
048import java.text.ParsePosition;
049import java.text.SimpleDateFormat;
050import java.util.Arrays;
051import java.util.Calendar;
052import java.util.Date;
053import java.util.GregorianCalendar;
054import java.util.Locale;
055import java.util.TimeZone;
056import org.jfree.chart.util.Args;
057
058/**
059 * A formatter that formats dates to show the initial letter(s) of the month
060 * name and, as an option, the year for the first or last month of each year.
061 */
062public class MonthDateFormat extends DateFormat {
063
064    /** The symbols used for the months. */
065    private String[] months;
066
067    /** Flags that control which months will have the year appended. */
068    private boolean[] showYear;
069
070    /** The year formatter. */
071    private DateFormat yearFormatter;
072
073    /**
074     * Creates a new instance for the default time zone.
075     */
076    public MonthDateFormat() {
077        this(TimeZone.getDefault());
078    }
079
080    /**
081     * Creates a new instance for the specified time zone.
082     *
083     * @param zone  the time zone ({@code null} not permitted).
084     */
085    public MonthDateFormat(TimeZone zone) {
086        this(zone, Locale.getDefault(), 1, true, false);
087    }
088
089    /**
090     * Creates a new instance for the specified time zone.
091     *
092     * @param locale  the locale used to obtain the month
093     *                names ({@code null} not permitted).
094     */
095    public MonthDateFormat(Locale locale) {
096        this(TimeZone.getDefault(), locale, 1, true, false);
097    }
098
099    /**
100     * Creates a new instance for the specified time zone.
101     *
102     * @param zone  the time zone ({@code null} not permitted).
103     * @param chars  the maximum number of characters to use from the month
104     *               names (that are obtained from the date symbols of the
105     *               default locale).  If this value is <= 0, the entire
106     *               month name is used in each case.
107     */
108    public MonthDateFormat(TimeZone zone, int chars) {
109        this(zone, Locale.getDefault(), chars, true, false);
110    }
111
112    /**
113     * Creates a new instance for the specified time zone.
114     *
115     * @param locale  the locale ({@code null} not permitted).
116     * @param chars  the maximum number of characters to use from the month
117     *               names (that are obtained from the date symbols of the
118     *               default locale).  If this value is <= 0, the entire
119     *               month name is used in each case.
120     */
121    public MonthDateFormat(Locale locale, int chars) {
122        this(TimeZone.getDefault(), locale, chars, true, false);
123    }
124
125    /**
126     * Creates a new formatter.
127     *
128     * @param zone  the time zone used to extract the month and year from dates
129     *              passed to this formatter ({@code null} not permitted).
130     * @param locale  the locale used to determine the month names
131     *                ({@code null} not permitted).
132     * @param chars  the maximum number of characters to use from the month
133     *               names, or zero to indicate that the entire month name
134     *               should be used.
135     * @param showYearForJan  a flag that controls whether or not the year is
136     *                        appended to the symbol for the first month of
137     *                        each year.
138     * @param showYearForDec  a flag that controls whether or not the year is
139     *                        appended to the symbol for the last month of
140     *                        each year.
141     */
142    public MonthDateFormat(TimeZone zone, Locale locale, int chars,
143                           boolean showYearForJan, boolean showYearForDec) {
144        this(zone, locale, chars, new boolean[] {showYearForJan, false, false,
145            false, false, false, false, false, false, false, false, false,
146            showYearForDec}, new SimpleDateFormat("yy"));
147    }
148
149    /**
150     * Creates a new formatter.
151     *
152     * @param zone  the time zone used to extract the month and year from dates
153     *              passed to this formatter ({@code null} not permitted).
154     * @param locale  the locale used to determine the month names
155     *                ({@code null} not permitted).
156     * @param chars  the maximum number of characters to use from the month
157     *               names, or zero to indicate that the entire month name
158     *               should be used.
159     * @param showYear  an array of flags that control whether or not the
160     *                  year is displayed for a particular month.
161     * @param yearFormatter  the year formatter.
162     */
163    public MonthDateFormat(TimeZone zone, Locale locale, int chars,
164                           boolean[] showYear, DateFormat yearFormatter) {
165        Args.nullNotPermitted(locale, "locale");
166        DateFormatSymbols dfs = new DateFormatSymbols(locale);
167        String[] monthsFromLocale = dfs.getMonths();
168        this.months = new String[12];
169        for (int i = 0; i < 12; i++) {
170            if (chars > 0) {
171                this.months[i] = monthsFromLocale[i].substring(0,
172                        Math.min(chars, monthsFromLocale[i].length()));
173            }
174            else {
175                this.months[i] = monthsFromLocale[i];
176            }
177        }
178        this.calendar = new GregorianCalendar(zone);
179        this.showYear = showYear;
180        this.yearFormatter = yearFormatter;
181
182        // the following is never used, but it seems that DateFormat requires
183        // it to be non-null.  It isn't well covered in the spec, refer to
184        // bug parade 5061189 for more info.
185        this.numberFormat = NumberFormat.getNumberInstance();
186    }
187
188    /**
189     * Formats the given date.
190     *
191     * @param date  the date.
192     * @param toAppendTo  the string buffer.
193     * @param fieldPosition  the field position.
194     *
195     * @return The formatted date.
196     */
197    @Override
198    public StringBuffer format(Date date, StringBuffer toAppendTo,
199                               FieldPosition fieldPosition) {
200        this.calendar.setTime(date);
201        int month = this.calendar.get(Calendar.MONTH);
202        toAppendTo.append(this.months[month]);
203        if (this.showYear[month]) {
204            toAppendTo.append(this.yearFormatter.format(date));
205        }
206        return toAppendTo;
207    }
208
209    /**
210     * Parses the given string (not implemented).
211     *
212     * @param source  the date string.
213     * @param pos  the parse position.
214     *
215     * @return {@code null}, as this method has not been implemented.
216     */
217    @Override
218    public Date parse(String source, ParsePosition pos) {
219        return null;
220    }
221
222    /**
223     * Tests this formatter for equality with an arbitrary object.
224     *
225     * @param obj  the object.
226     *
227     * @return A boolean.
228     */
229    @Override
230    public boolean equals(Object obj) {
231        if (obj == this) {
232            return true;
233        }
234        if (!(obj instanceof MonthDateFormat)) {
235            return false;
236        }
237        if (!super.equals(obj)) {
238            return false;
239        }
240        MonthDateFormat that = (MonthDateFormat) obj;
241        if (!Arrays.equals(this.months, that.months)) {
242            return false;
243        }
244        if (!Arrays.equals(this.showYear, that.showYear)) {
245            return false;
246        }
247        if (!this.yearFormatter.equals(that.yearFormatter)) {
248            return false;
249        }
250        return true;
251    }
252}