1// =================================================================================================
2// ADOBE SYSTEMS INCORPORATED
3// Copyright 2006 Adobe Systems Incorporated
4// All Rights Reserved
5//
6// NOTICE:  Adobe permits you to use, modify, and distribute this file in accordance with the terms
7// of the Adobe license agreement accompanying it.
8// =================================================================================================
9
10package com.adobe.xmp;
11
12import java.util.Calendar;
13import java.util.TimeZone;
14
15
16/**
17 * The <code>XMPDateTime</code>-class represents a point in time up to a resolution of nano
18 * seconds. Dates and time in the serialized XMP are ISO 8601 strings. There are utility functions
19 * to convert to the ISO format, a <code>Calendar</code> or get the Timezone. The fields of
20 * <code>XMPDateTime</code> are:
21 * <ul>
22 * <li> month - The month in the range 1..12.
23 * <li> day - The day of the month in the range 1..31.
24 * <li> minute - The minute in the range 0..59.
25 * <li> hour - The time zone hour in the range 0..23.
26 * <li> minute - The time zone minute in the range 0..59.
27 * <li> nanoSecond - The nano seconds within a second. <em>Note:</em> if the XMPDateTime is
28 * converted into a calendar, the resolution is reduced to milli seconds.
29 * <li> timeZone - a <code>TimeZone</code>-object.
30 * </ul>
31 * DateTime values are occasionally used in cases with only a date or only a time component. A date
32 * without a time has zeros for all the time fields. A time without a date has zeros for all date
33 * fields (year, month, and day).
34 */
35public interface XMPDateTime extends Comparable
36{
37	/** @return Returns the year, can be negative. */
38	int getYear();
39
40	/** @param year Sets the year */
41	void setYear(int year);
42
43	/** @return Returns The month in the range 1..12. */
44	int getMonth();
45
46	/** @param month Sets the month 1..12 */
47	void setMonth(int month);
48
49	/** @return Returns the day of the month in the range 1..31. */
50	int getDay();
51
52	/** @param day Sets the day 1..31 */
53	void setDay(int day);
54
55	/** @return Returns hour - The hour in the range 0..23. */
56	int getHour();
57
58	/** @param hour Sets the hour in the range 0..23. */
59	void setHour(int hour);
60
61	/** @return Returns the minute in the range 0..59. */
62	int getMinute();
63
64	/** @param minute Sets the minute in the range 0..59. */
65	void setMinute(int minute);
66
67	/** @return Returns the second in the range 0..59. */
68	int getSecond();
69
70	/** @param second Sets the second in the range 0..59. */
71	void setSecond(int second);
72
73	/**
74	 * @return Returns milli-, micro- and nano seconds.
75	 * 		   Nanoseconds within a second, often left as zero?
76	 */
77	int getNanoSecond();
78
79	/**
80	 * @param nanoSecond Sets the milli-, micro- and nano seconds.
81	 *		Granularity goes down to milli seconds.
82	 */
83	void setNanoSecond(int nanoSecond);
84
85	/** @return Returns the time zone. */
86	TimeZone getTimeZone();
87
88	/** @param tz a time zone to set */
89	void setTimeZone(TimeZone tz);
90
91	/**
92	 * @return Returns a <code>Calendar</code> (only with milli second precision). <br>
93	 *  		<em>Note:</em> the dates before Oct 15th 1585 (which normally fall into validity of
94	 *  		the Julian calendar) are also rendered internally as Gregorian dates.
95	 */
96	Calendar getCalendar();
97
98	/**
99	 * @return Returns the ISO 8601 string representation of the date and time.
100	 */
101	String getISO8601String();
102}