001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/util/tags/sakai_2-4-1/util-api/api/src/java/org/sakaiproject/time/api/TimeService.java $
003: * $Id: TimeService.java 8387 2006-04-27 03:10:39Z ggolden@umich.edu $
004: ***********************************************************************************
005: *
006: * Copyright (c) 2003, 2004, 2005, 2006 The Sakai Foundation.
007: *
008: * Licensed under the Educational Community License, Version 1.0 (the "License");
009: * you may not use this file except in compliance with the License.
010: * You may obtain a copy of the License at
011: *
012: * http://www.opensource.org/licenses/ecl1.php
013: *
014: * Unless required by applicable law or agreed to in writing, software
015: * distributed under the License is distributed on an "AS IS" BASIS,
016: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: * See the License for the specific language governing permissions and
018: * limitations under the License.
019: *
020: **********************************************************************************/package org.sakaiproject.time.api;
021:
022: import java.util.GregorianCalendar;
023: import java.util.TimeZone;
024:
025: /**
026: * <p>
027: * TimeService ...
028: * </p>
029: */
030: public interface TimeService {
031: /** The type string for this "application": should not change over time as it may be stored in various parts of persistent entities. */
032: static final String APPLICATION_ID = "sakai:time";
033:
034: /** Preferences key for user's time zone */
035: public static final String TIMEZONE_KEY = "timezone";
036:
037: /**
038: * Get a time object.
039: *
040: * @return A time object, set to now.
041: */
042: Time newTime();
043:
044: /**
045: * Get a time object, set from this string in our format, Gmt values
046: *
047: * @param value
048: * time format string.
049: * @return A time object.
050: */
051: Time newTimeGmt(String value);
052:
053: /**
054: * Get a time object, set from this long milliseconds since the "epoc" value.
055: *
056: * @param value
057: * time long milliseconds value.
058: * @return A time object.
059: */
060: Time newTime(long value);
061:
062: /**
063: * Get a time object, based on the time set in the calendar
064: *
065: * @return A time object, set to now.
066: */
067: Time newTime(GregorianCalendar cal);
068:
069: /**
070: * Get a time object, set from individual ints, Gmt values
071: *
072: * @param year
073: * full year (i.e. 1999, 2000)
074: * @param month
075: * month in year (1..12)
076: * @param day
077: * day in month (1..31)
078: * @param hour
079: * hour in day (0..23)
080: * @param minuet
081: * minute in hour (0..59)
082: * @param second
083: * second in minute (0..59)
084: * @param millisecond
085: * millisecond in second (0..999)
086: * @return A time object.
087: */
088: Time newTimeGmt(int year, int month, int day, int hour, int minute,
089: int second, int millisecond);
090:
091: /**
092: * Get a time object, set from this breakdown (Gmt values).
093: *
094: * @param breakdown
095: * The time breakdown values.
096: * @return A time object.
097: */
098: Time newTimeGmt(TimeBreakdown breakdown);
099:
100: /**
101: * Get a time object, set from individual ints, Local values
102: *
103: * @param year
104: * full year (i.e. 1999, 2000)
105: * @param month
106: * month in year (1..12)
107: * @param day
108: * day in month (1..31)
109: * @param hour
110: * hour in day (0..23)
111: * @param minuet
112: * minute in hour (0..59)
113: * @param second
114: * second in minute (0..59)
115: * @param millisecond
116: * millisecond in second (0..999)
117: * @return A time object.
118: */
119: Time newTimeLocal(int year, int month, int day, int hour,
120: int minute, int second, int millisecond);
121:
122: /**
123: * Get a time object, set from this breakdown (Local values).
124: *
125: * @param breakdown
126: * The time breakdown values.
127: * @return A time object.
128: */
129: Time newTimeLocal(TimeBreakdown breakdown);
130:
131: /**
132: * Get a TimeBreakdown object, set from individual ints.
133: *
134: * @param year
135: * full year (i.e. 1999, 2000)
136: * @param month
137: * month in year (1..12)
138: * @param day
139: * day in month (1..31)
140: * @param hour
141: * hour in day (0..23)
142: * @param minuet
143: * minute in hour (0..59)
144: * @param second
145: * second in minute (0..59)
146: * @param millisecond
147: * millisecond in second (0..999)
148: * @return A TimeBreakdown.
149: */
150: TimeBreakdown newTimeBreakdown(int year, int month, int day,
151: int hour, int minute, int second, int millisecond);
152:
153: /**
154: * Get a TimeRange, from parts.
155: *
156: * @param start
157: * The start Time.
158: * @param end
159: * The end Time.
160: * @param startIncluded
161: * true if start is part of the range, false if not.
162: * @param endIncluded
163: * true of end is part of the range, false if not.
164: * @return A TimeRange.
165: */
166: TimeRange newTimeRange(Time start, Time end, boolean startIncluded,
167: boolean endIncluded);
168:
169: /**
170: * Get a TimeRange, from our string format.
171: *
172: * @param value
173: * The TimeRange string.
174: * @return A TimeRange.
175: */
176: TimeRange newTimeRange(String value);
177:
178: /**
179: * Get a TimeRange, from a single time.
180: *
181: * @param startAndEnd
182: * The Time for the range.
183: * @return A TimeRange.
184: */
185: TimeRange newTimeRange(Time startAndEnd);
186:
187: /**
188: * Get a TimeRange, from a time value long start and duration
189: *
190: * @param start
191: * The long start time (milliseconds since).
192: * @param duration
193: * The long milliseconds duration.
194: * @return A TimeRange.
195: */
196: TimeRange newTimeRange(long start, long duration);
197:
198: /**
199: * Get a TimeRange, from two times, inclusive.
200: *
201: * @param start
202: * The start time.
203: * @param end
204: * The end time.
205: * @return A TimeRange.
206: */
207: TimeRange newTimeRange(Time start, Time end);
208:
209: /**
210: * Access the local TimeZone.
211: *
212: * @return The local TimeZone.
213: */
214: TimeZone getLocalTimeZone();
215:
216: /**
217: * Clear local time zone for specified user
218: *
219: * @return true if successful
220: */
221: boolean clearLocalTimeZone(String userId);
222:
223: /**
224: * Get a Calendar, set to this zone and these values.
225: *
226: * @param zone
227: * The TimeZone for the calendar.
228: * @param year
229: * full year (i.e. 1999, 2000)
230: * @param month
231: * month in year (1..12)
232: * @param day
233: * day in month (1..31)
234: * @param hour
235: * hour in day (0..23)
236: * @param min
237: * minute in hour (0..59)
238: * @param second
239: * second in minute (0..59)
240: * @param ms
241: * millisecond in second (0..999)
242: */
243: GregorianCalendar getCalendar(TimeZone zone, int year, int month,
244: int day, int hour, int min, int sec, int ms);
245:
246: /**
247: * Compare two Time for differences, either may be null
248: *
249: * @param a
250: * One Time.
251: * @param b
252: * The other Time.
253: * @return true if the Times are different, false if they are the same.
254: */
255: boolean different(Time a, Time b);
256: }
|