1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache license, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the license for the specific language governing permissions and
15 * limitations under the license.
16 */
17 package org.apache.logging.log4j.core.util.datetime;
18
19 import java.text.FieldPosition;
20 import java.util.Calendar;
21 import java.util.Date;
22 import java.util.Locale;
23 import java.util.TimeZone;
24
25 /**
26 * DatePrinter is the "missing" interface for the format methods of
27 * {@link java.text.DateFormat}. You can obtain an object implementing this
28 * interface by using one of the FastDateFormat factory methods.
29 * <p>
30 * Warning: Since binary compatible methods may be added to this interface in any
31 * release, developers are not expected to implement this interface.
32 * </p>
33 *
34 * <p>
35 * Copied and modified from <a href="https://commons.apache.org/proper/commons-lang/">Apache Commons Lang</a>.
36 * </p>
37 *
38 * @since Apache Commons Lang 3.2
39 */
40 public interface DatePrinter {
41
42 /**
43 * <p>Formats a millisecond {@code long} value.</p>
44 *
45 * @param millis the millisecond value to format
46 * @return the formatted string
47 * @since 2.1
48 */
49 String format(long millis);
50
51 /**
52 * <p>Formats a {@code Date} object using a {@code GregorianCalendar}.</p>
53 *
54 * @param date the date to format
55 * @return the formatted string
56 */
57 String format(Date date);
58
59 /**
60 * <p>Formats a {@code Calendar} object.</p>
61 * The TimeZone set on the Calendar is only used to adjust the time offset.
62 * The TimeZone specified during the construction of the Parser will determine the TimeZone
63 * used in the formatted string.
64 *
65 * @param calendar the calendar to format.
66 * @return the formatted string
67 */
68 String format(Calendar calendar);
69
70 /**
71 * <p>Formats a millisecond {@code long} value into the
72 * supplied {@code Appendable}.</p>
73 *
74 * @param millis the millisecond value to format
75 * @param buf the buffer to format into
76 * @param <B> the Appendable class type, usually StringBuilder or StringBuffer.
77 * @return the specified string buffer
78 * @since 3.5
79 */
80 <B extends Appendable> B format(long millis, B buf);
81
82 /**
83 * <p>Formats a {@code Date} object into the
84 * supplied {@code Appendable} using a {@code GregorianCalendar}.</p>
85 *
86 * @param date the date to format
87 * @param buf the buffer to format into
88 * @param <B> the Appendable class type, usually StringBuilder or StringBuffer.
89 * @return the specified string buffer
90 * @since 3.5
91 */
92 <B extends Appendable> B format(Date date, B buf);
93
94 /**
95 * <p>Formats a {@code Calendar} object into the supplied {@code Appendable}.</p>
96 * The TimeZone set on the Calendar is only used to adjust the time offset.
97 * The TimeZone specified during the construction of the Parser will determine the TimeZone
98 * used in the formatted string.
99 *
100 * @param calendar the calendar to format
101 * @param buf the buffer to format into
102 * @param <B> the Appendable class type, usually StringBuilder or StringBuffer.
103 * @return the specified string buffer
104 * @since 3.5
105 */
106 <B extends Appendable> B format(Calendar calendar, B buf);
107
108
109 // Accessors
110 //-----------------------------------------------------------------------
111 /**
112 * <p>Gets the pattern used by this printer.</p>
113 *
114 * @return the pattern, {@link java.text.SimpleDateFormat} compatible
115 */
116 String getPattern();
117
118 /**
119 * <p>Gets the time zone used by this printer.</p>
120 *
121 * <p>This zone is always used for {@code Date} printing. </p>
122 *
123 * @return the time zone
124 */
125 TimeZone getTimeZone();
126
127 /**
128 * <p>Gets the locale used by this printer.</p>
129 *
130 * @return the locale
131 */
132 Locale getLocale();
133
134 /**
135 * <p>Formats a {@code Date}, {@code Calendar} or
136 * {@code Long} (milliseconds) object.</p>
137 *
138 * @param obj the object to format
139 * @param toAppendTo the buffer to append to
140 * @param pos the position - ignored
141 * @return the buffer passed in
142 * @see java.text.DateFormat#format(Object, StringBuffer, FieldPosition)
143 */
144 StringBuilder format(Object obj, StringBuilder toAppendTo, FieldPosition pos);
145 }