1 /**
2 * Copyright 2005-2014 The Kuali Foundation
3 *
4 * Licensed under the Educational Community License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.opensource.org/licenses/ecl2.php
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.kuali.rice.core.api.datetime;
17
18 import java.sql.Time;
19 import java.sql.Timestamp;
20 import java.text.ParseException;
21 import java.util.Calendar;
22 import java.util.Date;
23
24 /**
25 * This interface defines methods that a DateTime service must provide
26 */
27 public interface DateTimeService {
28 /**
29 * Translates the specified date into a string without a time component, formatted according to "stringDateFormat" that the
30 * service is configured with
31 *
32 * @param date
33 * @return formatted string version of the specified date
34 */
35 String toDateString(Date date);
36
37 /**
38 * Translates the specified time into a string without a date component, formatted according to "stringTimeFormat" that the
39 * service is configured with
40 *
41 * @param time
42 * @return formatted string version of the specified time
43 */
44 String toTimeString(Time time);
45
46 /**
47 * Translates the specified date into a string with a time component, formatted according to the "stringDateTimeFormat" that the
48 * service is configured with
49 *
50 * @param date
51 * @return formatted string version of the specified date
52 */
53 String toDateTimeString(Date date);
54
55 /**
56 * Translates the specified date into a string without a time component, formatted according to the specified pattern
57 *
58 * @param date
59 * @return formatted string version of the specified date
60 */
61 String toString(Date date, String pattern);
62
63 /**
64 * Returns the current date/time as a java.util.Date
65 *
66 * @return current date/time
67 */
68 Date getCurrentDate();
69
70 /**
71 * Returns the current date/time as a java.sql.Timestamp
72 *
73 * @return current date/time
74 */
75 Timestamp getCurrentTimestamp();
76
77 /**
78 * Returns the current date/time as a java.sql.Date
79 *
80 * @return current date/time
81 */
82 java.sql.Date getCurrentSqlDate();
83
84 /**
85 * Returns the current date as a java.sql.Date rounded back to midnight. This is what the JDBC driver is supposed to do with
86 * dates on their way to the database, so it can be convenient for comparing to dates from the database or input from the UI.
87 *
88 * @return current date at the most recent midnight in the JVM's timezone
89 */
90 java.sql.Date getCurrentSqlDateMidnight();
91
92 /**
93 * Returns a Calendar initialized with the current Date
94 *
95 * @return currennt Calendar
96 */
97 Calendar getCurrentCalendar();
98
99 /**
100 * Returns a Calendar initialized to the given Date
101 *
102 * @return date-specific Calendar
103 * @throws IllegalArgumentException if the given Date is null
104 */
105 Calendar getCalendar(Date date);
106
107 /**
108 * Translates the specified string into a date without a time component, see implementation class for formatting details
109 *
110 * @param dateString
111 * @return the date representation of the specified dateString
112 * @throws ParseException
113 */
114 Date convertToDate(String dateString) throws ParseException;
115
116 /**
117 * Translates the specified string into a date with a time component, formatted according to "stringDateTimeFormat" that the
118 * service is configured with
119 *
120 * @param dateTimeString
121 * @return the date representation of the specified dateTimeString
122 * @throws ParseException
123 */
124 Date convertToDateTime(String dateTimeString) throws ParseException;
125
126 /**
127 * Converts the given String into a java.sql.Timestamp instance according to the "stringDateTimeFormat" that the service is
128 * configured with
129 *
130 * @param timeString
131 * @return java.sql.Timestamp
132 * @throws IllegalArgumentException if the given string is null or blank
133 * @throws ParseException if the string cannot be converted
134 */
135 java.sql.Timestamp convertToSqlTimestamp(String timeString) throws ParseException;
136
137 /**
138 * Converts the given String into a java.sql.Date instance
139 *
140 * @param dateString
141 * @return java.sql.Date
142 * @throws IllegalArgumentException if the given string is null or blank
143 * @throws ParseException if the string cannot be converted
144 */
145 java.sql.Date convertToSqlDate(String dateString) throws ParseException;
146
147 /**
148 * Converts the given String into a java.sql.Date instance for the next day
149 *
150 * @param dateString
151 * @return java.sql.Date
152 * @throws IllegalArgumentException if the given string is null or blank
153 * @throws ParseException if the string cannot be converted
154 *
155 * @since 2.4
156 */
157 java.sql.Date convertToSqlDateUpperBound(String dateString) throws ParseException;
158
159 /**
160 * Converts the given String into a java.sql.Time instance
161 *
162 * @param timeString
163 * @return java.sql.Time
164 * @throws IllegalArgumentException if the given string is null or blank
165 * @throws ParseException if the string cannot be converted
166 */
167 java.sql.Time convertToSqlTime(String timeString) throws ParseException;
168
169 /**
170 * Converts a Timestamp into a sql Date.
171 *
172 * @param timestamp
173 * @return
174 */
175 java.sql.Date convertToSqlDate(Timestamp timestamp) throws ParseException;
176
177 /**
178 * Returns the number of days between two days - start and end date of some arbitrary period.
179 *
180 * @param date1 The first date in the period
181 * @param date2 The second date in the period
182 * @param inclusive Whether the result should include both the start and the end date. Otherwise it only includes one.
183 * @return int The number of days in the period
184 */
185 int dateDiff(Date date1, Date date2, boolean inclusive);
186
187 /**
188 * Returns a String representing a date that is suitable for file names, and is preferably chronologically sortable
189 *
190 * @param date
191 * @return
192 */
193 String toDateStringForFilename(Date date);
194
195 /**
196 * Returns a String representing a date/time that is suitable for file names, and is preferably chronologically sortable
197 *
198 * @param date
199 * @return
200 */
201 String toDateTimeStringForFilename(Date date);
202
203
204 }