View Javadoc

1   /*
2    * Copyright (c) 2001 - 2005 ivata limited.
3    * All rights reserved.
4    * -----------------------------------------------------------------------------
5    * ivata masks may be redistributed under the GNU General Public
6    * License as published by the Free Software Foundation;
7    * version 2 of the License.
8    *
9    * These programs are free software; you can redistribute them and/or
10   * modify them under the terms of the GNU General Public License
11   * as published by the Free Software Foundation; version 2 of the License.
12   *
13   * These programs are distributed in the hope that they will be useful,
14   * but WITHOUT ANY WARRANTY; without even the implied warranty of
15   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
16   *
17   * See the GNU General Public License in the file LICENSE.txt for more
18   * details.
19   *
20   * If you would like a copy of the GNU General Public License write to
21   *
22   * Free Software Foundation, Inc.
23   * 59 Temple Place - Suite 330
24   * Boston, MA 02111-1307, USA.
25   *
26   *
27   * To arrange commercial support and licensing, contact ivata at
28   *                  http://www.ivata.com/contact.jsp
29   * -----------------------------------------------------------------------------
30   * $Log: DateFormatter.java,v $
31   * Revision 1.2  2005/04/09 18:04:18  colinmacleod
32   * Changed copyright text to GPL v2 explicitly.
33   *
34   * Revision 1.1  2005/01/19 12:49:24  colinmacleod
35   * Moved from ivata groupware.
36   *
37   * -----------------------------------------------------------------------------
38   */
39  package com.ivata.mask.web.format;
40  
41  import java.text.ParseException;
42  import java.util.Date;
43  
44  /***
45   * <p>
46   * This interface defines a formatter which is used to parse dates in a standard
47   * way, system-wide.
48   * </p>
49   * <p>
50   * <b>Note</b> that ivata masks does not provide an implementation of
51   * this interface. For an example implementation, look at the class
52   * <code>SettingDateFormatter</code> in
53   * <a href='http://groupware.ivata.org'>ivata groupware</a>.
54   * </p>
55   *
56   * @since ivata masks 0.5 (2005-01-11)
57   * @author Colin MacLeod
58   * <a href="mailto:colin.macleod@ivata.com">colin.macleod@ivata.com</a>
59   * @version $Revision: 1.2 $
60   */
61  
62  public interface DateFormatter {
63      /***
64       * <p>Format the date provided as a string.</p>
65       *
66       * @param date the date to convert into a string.
67       * @return date string, converted to a string, using the requested
68       * format.
69       * @throws DateFormatterException if there is a problem creating the
70       * string
71       * because of an incorrect format pattern, for example.
72       */
73      String format(Date date)
74              throws DateFormatterException;
75      /***
76       * <p>Get the number of the date format used in this object. This
77       * should
78       * correspond to one of the <code>DATE_FORMAT_...</code>
79       * constants.</p>
80       *
81       * @return the current value of the date format used.
82       */
83      int getDateFormat();
84  
85      /***
86       * <p>Get how the date and time are used in the output.</p>
87       *
88       * <p>The format used is the same as the format for
89       * <code>java.text.MessageFormat</code> and the string
90       * <code>{0}</code> will be
91       * replaced with the date format chosen, <code>{1}</code> is replaced
92       * with the
93       * time format chosen.</p>
94       *
95       * @return the current text used to combine date and time formats.
96       */
97      String getDateTimeText();
98      /***
99       * <p>Get the number of the time format used in this object. This
100      * should
101      * correspond to one of the <code>TIME_FORMAT_...</code>
102      * constants.</p>
103      *
104      * @return the current value of the time format used.
105      */
106     int getTimeFormat();
107 
108     /***
109      * <p>Parse the given string to a date, using the current date
110      * format.</p>
111      *
112      * @param formatString the string to convert into a date.
113      * @return date parsed from the string provided.
114      * @throws ParseException if the string cannot be parsed into a
115      * date object.
116      * @throws DateFormatterException if the settings for this date format
117      * are not set, or not set correctly
118      */
119     Date parse(String formatString)
120             throws ParseException,
121             DateFormatterException;
122     /***
123      * <p>Set the number of the date format used in this object. This
124      * should
125      * correspond to one of the <code>DATE_FORMAT_...</code>
126      * constants.</p>
127      *
128      * @param dateFormat the new value of the date format used.
129      * @throws DateFormatterException if the settings for this date format
130      * are not set, or not set correctly
131      */
132     void setDateFormat(int dateFormat) throws DateFormatterException;
133 
134     /***
135      * <p>Set  this text to restrict the output to just date or just time,
136      * or to
137      * change the text between
138      * them.</p>
139      *
140      * <p>The format used is the same as the format for
141      * <code>java.text.MessageFormat</code> and the string
142      * <code>{0}</code> will be
143      * replaced with the date format chosen, <code>{1}</code> is replaced
144      * with the
145      * time format chosen.</p>
146      *
147      * @param dateTimeText the new value of the text used to combine date
148      * and time
149      * formats.
150      * @throws DateFormatterException if the settings for this date format
151      * are not set, or not set correctly
152      */
153     void setDateTimeText(String dateTimeText)
154             throws DateFormatterException;
155 
156     /***
157      * <p>Set the number of the time format used in this object. This
158      * should
159      * correspond to one of the <code>TIME_FORMAT_...</code>
160      * constants.</p>
161      *
162      * @param timeFormat the new value of the time format used.
163      * @throws DateFormatterException if the settings for this date format
164      *
165      * are not set, or not set correctly
166      */
167     void setTimeFormat(int timeFormat) throws DateFormatterException;
168 }