001 package biz.wedoit4u.ejb.session;
002
003 import java.util.Date;
004 import java.text.ParseException;
005 import java.text.SimpleDateFormat;
006 import javax.ejb.EJBLocalObject;
007
008 /**
009 * This stateless session bean provides utility methods to convert
010 * dates into commonly needed string formats, as well as strings in
011 * commonly used date formats into Java Dates.
012 *
013 * <p>For maximum efficiency this session bean is implemented only
014 * as a <code>local EJB</code>, and this interface represents the
015 * <code>local interface</code> to the bean.</p>
016 *
017 * <p>The following code sample shows one way of using the methods
018 * in this session bean:</p>
019 *
020 * <pre>
021 * Date now = new Date();
022 * String formattedDate = "";
023 * Date parsedDate = null;
024 * try
025 * {
026 * DateFormatter df = SessionBeanProvider.getDateFormatter();
027 * formattedDate = df.getDateTime( now );
028 *
029 * try
030 * {
031 * parsedDate = df.getDateTime( formattedDate );
032 * }
033 * catch ( ParseException pex )
034 * {
035 * // Do error processing
036 * }
037 *
038 * df.remove();
039 * }
040 * catch ( Exception ex )
041 * {
042 * // Do error processing.
043 * }
044 * </pre>
045 *
046 * @see SessionBeanProvider#getDateFormatter()
047 *
048 * @author Rakesh Vidyadharan 17<sup><small>th</small></sup> September 2003
049 *
050 * <p>Copyright 2003, wedoit4u.biz</p>
051 *
052 * @version $Id: DateFormatter.java,v 1.2 2004/05/26 11:42:36 rakesh Exp $
053 */
054 public interface DateFormatter extends EJBLocalObject
055 {
056 /**
057 * Formats the specified <code>Date</code> object in <code>ISO 8601
058 * day</code> format (yyyy-MM-dd). This is also the <code>SQL
059 * Date</code> format.
060 *
061 * @param date - The input date that is to be formatted.
062 * @return String - The parsed date value.
063 */
064 public String getDay( Date date );
065
066 /**
067 * Parses the specified <code>String</code> in <code>ISO 8601
068 * day</code> format (yyyy-MM-dd) into a <code>Java Date</code>.
069 * This is also the <code>SQL Date</code> format.
070 *
071 * @param date - The input date that is to be parsed.
072 * @return Date - The formatted string value.
073 * @throws ParseException - If an exception is encountered while
074 * attempting to parse the input String in yyyy-MM-dd format
075 * into a Java Date.
076 */
077 public Date getDay( String date ) throws ParseException;
078
079 /**
080 * Formats the specified <code>Date</code> object in <code>ISO 8601
081 * time</code> format (HH:mm:ss). This is also the <code>SQL
082 * Time</code> format.
083 *
084 * @param date - The input date that is to be formatted.
085 * @return String - The formatted string value.
086 */
087 public String getTime( Date date );
088
089 /**
090 * Parses the specified <code>String</code> object in <code>ISO 8601
091 * time</code> format (HH:mm:ss) into a <code>Java Date</code>. This
092 * is also the <code>SQL Time</code> format.
093 *
094 * @param date - The input date that is to be parsed.
095 * @return Date - The parsed date value.
096 * @throws ParseException - If an exception is encountered while
097 * attempting to parse the input String in HH-mm-ss format
098 * into a Java Date.
099 */
100 public Date getTime( String date ) throws ParseException;
101
102 /**
103 * Formats the specified <code>Date</code> object in <code>ISO 8601
104 * date-time</code> format (yyyy-MM-dd'T'HH-mm-ss). This is not
105 * strictly ISO compliant, since this would indicate that the time
106 * is in <code>zero meridian</code>, while in reality this time
107 * is in US central time.
108 *
109 * @param date - The input date that is to be formatted.
110 * @return String - The formatted string value.
111 */
112 public String getDateTime( Date date );
113
114 /**
115 * Parses the specified <code>String</code> object in <code>ISO 8601
116 * date-time</code> format (yyyy-MM-dd'T'HH-mm-ss) into a
117 * <code>Java Date</code>. This is not
118 * strictly ISO compliant, since this would indicate that the time
119 * is in <code>zero meridian</code>, while in reality this time
120 * is in US central time.
121 *
122 * @param date - The input string that is to be formatted.
123 * @return Date - The parsed date value.
124 */
125 public Date getDateTime( String date ) throws ParseException;
126
127 /**
128 * Formats the specified <code>Date</code> object in <code>SQL
129 * timestamp</code> format (yyyy-MM-dd HH-mm-ss).
130 *
131 * @param date - The input date that is to be formatted.
132 * @return String - The formatted string value.
133 */
134 public String getSQLTimestamp( Date date );
135
136 /**
137 * Parses the specified <code>String</code> object in <code>SQL
138 * timestamp</code> format (yyyy-MM-dd HH-mm-ss) into a
139 * <code>Java Date</code>.
140 *
141 * @param date - The input string that is to be formatted.
142 * @return Date - The parsed date value.
143 */
144 public Date getSQLTimestamp( String date ) throws ParseException;
145 }