1 /**
2 * Copyright 2005-2012 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.Timestamp;
19 import java.text.ParseException;
20 import java.util.Calendar;
21 import java.util.Date;
22
23 /**
24 * This interface defines methods that a DateTime service must provide
25 */
26 public interface DateTimeService {
27 /**
28 * Translates the specified date into a string without a time component, formatted according to "stringDateFormat" that the
29 * service is configured with
30 *
31 * @param date
32 * @return formatted string version of the specified date
33 */
34 String toDateString(Date date);
35
36 /**
37 * Translates the specified date into a string with a time component, formatted according to the "stringDateTimeFormat" that the
38 * service is configured with
39 *
40 * @param date
41 * @return formatted string version of the specified date
42 */
43 String toDateTimeString(Date date);
44
45 /**
46 * Translates the specified date into a string without a time component, formatted according to the specified pattern
47 *
48 * @param date
49 * @return formatted string version of the specified date
50 */
51 String toString(Date date, String pattern);
52
53 /**
54 * Returns the current date/time as a java.util.Date
55 *
56 * @return current date/time
57 */
58 Date getCurrentDate();
59
60 /**
61 * Returns the current date/time as a java.sql.Timestamp
62 *
63 * @return current date/time
64 */
65 Timestamp getCurrentTimestamp();
66
67 /**
68 * Returns the current date/time as a java.sql.Date
69 *
70 * @return current date/time
71 */
72 java.sql.Date getCurrentSqlDate();
73
74 /**
75 * Returns the current date as a java.sql.Date rounded back to midnight. This is what the JDBC driver is supposed to do with
76 * dates on their way to the database, so it can be convenient for comparing to dates from the database or input from the UI.
77 *
78 * @return current date at the most recent midnight in the JVM's timezone
79 */
80 java.sql.Date getCurrentSqlDateMidnight();
81
82 /**
83 * Returns a Calendar initialized with the current Date
84 *
85 * @return currennt Calendar
86 */
87 Calendar getCurrentCalendar();
88
89 /**
90 * Returns a Calendar initialized to the given Date
91 *
92 * @return date-specific Calendar
93 * @throws IllegalArgumentException if the given Date is null
94 */
95 Calendar getCalendar(Date date);
96
97 /**
98 * Translates the specified string into a date without a time component, see implementation class for formatting details
99 *
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 }