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 /**
27 * A factory for creating {@link DateTime date-time instants}. This interface extends the {@link ValueFactory} generic interface
28 * and adds specific methods for creating instants for the current time (and time zone) as well as various combinations of
29 * individual field values. <h2>ISO-8601</h2>
30 * <p>
31 * The factory creates date-time instants from strings that are in the standard ISO-8601 format. There are three supported styles:
32 * month-based, day-of-year-based, and week-based.
33 * </p>
34 * <h3>Month-Based</h3>
35 * <p>
36 * The month-based representation is the most common format of ISO8601, and is the format used in the XML standards for passing
37 * dates and times:
38 *
39 * <pre>
40 * yyyy-mm-ddTHH:MM:SS.SSSZ
41 * </pre>
42 *
43 * The fields are separated by dashes and consist of:
44 * <ul>
45 * <li>four digit year;</li>
46 * <li>two digit month, where 01 is Janurary and 12 is December;</li>
47 * <li>two digit day of month, from 01 to 31;</li>
48 * <li>two digit hour, from 00 to 23;</li>
49 * <li>two digit minute, from 00 to 59;</li>
50 * <li>two digit second, from 00 to 59;</li>
51 * <li>three decimal places for milliseconds, if required;</li>
52 * <li>time zone offset of the form <code>�HH:mm</code> (or '0' if UTC)</li>
53 * </ul>
54 * </p>
55 * <h3>Day of Year Based</h3>
56 * <p>
57 * This format of ISO-8601 uses a single field to represent the day of the year:
58 *
59 * <pre>
60 * yyyy-dddTHH:MM:SS.SSSZ
61 * </pre>
62 *
63 * The fields are separated by dashes and consist of:
64 * <ul>
65 * <li>four digit year</li>
66 * <li>three digit day of year, from 001 to 366;</li>
67 * <li>two digit hour, from 00 to 23;</li>
68 * <li>two digit minute, from 00 to 59;</li>
69 * <li>two digit second, from 00 to 59;</li>
70 * <li>three decimal places for milliseconds, if required;</li>
71 * <li>time zone offset of the form <code>�HH:mm</code> (or '0' if UTC)</li>
72 * </ul>
73 * </p>
74 * <h3>Week Based</h3>
75 * <p>
76 * This format of ISO-8601 uses a single field to represent the day of the year:
77 *
78 * <pre>
79 * yyyy-Www-dTHH:MM:SS.SSSZ
80 * </pre>
81 *
82 * The fields are separated by dashes and consist of:
83 * <ul>
84 * <li>four digit weekyear (see below)</li>
85 * <li>two digit week of year, from 01 to 53;</li>
86 * <li>one digit day of week, from 1 to 7 where 1 is Monday and 7 is Sunday;</li>
87 * <li>two digit hour, from 00 to 23;</li>
88 * <li>two digit minute, from 00 to 59;</li>
89 * <li>two digit second, from 00 to 59;</li>
90 * <li>three decimal places for milliseconds, if required;</li>
91 * <li>time zone offset of the form <code>�HH:mm</code> (or '0' if UTC)</li>
92 * </ul>
93 * </p>
94 * <p>
95 * From <a href="http://joda-time.sourceforge.net/cal_iso.html">Joda-Time</a>: Weeks are always complete, and the first week of a
96 * year is the one that includes the first Thursday of the year. This definition can mean that the first week of a year starts in
97 * the previous year, and the last week finishes in the next year. The weekyear field is defined to refer to the year that owns
98 * the week, which may differ from the actual year.
99 * </p>
100 */
101 public interface DateTimeFactory extends ValueFactory<DateTime> {
102
103 /**
104 * Create a date-time instance for the current time in the local time zone.
105 *
106 * @return the current date-time instance
107 * @see #createUtc()
108 */
109 DateTime create();
110
111 /**
112 * Create a date-time instance for the current time in UTC.
113 *
114 * @return the current date-time instance (in UTC)
115 * @see #create()
116 */
117 DateTime createUtc();
118
119 /**
120 * Create a date-time instance that is offset from the original by the specified amount.
121 *
122 * @param original
123 * @param offsetInMillis the offset in milliseconds (positive or negative)
124 * @return the offset date-time instance
125 */
126 DateTime create( DateTime original,
127 long offsetInMillis );
128
129 /**
130 * Create a date-time instance given the individual values for the fields
131 *
132 * @param year the year of the era
133 * @param monthOfYear the month of the year
134 * @param dayOfMonth the day of the month
135 * @param hourOfDay the hour of the day
136 * @param minuteOfHour the minute of the hour
137 * @param secondOfMinute the second of the minute
138 * @param millisecondsOfSecond the milliseconds of the second
139 * @return the date-time instance
140 */
141 DateTime create( int year,
142 int monthOfYear,
143 int dayOfMonth,
144 int hourOfDay,
145 int minuteOfHour,
146 int secondOfMinute,
147 int millisecondsOfSecond );
148
149 /**
150 * Create a date-time instance given the individual values for the fields
151 *
152 * @param year the year of the era
153 * @param monthOfYear the month of the year
154 * @param dayOfMonth the day of the month
155 * @param hourOfDay the hour of the day
156 * @param minuteOfHour the minute of the hour
157 * @param secondOfMinute the second of the minute
158 * @param millisecondsOfSecond the milliseconds of the second
159 * @param timeZoneOffsetHours the number of hours offset from UTC for the time zone
160 * @return the date-time instance
161 */
162 DateTime create( int year,
163 int monthOfYear,
164 int dayOfMonth,
165 int hourOfDay,
166 int minuteOfHour,
167 int secondOfMinute,
168 int millisecondsOfSecond,
169 int timeZoneOffsetHours );
170
171 /**
172 * Create a date-time instance given the individual values for the fields
173 *
174 * @param year the year of the era
175 * @param monthOfYear the month of the year
176 * @param dayOfMonth the day of the month
177 * @param hourOfDay the hour of the day
178 * @param minuteOfHour the minute of the hour
179 * @param secondOfMinute the second of the minute
180 * @param millisecondsOfSecond the milliseconds of the second
181 * @param timeZoneId the ID of the time zone (e.g, "PST", "UTC", "EDT"); may not be null
182 * @return the date-time instance
183 */
184 DateTime create( int year,
185 int monthOfYear,
186 int dayOfMonth,
187 int hourOfDay,
188 int minuteOfHour,
189 int secondOfMinute,
190 int millisecondsOfSecond,
191 String timeZoneId );
192
193 }