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 }