1 /*
2 * ModeShape (http://www.modeshape.org)
3 * See the COPYRIGHT.txt file distributed with this work for information
4 * regarding copyright ownership. Some portions may be licensed
5 * to Red Hat, Inc. under one or more contributor license agreements.
6 * See the AUTHORS.txt file in the distribution for a full listing of
7 * individual contributors.
8 *
9 * ModeShape is free software. Unless otherwise indicated, all code in ModeShape
10 * is licensed to you under the terms of the GNU Lesser General Public License as
11 * published by the Free Software Foundation; either version 2.1 of
12 * the License, or (at your option) any later version.
13 *
14 * ModeShape is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 * Lesser General Public License for more details.
18 *
19 * You should have received a copy of the GNU Lesser General Public
20 * License along with this software; if not, write to the Free
21 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
22 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
23 */
24 package org.modeshape.graph.property;
25
26 import java.io.Serializable;
27 import java.util.Locale;
28 import java.util.concurrent.TimeUnit;
29 import net.jcip.annotations.Immutable;
30
31 /**
32 * An immutable date-time class that represents an instance in time. This class is designed to hide the horrible implementations
33 * of the JDK date and calendar classes, which are being overhauled (and replaced) under <a
34 * href="http://jcp.org/en/jsr/detail?id=310">JSR-310</a>, which will be based upon <a
35 * href="http://joda-time.sourceforge.net/">Joda-Time</a>. This class serves as a stable migration path toward the new JSR 310
36 * classes.
37 */
38 @Immutable
39 public interface DateTime extends Comparable<DateTime>, Serializable {
40
41 /**
42 * Get the ISO-8601 representation of this instance in time. The month-based ISO-8601 representation is the most common format
43 * of ISO8601, and is the format used in the XML standards for passing dates and times:
44 *
45 * <pre>
46 * yyyy-mm-ddTHH:MM:SS.SSSZ
47 * </pre>
48 *
49 * The fields are separated by dashes and consist of:
50 * <ul>
51 * <li>four digit year;</li>
52 * <li>two digit month, where 01 is Janurary and 12 is December;</li>
53 * <li>two digit day of month, from 01 to 31;</li>
54 * <li>two digit hour, from 00 to 23;</li>
55 * <li>two digit minute, from 00 to 59;</li>
56 * <li>two digit second, from 00 to 59;</li>
57 * <li>three decimal places for milliseconds, if required;</li>
58 * <li>time zone offset of the form <code>�HH:mm</code> (or '0' if UTC)</li>
59 * </ul>
60 *
61 * @return the string representation; never null
62 */
63 String getString();
64
65 /**
66 * Get the number of milliseconds from 1970-01-01T00:00Z. This value is consistent with the JDK {@link java.util.Date Date}
67 * and {@link java.util.Calendar Calendar} classes.
68 *
69 * @return the number of milliseconds from 1970-01-01T00:00Z
70 */
71 long getMilliseconds();
72
73 /**
74 * Get the number of milliseconds from 1970-01-01T00:00Z with this time converted to UTC. This value is consistent with the
75 * JDK {@link java.util.Date Date} and {@link java.util.Calendar Calendar} classes.
76 *
77 * @return the number of milliseconds from 1970-01-01T00:00Z in the UTC time zone
78 */
79 long getMillisecondsInUtc();
80
81 /**
82 * Get this instance represented as a standard JDK {@link java.util.Date} instance. Note that this conversion loses the time
83 * zone information, as the standard JDK {@link java.util.Date} does not represent time zones.
84 *
85 * @return this instance in time as a JDK Date; never null
86 */
87 java.util.Date toDate();
88
89 /**
90 * Get this instance represented as a standard JDK {@link java.util.Calendar} instance, in the {@link Locale#getDefault()
91 * default locale}.
92 *
93 * @return this instance in time as a JDK Calendar; never null
94 */
95 java.util.Calendar toCalendar();
96
97 /**
98 * Get this instance represented as a standard JDK {@link java.util.Calendar} instance, in the specified {@link Locale locale}
99 * .
100 *
101 * @param locale the locale in which the Calendar instance is desired; may be null if the {@link Locale#getDefault() default
102 * locale} is to be used.
103 * @return this instance in time as a JDK Calendar; never null
104 */
105 java.util.Calendar toCalendar( Locale locale );
106
107 /**
108 * Get this instance represented as a standard JDK {@link java.util.GregorianCalendar} instance.
109 *
110 * @return this instance in time as a JDK GregorianCalendar; never null
111 */
112 java.util.GregorianCalendar toGregorianCalendar();
113
114 /**
115 * Get the era of this instance in time.
116 *
117 * @return the era
118 */
119 int getEra();
120
121 /**
122 * Get the era of this instance in time.
123 *
124 * @return the era
125 */
126 int getYear();
127
128 /**
129 * Get the era of this instance in time.
130 *
131 * @return the era
132 */
133 int getWeekyear();
134
135 /**
136 * Get the era of this instance in time.
137 *
138 * @return the era
139 */
140 int getCenturyOfEra();
141
142 /**
143 * Get the year of the era of this instance in time.
144 *
145 * @return the year of the era
146 */
147 int getYearOfEra();
148
149 /**
150 * Get the year of this century of this instance in time.
151 *
152 * @return the year of the century
153 */
154 int getYearOfCentury();
155
156 /**
157 * Get the month of the year of this instance in time.
158 *
159 * @return the month number
160 */
161 int getMonthOfYear();
162
163 /**
164 * Get the week of the weekyear of this instance in time.
165 *
166 * @return the week of the weekyear
167 */
168 int getWeekOfWeekyear();
169
170 /**
171 * Get the day of the year of this instance in time.
172 *
173 * @return the day of the year
174 */
175 int getDayOfYear();
176
177 /**
178 * Get the day of the month value of this instance in time.
179 *
180 * @return the day of the month
181 */
182 int getDayOfMonth();
183
184 /**
185 * Get the day of the week value of this instance in time.
186 *
187 * @return the day of the week
188 */
189 int getDayOfWeek();
190
191 /**
192 * Get the hour of the day of this instance in time.
193 *
194 * @return the hour of the day
195 */
196 int getHourOfDay();
197
198 /**
199 * Get the minute of this instance in time.
200 *
201 * @return the minute of the hour
202 */
203 int getMinuteOfHour();
204
205 /**
206 * Get the seconds of the minute value of this instance in time.
207 *
208 * @return the seconds of the minute
209 */
210 int getSecondOfMinute();
211
212 /**
213 * Get the milliseconds of the second value of this instance in time.
214 *
215 * @return the milliseconds
216 */
217 int getMillisOfSecond();
218
219 /**
220 * Get the number of hours that this time zone is offset from UTC.
221 *
222 * @return the number of hours
223 */
224 int getTimeZoneOffsetHours();
225
226 /**
227 * Get the identifier of the time zone in which this instant is defined
228 *
229 * @return the time zone identifier; never null
230 */
231 String getTimeZoneId();
232
233 /**
234 * Convert this time to the same instant in the UTC time zone.
235 *
236 * @return this instant in time in the specified time zone
237 */
238 DateTime toUtcTimeZone();
239
240 /**
241 * Convert this time to the time zone given by the supplied identifier.
242 *
243 * @param timeZoneId the time zone identifier
244 * @return the instant in the specified time zone
245 * @throws IllegalArgumentException if the time zone identifier is null or is invalid
246 */
247 DateTime toTimeZone( String timeZoneId );
248
249 /**
250 * Return whether this date-time is earlier than the supplied date-time.
251 *
252 * @param other the date-time to compare with
253 * @return true if this date-time is earliar than the other, or false otherwise
254 * @see #compareTo(DateTime)
255 * @see #isSameAs(DateTime)
256 * @see #isAfter(DateTime)
257 */
258 boolean isBefore( DateTime other );
259
260 /**
261 * Return whether this date-time is later than the supplied date-time.
262 *
263 * @param other the date-time to compare with
264 * @return true if this date-time is later than the other, or false otherwise
265 * @see #compareTo(DateTime)
266 * @see #isBefore(DateTime)
267 * @see #isSameAs(DateTime)
268 */
269 boolean isAfter( DateTime other );
270
271 /**
272 * Return whether this date-time is exactly the the same as the supplied date-time. This differs from {@link #equals(Object)
273 * the equals method} in that it can be arbitrarily more strict, checking, for example, not only the logical equivalence of
274 * the other date time, but also arbitrary additional fields such as the time zone.
275 *
276 * @param other the date-time to compare with
277 * @return true if this date-time is later than the other, or false otherwise
278 * @see #compareTo(DateTime)
279 * @see #isBefore(DateTime)
280 * @see #isAfter(DateTime)
281 */
282 boolean isSameAs( DateTime other );
283
284 /**
285 * Subtract the specified about of time in the supplied units.
286 *
287 * @param timeAmount the amount of time to subtract
288 * @param unit the units of the amount of time; may not be null
289 * @return the instance in time the specified number of time before this instant
290 */
291 DateTime minus( long timeAmount,
292 TimeUnit unit );
293
294 /**
295 * Subtract the specified number of days from this time instant.
296 *
297 * @param days the number of days to subtract
298 * @return the instance in time the specified number of days before this instant
299 */
300 DateTime minusDays( int days );
301
302 /**
303 * Subtract the specified number of hours from this time instant.
304 *
305 * @param hours the number of hours to subtract
306 * @return the instance in time the specified number of hours before this instant
307 */
308 DateTime minusHours( int hours );
309
310 /**
311 * Subtract the specified number of milliseconds from this time instant.
312 *
313 * @param milliseconds the number of milliseconds to subtract
314 * @return the instance in time the specified number of milliseconds before this instant
315 */
316 DateTime minusMillis( int milliseconds );
317
318 /**
319 * Subtract the specified number of minutes from this time instant.
320 *
321 * @param minutes the number of minutes to subtract
322 * @return the instance in time the specified number of minutes before this instant
323 */
324 DateTime minusMinutes( int minutes );
325
326 /**
327 * Subtract the specified number of months from this time instant.
328 *
329 * @param months the number of months to subtract
330 * @return the instance in time the specified number of months before this instant
331 */
332 DateTime minusMonths( int months );
333
334 /**
335 * Subtract the specified number of seconds from this time instant.
336 *
337 * @param seconds the number of seconds to subtract
338 * @return the instance in time the specified number of seconds before this instant
339 */
340 DateTime minusSeconds( int seconds );
341
342 /**
343 * Subtract the specified number of weeks from this time instant.
344 *
345 * @param weeks the number of weeks to subtract
346 * @return the instance in time the specified number of weeks before this instant
347 */
348 DateTime minusWeeks( int weeks );
349
350 /**
351 * Subtract the specified number of years from this time instant.
352 *
353 * @param years the number of years to subtract
354 * @return the instance in time the specified number of years before this instant
355 */
356 DateTime minusYears( int years );
357
358 /**
359 * Add the specified about of time in the supplied units.
360 *
361 * @param timeAmount the amount of time to add
362 * @param unit the units of the amount of time; may not be null
363 * @return the instance in time the specified number of time after this instant
364 */
365 DateTime plus( long timeAmount,
366 TimeUnit unit );
367
368 /**
369 * Add the specified number of days from this time instant.
370 *
371 * @param days the number of days to add
372 * @return the instance in time the specified number of days after this instant
373 */
374 DateTime plusDays( int days );
375
376 /**
377 * Add the specified number of hours from this time instant.
378 *
379 * @param hours the number of hours to add
380 * @return the instance in time the specified number of hours after this instant
381 */
382 DateTime plusHours( int hours );
383
384 /**
385 * Add the specified number of milliseconds from this time instant.
386 *
387 * @param milliseconds the number of milliseconds to add
388 * @return the instance in time the specified number of milliseconds after this instant
389 */
390 DateTime plusMillis( int milliseconds );
391
392 /**
393 * Add the specified number of minutes from this time instant.
394 *
395 * @param minutes the number of minutes to add
396 * @return the instance in time the specified number of minutes after this instant
397 */
398 DateTime plusMinutes( int minutes );
399
400 /**
401 * Add the specified number of months from this time instant.
402 *
403 * @param months the number of months to add
404 * @return the instance in time the specified number of months after this instant
405 */
406 DateTime plusMonths( int months );
407
408 /**
409 * Add the specified number of seconds from this time instant.
410 *
411 * @param seconds the number of seconds to add
412 * @return the instance in time the specified number of seconds after this instant
413 */
414 DateTime plusSeconds( int seconds );
415
416 /**
417 * Add the specified number of weeks from this time instant.
418 *
419 * @param weeks the number of weeks to add
420 * @return the instance in time the specified number of weeks after this instant
421 */
422 DateTime plusWeeks( int weeks );
423
424 /**
425 * Add the specified number of years from this time instant.
426 *
427 * @param years the number of years to add
428 * @return the instance in time the specified number of years after this instant
429 */
430 DateTime plusYears( int years );
431
432 }