View Javadoc
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.commons.lang3.time;
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   * <p>DatePrinter is the "missing" interface for the format methods of 
27   * {@link java.text.DateFormat}.</p>
28   * 
29   * @since 3.2
30   */
31  public interface DatePrinter {
32  
33      /**
34       * <p>Formats a millisecond {@code long} value.</p>
35       *
36       * @param millis  the millisecond value to format
37       * @return the formatted string
38       * @since 2.1
39       */
40      String format(long millis);
41  
42      /**
43       * <p>Formats a {@code Date} object using a {@code GregorianCalendar}.</p>
44       *
45       * @param date  the date to format
46       * @return the formatted string
47       */
48      String format(Date date);
49  
50      /**
51       * <p>Formats a {@code Calendar} object.</p>
52       *
53       * @param calendar  the calendar to format
54       * @return the formatted string
55       */
56      String format(Calendar calendar);
57  
58      /**
59       * <p>Formats a milliseond {@code long} value into the
60       * supplied {@code StringBuffer}.</p>
61       *
62       * @param millis  the millisecond value to format
63       * @param buf  the buffer to format into
64       * @return the specified string buffer
65       */
66      StringBuffer format(long millis, StringBuffer buf);
67  
68      /**
69       * <p>Formats a {@code Date} object into the
70       * supplied {@code StringBuffer} using a {@code GregorianCalendar}.</p>
71       *
72       * @param date  the date to format
73       * @param buf  the buffer to format into
74       * @return the specified string buffer
75       */
76      StringBuffer format(Date date, StringBuffer buf);
77  
78      /**
79       * <p>Formats a {@code Calendar} object into the
80       * supplied {@code StringBuffer}.</p>
81       *
82       * @param calendar  the calendar to format
83       * @param buf  the buffer to format into
84       * @return the specified string buffer
85       */
86      StringBuffer format(Calendar calendar, StringBuffer buf);
87  
88      // Accessors
89      //-----------------------------------------------------------------------
90      /**
91       * <p>Gets the pattern used by this printer.</p>
92       *
93       * @return the pattern, {@link java.text.SimpleDateFormat} compatible
94       */
95      String getPattern();
96  
97      /**
98       * <p>Gets the time zone used by this printer.</p>
99       *
100      * <p>This zone is always used for {@code Date} printing. </p>
101      *
102      * @return the time zone
103      */
104     TimeZone getTimeZone();
105 
106     /**
107      * <p>Gets the locale used by this printer.</p>
108      *
109      * @return the locale
110      */
111     Locale getLocale();
112 
113     /**
114      * <p>Formats a {@code Date}, {@code Calendar} or
115      * {@code Long} (milliseconds) object.</p>
116      * 
117      * See {@link java.text.DateFormat#format(Object, StringBuffer, FieldPosition)}
118      * 
119      * @param obj  the object to format
120      * @param toAppendTo  the buffer to append to
121      * @param pos  the position - ignored
122      * @return the buffer passed in
123      */
124     StringBuffer format(Object obj, StringBuffer toAppendTo, FieldPosition pos);
125 }