001    /**
002     * Copyright 2005-2012 The Kuali Foundation
003     *
004     * Licensed under the Educational Community License, Version 2.0 (the "License");
005     * you may not use this file except in compliance with the License.
006     * You may obtain a copy of the License at
007     *
008     * http://www.opensource.org/licenses/ecl2.php
009     *
010     * Unless required by applicable law or agreed to in writing, software
011     * distributed under the License is distributed on an "AS IS" BASIS,
012     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013     * See the License for the specific language governing permissions and
014     * limitations under the License.
015     */
016    package org.kuali.rice.core.api.datetime;
017    
018    import java.sql.Timestamp;
019    import java.text.ParseException;
020    import java.util.Calendar;
021    import java.util.Date;
022    
023    /**
024     * This interface defines methods that a DateTime service must provide
025     */
026     public interface DateTimeService {
027        /**
028         * Translates the specified date into a string without a time component, formatted according to "stringDateFormat" that the
029         * service is configured with
030         *
031         * @param date
032         * @return formatted string version of the specified date
033         */
034         String toDateString(Date date);
035    
036        /**
037         * Translates the specified date into a string with a time component, formatted according to the "stringDateTimeFormat" that the
038         * service is configured with
039         *
040         * @param date
041         * @return formatted string version of the specified date
042         */
043         String toDateTimeString(Date date);
044    
045        /**
046         * Translates the specified date into a string without a time component, formatted according to the specified pattern
047         *
048         * @param date
049         * @return formatted string version of the specified date
050         */
051         String toString(Date date, String pattern);
052    
053        /**
054         * Returns the current date/time as a java.util.Date
055         *
056         * @return current date/time
057         */
058         Date getCurrentDate();
059    
060        /**
061         * Returns the current date/time as a java.sql.Timestamp
062         *
063         * @return current date/time
064         */
065         Timestamp getCurrentTimestamp();
066    
067        /**
068         * Returns the current date/time as a java.sql.Date
069         *
070         * @return current date/time
071         */
072         java.sql.Date getCurrentSqlDate();
073    
074        /**
075         * Returns the current date as a java.sql.Date rounded back to midnight. This is what the JDBC driver is supposed to do with
076         * dates on their way to the database, so it can be convenient for comparing to dates from the database or input from the UI.
077         *
078         * @return current date at the most recent midnight in the JVM's timezone
079         */
080         java.sql.Date getCurrentSqlDateMidnight();
081    
082        /**
083         * Returns a Calendar initialized with the current Date
084         *
085         * @return currennt Calendar
086         */
087         Calendar getCurrentCalendar();
088    
089        /**
090         * Returns a Calendar initialized to the given Date
091         *
092         * @return date-specific Calendar
093         * @throws IllegalArgumentException if the given Date is null
094         */
095         Calendar getCalendar(Date date);
096    
097        /**
098         * Translates the specified string into a date without a time component, see implementation class for formatting details
099         *
100         * @param dateString
101         * @return the date representation of the specified dateString
102         * @throws ParseException
103         */
104         Date convertToDate(String dateString) throws ParseException;
105    
106        /**
107         * Translates the specified string into a date with a time component, formatted according to "stringDateTimeFormat" that the
108         * service is configured with
109         *
110         * @param dateTimeString
111         * @return the date representation of the specified dateTimeString
112         * @throws ParseException
113         */
114         Date convertToDateTime(String dateTimeString) throws ParseException;
115    
116        /**
117         * Converts the given String into a java.sql.Timestamp instance according to the "stringDateTimeFormat" that the service is
118         * configured with
119         *
120         * @param timeString
121         * @return java.sql.Timestamp
122         * @throws IllegalArgumentException if the given string is null or blank
123         * @throws ParseException if the string cannot be converted
124         */
125         java.sql.Timestamp convertToSqlTimestamp(String timeString) throws ParseException;
126    
127        /**
128         * Converts the given String into a java.sql.Date instance
129         *
130         * @param dateString
131         * @return java.sql.Date
132         * @throws IllegalArgumentException if the given string is null or blank
133         * @throws ParseException if the string cannot be converted
134         */
135         java.sql.Date convertToSqlDate(String dateString) throws ParseException;
136    
137        /**
138         * Converts a Timestamp into a sql Date.
139         *
140         * @param timestamp
141         * @return
142         */
143         java.sql.Date convertToSqlDate(Timestamp timestamp) throws ParseException;
144    
145        /**
146         * Returns the number of days between two days - start and end date of some arbitrary period.
147         *
148         * @param date1 The first date in the period
149         * @param date2 The second date in the period
150         * @param inclusive Whether the result should include both the start and the end date. Otherwise it only includes one.
151         * @return int The number of days in the period
152         */
153         int dateDiff(Date date1, Date date2, boolean inclusive);
154    
155        /**
156         * Returns a String representing a date that is suitable for file names, and is preferably chronologically sortable
157         *
158         * @param date
159         * @return
160         */
161         String toDateStringForFilename(Date date);
162    
163        /**
164         * Returns a String representing a date/time that is suitable for file names, and is preferably chronologically sortable
165         *
166         * @param date
167         * @return
168         */
169         String toDateTimeStringForFilename(Date date);
170        
171    
172    }