1 /*
2 * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
124 * to a {@link SimpleDateFormat}. This will work for the majority
125 * of countries; just remember to put it in a {@code try} block in case you
126 * encounter an unusual one.
127 *
128 * <p>You can also use forms of the parse and format methods with
129 * {@link ParsePosition} and {@link FieldPosition} to
130 * allow you to
131 * <ul><li>progressively parse through pieces of a string.
132 * <li>align any particular field, or find out where it is for selection
133 * on the screen.
134 * </ul>
135 *
136 * <h3><a name="synchronization">Synchronization</a></h3>
137 *
138 * <p>
139 * Date formats are not synchronized.
140 * It is recommended to create separate format instances for each thread.
141 * If multiple threads access a format concurrently, it must be synchronized
142 * externally.
143 *
144 * @see Format
145 * @see NumberFormat
146 * @see SimpleDateFormat
147 * @see java.util.Calendar
148 * @see java.util.GregorianCalendar
149 * @see java.util.TimeZone
150 * @author Mark Davis, Chen-Lieh Huang, Alan Liu
151 */
152 public abstract class DateFormat extends Format {
153
154 /**
155 * The {@link Calendar} instance used for calculating the date-time fields
156 * and the instant of time. This field is used for both formatting and
157 * parsing.
158 *
159 * <p>Subclasses should initialize this field to a {@link Calendar}
160 * appropriate for the {@link Locale} associated with this
161 * <code>DateFormat</code>.
162 * @serial
163 */
279 * are a time value expressed in milliseconds and a Date object.
280 * @param obj must be a Number or a Date.
281 * @param toAppendTo the string buffer for the returning time string.
282 * @return the string buffer passed in as toAppendTo, with formatted text appended.
283 * @param fieldPosition keeps track of the position of the field
284 * within the returned string.
285 * On input: an alignment field,
286 * if desired. On output: the offsets of the alignment field. For
287 * example, given a time text "1996.07.10 AD at 15:08:56 PDT",
288 * if the given fieldPosition is DateFormat.YEAR_FIELD, the
289 * begin index and end index of fieldPosition will be set to
290 * 0 and 4, respectively.
291 * Notice that if the same time field appears
292 * more than once in a pattern, the fieldPosition will be set for the first
293 * occurrence of that time field. For instance, formatting a Date to
294 * the time string "1 PM PDT (Pacific Daylight Time)" using the pattern
295 * "h a z (zzzz)" and the alignment field DateFormat.TIMEZONE_FIELD,
296 * the begin index and end index of fieldPosition will be set to
297 * 5 and 8, respectively, for the first occurrence of the timezone
298 * pattern character 'z'.
299 * @see java.text.Format
300 */
301 public final StringBuffer format(Object obj, StringBuffer toAppendTo,
302 FieldPosition fieldPosition)
303 {
304 if (obj instanceof Date)
305 return format( (Date)obj, toAppendTo, fieldPosition );
306 else if (obj instanceof Number)
307 return format( new Date(((Number)obj).longValue()),
308 toAppendTo, fieldPosition );
309 else
310 throw new IllegalArgumentException("Cannot format given Object as a Date");
311 }
312
313 /**
314 * Formats a Date into a date/time string.
315 * @param date a Date to be formatted into a date/time string.
316 * @param toAppendTo the string buffer for the returning date/time string.
317 * @param fieldPosition keeps track of the position of the field
318 * within the returned string.
|
1 /*
2 * Copyright (c) 1996, 2017, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
124 * to a {@link SimpleDateFormat}. This will work for the majority
125 * of countries; just remember to put it in a {@code try} block in case you
126 * encounter an unusual one.
127 *
128 * <p>You can also use forms of the parse and format methods with
129 * {@link ParsePosition} and {@link FieldPosition} to
130 * allow you to
131 * <ul><li>progressively parse through pieces of a string.
132 * <li>align any particular field, or find out where it is for selection
133 * on the screen.
134 * </ul>
135 *
136 * <h3><a name="synchronization">Synchronization</a></h3>
137 *
138 * <p>
139 * Date formats are not synchronized.
140 * It is recommended to create separate format instances for each thread.
141 * If multiple threads access a format concurrently, it must be synchronized
142 * externally.
143 *
144 * @implSpec
145 * <ul><li>The {@link #format(Date, StringBuffer, FieldPosition)} and
146 * {@link #parse(String, ParsePosition)} methods may throw
147 * {@code NullPointerException}, if any of their parameter is {@code null}.
148 * The subclass may provide its own implementation and specification about
149 * {@code NullPointerException}.</li>
150 * <li>The {@link #setCalendar(Calendar)}, {@link
151 * #setNumberFormat(NumberFormat)} and {@link #setTimeZone(TimeZone)} methods
152 * do not throw {@code NullPointerException} when their parameter is
153 * {@code null}, but any subsequent operations on the same instance may throw
154 * {@code NullPointerException}.</li>
155 * <li>The {@link #getCalendar()}, {@link #getNumberFormat()} and
156 * {@link getTimeZone()} methods may return {@code null}, if the respective
157 * values of this instance is set to {@code null} through the corresponding
158 * setter methods. For Example: {@link #getTimeZone()} may return {@code null},
159 * if the {@code TimeZone} value of this instance is set as
160 * {@link #setTimeZone(java.util.TimeZone) setTimeZone(null)}.</li>
161 * </ul>
162 *
163 * @see Format
164 * @see NumberFormat
165 * @see SimpleDateFormat
166 * @see java.util.Calendar
167 * @see java.util.GregorianCalendar
168 * @see java.util.TimeZone
169 * @author Mark Davis, Chen-Lieh Huang, Alan Liu
170 */
171 public abstract class DateFormat extends Format {
172
173 /**
174 * The {@link Calendar} instance used for calculating the date-time fields
175 * and the instant of time. This field is used for both formatting and
176 * parsing.
177 *
178 * <p>Subclasses should initialize this field to a {@link Calendar}
179 * appropriate for the {@link Locale} associated with this
180 * <code>DateFormat</code>.
181 * @serial
182 */
298 * are a time value expressed in milliseconds and a Date object.
299 * @param obj must be a Number or a Date.
300 * @param toAppendTo the string buffer for the returning time string.
301 * @return the string buffer passed in as toAppendTo, with formatted text appended.
302 * @param fieldPosition keeps track of the position of the field
303 * within the returned string.
304 * On input: an alignment field,
305 * if desired. On output: the offsets of the alignment field. For
306 * example, given a time text "1996.07.10 AD at 15:08:56 PDT",
307 * if the given fieldPosition is DateFormat.YEAR_FIELD, the
308 * begin index and end index of fieldPosition will be set to
309 * 0 and 4, respectively.
310 * Notice that if the same time field appears
311 * more than once in a pattern, the fieldPosition will be set for the first
312 * occurrence of that time field. For instance, formatting a Date to
313 * the time string "1 PM PDT (Pacific Daylight Time)" using the pattern
314 * "h a z (zzzz)" and the alignment field DateFormat.TIMEZONE_FIELD,
315 * the begin index and end index of fieldPosition will be set to
316 * 5 and 8, respectively, for the first occurrence of the timezone
317 * pattern character 'z'.
318 * @exception IllegalArgumentException if the {@code Format} cannot format
319 * the given {@code obj}.
320 * @see java.text.Format
321 */
322 public final StringBuffer format(Object obj, StringBuffer toAppendTo,
323 FieldPosition fieldPosition)
324 {
325 if (obj instanceof Date)
326 return format( (Date)obj, toAppendTo, fieldPosition );
327 else if (obj instanceof Number)
328 return format( new Date(((Number)obj).longValue()),
329 toAppendTo, fieldPosition );
330 else
331 throw new IllegalArgumentException("Cannot format given Object as a Date");
332 }
333
334 /**
335 * Formats a Date into a date/time string.
336 * @param date a Date to be formatted into a date/time string.
337 * @param toAppendTo the string buffer for the returning date/time string.
338 * @param fieldPosition keeps track of the position of the field
339 * within the returned string.
|