001 /*
002 * JBoss, Home of Professional Open Source.
003 * Copyright 2008, Red Hat Middleware LLC, and individual contributors
004 * as indicated by the @author tags. See the copyright.txt file in the
005 * distribution for a full listing of individual contributors.
006 *
007 * This is free software; you can redistribute it and/or modify it
008 * under the terms of the GNU Lesser General Public License as
009 * published by the Free Software Foundation; either version 2.1 of
010 * the License, or (at your option) any later version.
011 *
012 * This software is distributed in the hope that it will be useful,
013 * but WITHOUT ANY WARRANTY; without even the implied warranty of
014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015 * Lesser General Public License for more details.
016 *
017 * You should have received a copy of the GNU Lesser General Public
018 * License along with this software; if not, write to the Free
019 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
021 */
022 package org.jboss.dna.graph.properties;
023
024 import java.io.Serializable;
025 import java.util.Locale;
026 import java.util.concurrent.TimeUnit;
027 import net.jcip.annotations.Immutable;
028
029 /**
030 * An immutable date-time class that represents an instance in time. This class is designed to hide the horrible implementations
031 * of the JDK date and calendar classes, which are being overhauled (and replaced) under <a
032 * href="http://jcp.org/en/jsr/detail?id=310">JSR-310</a>, which will be based upon <a
033 * href="http://joda-time.sourceforge.net/">Joda-Time</a>. This class serves as a stable migration path toward the new JSR 310
034 * classes.
035 *
036 * @author Randall Hauch
037 */
038 @Immutable
039 public interface DateTime extends Comparable<DateTime>, Serializable {
040
041 /**
042 * Get the ISO-8601 representation of this instance in time. The month-based ISO-8601 representation is the most common format
043 * of ISO8601, and is the format used in the XML standards for passing dates and times:
044 *
045 * <pre>
046 * yyyy-mm-ddTHH:MM:SS.SSSZ
047 * </pre>
048 *
049 * The fields are separated by dashes and consist of:
050 * <ul>
051 * <li>four digit year;</li>
052 * <li>two digit month, where 01 is Janurary and 12 is December;</li>
053 * <li>two digit day of month, from 01 to 31;</li>
054 * <li>two digit hour, from 00 to 23;</li>
055 * <li>two digit minute, from 00 to 59;</li>
056 * <li>two digit second, from 00 to 59;</li>
057 * <li>three decimal places for milliseconds, if required;</li>
058 * <li>time zone offset of the form <code>±HH:mm</code> (or '0' if UTC)</li>
059 * </ul>
060 *
061 * @return the string representation; never null
062 */
063 String getString();
064
065 /**
066 * Get the number of milliseconds from 1970-01-01T00:00Z. This value is consistent with the JDK {@link java.util.Date Date}
067 * and {@link java.util.Calendar Calendar} classes.
068 *
069 * @return the number of milliseconds from 1970-01-01T00:00Z
070 */
071 long getMilliseconds();
072
073 /**
074 * Get this instance represented as a standard JDK {@link java.util.Date} instance. Note that this conversion loses the time
075 * zone information, as the standard JDK {@link java.util.Date} does not represent time zones.
076 *
077 * @return this instance in time as a JDK Date; never null
078 */
079 java.util.Date toDate();
080
081 /**
082 * Get this instance represented as a standard JDK {@link java.util.Calendar} instance, in the {@link Locale#getDefault()
083 * default locale}.
084 *
085 * @return this instance in time as a JDK Calendar; never null
086 */
087 java.util.Calendar toCalendar();
088
089 /**
090 * Get this instance represented as a standard JDK {@link java.util.Calendar} instance, in the specified {@link Locale locale}
091 * .
092 *
093 * @param locale the locale in which the Calendar instance is desired; may be null if the {@link Locale#getDefault() default
094 * locale} is to be used.
095 * @return this instance in time as a JDK Calendar; never null
096 */
097 java.util.Calendar toCalendar( Locale locale );
098
099 /**
100 * Get this instance represented as a standard JDK {@link java.util.GregorianCalendar} instance.
101 *
102 * @return this instance in time as a JDK GregorianCalendar; never null
103 */
104 java.util.GregorianCalendar toGregorianCalendar();
105
106 /**
107 * Get the era of this instance in time.
108 *
109 * @return the era
110 */
111 int getEra();
112
113 /**
114 * Get the era of this instance in time.
115 *
116 * @return the era
117 */
118 int getYear();
119
120 /**
121 * Get the era of this instance in time.
122 *
123 * @return the era
124 */
125 int getWeekyear();
126
127 /**
128 * Get the era of this instance in time.
129 *
130 * @return the era
131 */
132 int getCenturyOfEra();
133
134 /**
135 * Get the year of the era of this instance in time.
136 *
137 * @return the year of the era
138 */
139 int getYearOfEra();
140
141 /**
142 * Get the year of this century of this instance in time.
143 *
144 * @return the year of the century
145 */
146 int getYearOfCentury();
147
148 /**
149 * Get the month of the year of this instance in time.
150 *
151 * @return the month number
152 */
153 int getMonthOfYear();
154
155 /**
156 * Get the week of the weekyear of this instance in time.
157 *
158 * @return the week of the weekyear
159 */
160 int getWeekOfWeekyear();
161
162 /**
163 * Get the day of the year of this instance in time.
164 *
165 * @return the day of the year
166 */
167 int getDayOfYear();
168
169 /**
170 * Get the day of the month value of this instance in time.
171 *
172 * @return the day of the month
173 */
174 int getDayOfMonth();
175
176 /**
177 * Get the day of the week value of this instance in time.
178 *
179 * @return the day of the week
180 */
181 int getDayOfWeek();
182
183 /**
184 * Get the hour of the day of this instance in time.
185 *
186 * @return the hour of the day
187 */
188 int getHourOfDay();
189
190 /**
191 * Get the minute of this instance in time.
192 *
193 * @return the minute of the hour
194 */
195 int getMinuteOfHour();
196
197 /**
198 * Get the seconds of the minute value of this instance in time.
199 *
200 * @return the seconds of the minute
201 */
202 int getSecondOfMinute();
203
204 /**
205 * Get the milliseconds of the second value of this instance in time.
206 *
207 * @return the milliseconds
208 */
209 int getMillisOfSecond();
210
211 /**
212 * Get the number of hours that this time zone is offset from UTC.
213 *
214 * @return the number of hours
215 */
216 int getTimeZoneOffsetHours();
217
218 /**
219 * Get the identifier of the time zone in which this instant is defined
220 *
221 * @return the time zone identifier; never null
222 */
223 String getTimeZoneId();
224
225 /**
226 * Convert this time to the same instant in the UTC time zone.
227 *
228 * @return this instant in time in the specified time zone
229 */
230 DateTime toUtcTimeZone();
231
232 /**
233 * Convert this time to the time zone given by the supplied identifier.
234 *
235 * @param timeZoneId the time zone identifier
236 * @return the instant in the specified time zone
237 * @throws IllegalArgumentException if the time zone identifier is null or is invalid
238 */
239 DateTime toTimeZone( String timeZoneId );
240
241 /**
242 * Return whether this date-time is earlier than the supplied date-time.
243 *
244 * @param other the date-time to compare with
245 * @return true if this date-time is earliar than the other, or false otherwise
246 * @see #compareTo(DateTime)
247 * @see #isSameAs(DateTime)
248 * @see #isAfter(DateTime)
249 */
250 boolean isBefore( DateTime other );
251
252 /**
253 * Return whether this date-time is later than the supplied date-time.
254 *
255 * @param other the date-time to compare with
256 * @return true if this date-time is later than the other, or false otherwise
257 * @see #compareTo(DateTime)
258 * @see #isBefore(DateTime)
259 * @see #isSameAs(DateTime)
260 */
261 boolean isAfter( DateTime other );
262
263 /**
264 * Return whether this date-time is at the same time as the supplied date-time.
265 *
266 * @param other the date-time to compare with
267 * @return true if this date-time is later than the other, or false otherwise
268 * @see #compareTo(DateTime)
269 * @see #isBefore(DateTime)
270 * @see #isAfter(DateTime)
271 */
272 boolean isSameAs( DateTime other );
273
274 /**
275 * Subtract the specified about of time in the supplied units.
276 *
277 * @param timeAmount the amount of time to subtract
278 * @param unit the units of the amount of time; may not be null
279 * @return the instance in time the specified number of time before this instant
280 */
281 DateTime minus( long timeAmount,
282 TimeUnit unit );
283
284 /**
285 * Subtract the specified number of days from this time instant.
286 *
287 * @param days the number of days to subtract
288 * @return the instance in time the specified number of days before this instant
289 */
290 DateTime minusDays( int days );
291
292 /**
293 * Subtract the specified number of hours from this time instant.
294 *
295 * @param hours the number of hours to subtract
296 * @return the instance in time the specified number of hours before this instant
297 */
298 DateTime minusHours( int hours );
299
300 /**
301 * Subtract the specified number of milliseconds from this time instant.
302 *
303 * @param milliseconds the number of milliseconds to subtract
304 * @return the instance in time the specified number of milliseconds before this instant
305 */
306 DateTime minusMillis( int milliseconds );
307
308 /**
309 * Subtract the specified number of minutes from this time instant.
310 *
311 * @param minutes the number of minutes to subtract
312 * @return the instance in time the specified number of minutes before this instant
313 */
314 DateTime minusMinutes( int minutes );
315
316 /**
317 * Subtract the specified number of months from this time instant.
318 *
319 * @param months the number of months to subtract
320 * @return the instance in time the specified number of months before this instant
321 */
322 DateTime minusMonths( int months );
323
324 /**
325 * Subtract the specified number of seconds from this time instant.
326 *
327 * @param seconds the number of seconds to subtract
328 * @return the instance in time the specified number of seconds before this instant
329 */
330 DateTime minusSeconds( int seconds );
331
332 /**
333 * Subtract the specified number of weeks from this time instant.
334 *
335 * @param weeks the number of weeks to subtract
336 * @return the instance in time the specified number of weeks before this instant
337 */
338 DateTime minusWeeks( int weeks );
339
340 /**
341 * Subtract the specified number of years from this time instant.
342 *
343 * @param years the number of years to subtract
344 * @return the instance in time the specified number of years before this instant
345 */
346 DateTime minusYears( int years );
347
348 /**
349 * Add the specified about of time in the supplied units.
350 *
351 * @param timeAmount the amount of time to add
352 * @param unit the units of the amount of time; may not be null
353 * @return the instance in time the specified number of time after this instant
354 */
355 DateTime plus( long timeAmount,
356 TimeUnit unit );
357
358 /**
359 * Add the specified number of days from this time instant.
360 *
361 * @param days the number of days to add
362 * @return the instance in time the specified number of days after this instant
363 */
364 DateTime plusDays( int days );
365
366 /**
367 * Add the specified number of hours from this time instant.
368 *
369 * @param hours the number of hours to add
370 * @return the instance in time the specified number of hours after this instant
371 */
372 DateTime plusHours( int hours );
373
374 /**
375 * Add the specified number of milliseconds from this time instant.
376 *
377 * @param milliseconds the number of milliseconds to add
378 * @return the instance in time the specified number of milliseconds after this instant
379 */
380 DateTime plusMillis( int milliseconds );
381
382 /**
383 * Add the specified number of minutes from this time instant.
384 *
385 * @param minutes the number of minutes to add
386 * @return the instance in time the specified number of minutes after this instant
387 */
388 DateTime plusMinutes( int minutes );
389
390 /**
391 * Add the specified number of months from this time instant.
392 *
393 * @param months the number of months to add
394 * @return the instance in time the specified number of months after this instant
395 */
396 DateTime plusMonths( int months );
397
398 /**
399 * Add the specified number of seconds from this time instant.
400 *
401 * @param seconds the number of seconds to add
402 * @return the instance in time the specified number of seconds after this instant
403 */
404 DateTime plusSeconds( int seconds );
405
406 /**
407 * Add the specified number of weeks from this time instant.
408 *
409 * @param weeks the number of weeks to add
410 * @return the instance in time the specified number of weeks after this instant
411 */
412 DateTime plusWeeks( int weeks );
413
414 /**
415 * Add the specified number of years from this time instant.
416 *
417 * @param years the number of years to add
418 * @return the instance in time the specified number of years after this instant
419 */
420 DateTime plusYears( int years );
421
422 }