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