001: /*
002: * Copyright (c) 2001 - 2005 ivata limited.
003: * All rights reserved.
004: * -----------------------------------------------------------------------------
005: * ivata masks may be redistributed under the GNU General Public
006: * License as published by the Free Software Foundation;
007: * version 2 of the License.
008: *
009: * These programs are free software; you can redistribute them and/or
010: * modify them under the terms of the GNU General Public License
011: * as published by the Free Software Foundation; version 2 of the License.
012: *
013: * These programs are distributed in the hope that they will be useful,
014: * but WITHOUT ANY WARRANTY; without even the implied warranty of
015: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
016: *
017: * See the GNU General Public License in the file LICENSE.txt for more
018: * details.
019: *
020: * If you would like a copy of the GNU General Public License write to
021: *
022: * Free Software Foundation, Inc.
023: * 59 Temple Place - Suite 330
024: * Boston, MA 02111-1307, USA.
025: *
026: *
027: * To arrange commercial support and licensing, contact ivata at
028: * http://www.ivata.com/contact.jsp
029: * -----------------------------------------------------------------------------
030: * $Log: DateFormatter.java,v $
031: * Revision 1.2 2005/04/09 18:04:18 colinmacleod
032: * Changed copyright text to GPL v2 explicitly.
033: *
034: * Revision 1.1 2005/01/19 12:49:24 colinmacleod
035: * Moved from ivata groupware.
036: *
037: * -----------------------------------------------------------------------------
038: */
039: package com.ivata.mask.web.format;
040:
041: import java.text.ParseException;
042: import java.util.Date;
043:
044: /**
045: * <p>
046: * This interface defines a formatter which is used to parse dates in a standard
047: * way, system-wide.
048: * </p>
049: * <p>
050: * <b>Note</b> that ivata masks does not provide an implementation of
051: * this interface. For an example implementation, look at the class
052: * <code>SettingDateFormatter</code> in
053: * <a href='http://groupware.ivata.org'>ivata groupware</a>.
054: * </p>
055: *
056: * @since ivata masks 0.5 (2005-01-11)
057: * @author Colin MacLeod
058: * <a href="mailto:colin.macleod@ivata.com">colin.macleod@ivata.com</a>
059: * @version $Revision: 1.2 $
060: */
061:
062: public interface DateFormatter {
063: /**
064: * <p>Format the date provided as a string.</p>
065: *
066: * @param date the date to convert into a string.
067: * @return date string, converted to a string, using the requested
068: * format.
069: * @throws DateFormatterException if there is a problem creating the
070: * string
071: * because of an incorrect format pattern, for example.
072: */
073: String format(Date date) throws DateFormatterException;
074:
075: /**
076: * <p>Get the number of the date format used in this object. This
077: * should
078: * correspond to one of the <code>DATE_FORMAT_...</code>
079: * constants.</p>
080: *
081: * @return the current value of the date format used.
082: */
083: int getDateFormat();
084:
085: /**
086: * <p>Get how the date and time are used in the output.</p>
087: *
088: * <p>The format used is the same as the format for
089: * <code>java.text.MessageFormat</code> and the string
090: * <code>{0}</code> will be
091: * replaced with the date format chosen, <code>{1}</code> is replaced
092: * with the
093: * time format chosen.</p>
094: *
095: * @return the current text used to combine date and time formats.
096: */
097: String getDateTimeText();
098:
099: /**
100: * <p>Get the number of the time format used in this object. This
101: * should
102: * correspond to one of the <code>TIME_FORMAT_...</code>
103: * constants.</p>
104: *
105: * @return the current value of the time format used.
106: */
107: int getTimeFormat();
108:
109: /**
110: * <p>Parse the given string to a date, using the current date
111: * format.</p>
112: *
113: * @param formatString the string to convert into a date.
114: * @return date parsed from the string provided.
115: * @throws ParseException if the string cannot be parsed into a
116: * date object.
117: * @throws DateFormatterException if the settings for this date format
118: * are not set, or not set correctly
119: */
120: Date parse(String formatString) throws ParseException,
121: DateFormatterException;
122:
123: /**
124: * <p>Set the number of the date format used in this object. This
125: * should
126: * correspond to one of the <code>DATE_FORMAT_...</code>
127: * constants.</p>
128: *
129: * @param dateFormat the new value of the date format used.
130: * @throws DateFormatterException if the settings for this date format
131: * are not set, or not set correctly
132: */
133: void setDateFormat(int dateFormat) throws DateFormatterException;
134:
135: /**
136: * <p>Set this text to restrict the output to just date or just time,
137: * or to
138: * change the text between
139: * them.</p>
140: *
141: * <p>The format used is the same as the format for
142: * <code>java.text.MessageFormat</code> and the string
143: * <code>{0}</code> will be
144: * replaced with the date format chosen, <code>{1}</code> is replaced
145: * with the
146: * time format chosen.</p>
147: *
148: * @param dateTimeText the new value of the text used to combine date
149: * and time
150: * formats.
151: * @throws DateFormatterException if the settings for this date format
152: * are not set, or not set correctly
153: */
154: void setDateTimeText(String dateTimeText)
155: throws DateFormatterException;
156:
157: /**
158: * <p>Set the number of the time format used in this object. This
159: * should
160: * correspond to one of the <code>TIME_FORMAT_...</code>
161: * constants.</p>
162: *
163: * @param timeFormat the new value of the time format used.
164: * @throws DateFormatterException if the settings for this date format
165: *
166: * are not set, or not set correctly
167: */
168: void setTimeFormat(int timeFormat) throws DateFormatterException;
169: }
|