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
027 /**
028 * A factory for creating {@link DateTime date-time instants}. This interface extends the {@link ValueFactory} generic interface
029 * and adds specific methods for creating instants for the current time (and time zone) as well as various combinations of
030 * individual field values. <h2>ISO-8601</h2>
031 * <p>
032 * The factory creates date-time instants from strings that are in the standard ISO-8601 format. There are three supported styles:
033 * month-based, day-of-year-based, and week-based.
034 * </p>
035 * <h3>Month-Based</h3>
036 * <p>
037 * The month-based representation is the most common format of ISO8601, and is the format used in the XML standards for passing
038 * dates and times:
039 *
040 * <pre>
041 * yyyy-mm-ddTHH:MM:SS.SSSZ
042 * </pre>
043 *
044 * The fields are separated by dashes and consist of:
045 * <ul>
046 * <li>four digit year;</li>
047 * <li>two digit month, where 01 is Janurary and 12 is December;</li>
048 * <li>two digit day of month, from 01 to 31;</li>
049 * <li>two digit hour, from 00 to 23;</li>
050 * <li>two digit minute, from 00 to 59;</li>
051 * <li>two digit second, from 00 to 59;</li>
052 * <li>three decimal places for milliseconds, if required;</li>
053 * <li>time zone offset of the form <code>±HH:mm</code> (or '0' if UTC)</li>
054 * </ul>
055 * </p>
056 * <h3>Day of Year Based</h3>
057 * <p>
058 * This format of ISO-8601 uses a single field to represent the day of the year:
059 *
060 * <pre>
061 * yyyy-dddTHH:MM:SS.SSSZ
062 * </pre>
063 *
064 * The fields are separated by dashes and consist of:
065 * <ul>
066 * <li>four digit year</li>
067 * <li>three digit day of year, from 001 to 366;</li>
068 * <li>two digit hour, from 00 to 23;</li>
069 * <li>two digit minute, from 00 to 59;</li>
070 * <li>two digit second, from 00 to 59;</li>
071 * <li>three decimal places for milliseconds, if required;</li>
072 * <li>time zone offset of the form <code>±HH:mm</code> (or '0' if UTC)</li>
073 * </ul>
074 * </p>
075 * <h3>Week Based</h3>
076 * <p>
077 * This format of ISO-8601 uses a single field to represent the day of the year:
078 *
079 * <pre>
080 * yyyy-Www-dTHH:MM:SS.SSSZ
081 * </pre>
082 *
083 * The fields are separated by dashes and consist of:
084 * <ul>
085 * <li>four digit weekyear (see below)</li>
086 * <li>two digit week of year, from 01 to 53;</li>
087 * <li>one digit day of week, from 1 to 7 where 1 is Monday and 7 is Sunday;</li>
088 * <li>two digit hour, from 00 to 23;</li>
089 * <li>two digit minute, from 00 to 59;</li>
090 * <li>two digit second, from 00 to 59;</li>
091 * <li>three decimal places for milliseconds, if required;</li>
092 * <li>time zone offset of the form <code>±HH:mm</code> (or '0' if UTC)</li>
093 * </ul>
094 * </p>
095 * <p>
096 * From <a href="http://joda-time.sourceforge.net/cal_iso.html">Joda-Time</a>: Weeks are always complete, and the first week of a
097 * 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
098 * the previous year, and the last week finishes in the next year. The weekyear field is defined to refer to the year that owns
099 * the week, which may differ from the actual year.
100 * </p>
101 *
102 * @author Randall Hauch
103 */
104 public interface DateTimeFactory extends ValueFactory<DateTime> {
105
106 /**
107 * Create a date-time instance for the current time in the local time zone.
108 *
109 * @return the current date-time instance
110 * @see #createUtc()
111 */
112 DateTime create();
113
114 /**
115 * Create a date-time instance for the current time in UTC.
116 *
117 * @return the current date-time instance (in UTC)
118 * @see #create()
119 */
120 DateTime createUtc();
121
122 /**
123 * Create a date-time instance that is offset from the original by the specified amount.
124 *
125 * @param original
126 * @param offsetInMillis the offset in milliseconds (positive or negative)
127 * @return the offset date-time instance
128 */
129 DateTime create( DateTime original,
130 long offsetInMillis );
131
132 /**
133 * Create a date-time instance given the individual values for the fields
134 *
135 * @param year the year of the era
136 * @param monthOfYear the month of the year
137 * @param dayOfMonth the day of the month
138 * @param hourOfDay the hour of the day
139 * @param minuteOfHour the minute of the hour
140 * @param secondOfMinute the second of the minute
141 * @param millisecondsOfSecond the milliseconds of the second
142 * @return the date-time instance
143 */
144 DateTime create( int year,
145 int monthOfYear,
146 int dayOfMonth,
147 int hourOfDay,
148 int minuteOfHour,
149 int secondOfMinute,
150 int millisecondsOfSecond );
151
152 /**
153 * Create a date-time instance given the individual values for the fields
154 *
155 * @param year the year of the era
156 * @param monthOfYear the month of the year
157 * @param dayOfMonth the day of the month
158 * @param hourOfDay the hour of the day
159 * @param minuteOfHour the minute of the hour
160 * @param secondOfMinute the second of the minute
161 * @param millisecondsOfSecond the milliseconds of the second
162 * @param timeZoneOffsetHours the number of hours offset from UTC for the time zone
163 * @return the date-time instance
164 */
165 DateTime create( int year,
166 int monthOfYear,
167 int dayOfMonth,
168 int hourOfDay,
169 int minuteOfHour,
170 int secondOfMinute,
171 int millisecondsOfSecond,
172 int timeZoneOffsetHours );
173
174 /**
175 * Create a date-time instance given the individual values for the fields
176 *
177 * @param year the year of the era
178 * @param monthOfYear the month of the year
179 * @param dayOfMonth the day of the month
180 * @param hourOfDay the hour of the day
181 * @param minuteOfHour the minute of the hour
182 * @param secondOfMinute the second of the minute
183 * @param millisecondsOfSecond the milliseconds of the second
184 * @param timeZoneId the ID of the time zone (e.g, "PST", "UTC", "EDT"); may not be null
185 * @return the date-time instance
186 */
187 DateTime create( int year,
188 int monthOfYear,
189 int dayOfMonth,
190 int hourOfDay,
191 int minuteOfHour,
192 int secondOfMinute,
193 int millisecondsOfSecond,
194 String timeZoneId );
195
196 }