001 /*
002 * JBoss, Home of Professional Open Source.
003 * Copyright 2008, Red Hat Middleware LLC, and individual contributors
004 * as indicated by the @author tags. See the copyright.txt file in the
005 * distribution for a full listing of individual contributors.
006 *
007 * This is free software; you can redistribute it and/or modify it
008 * under the terms of the GNU Lesser General Public License as
009 * published by the Free Software Foundation; either version 2.1 of
010 * the License, or (at your option) any later version.
011 *
012 * This software is distributed in the hope that it will be useful,
013 * but WITHOUT ANY WARRANTY; without even the implied warranty of
014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015 * Lesser General Public License for more details.
016 *
017 * You should have received a copy of the GNU Lesser General Public
018 * License along with this software; if not, write to the Free
019 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
021 */
022 package org.jboss.dna.graph.properties;
023
024
025 /**
026 * A factory for creating {@link DateTime date-time instants}. This interface extends the {@link ValueFactory} generic interface
027 * and adds specific methods for creating instants for the current time (and time zone) as well as various combinations of
028 * individual field values. <h2>ISO-8601</h2>
029 * <p>
030 * The factory creates date-time instants from strings that are in the standard ISO-8601 format. There are three supported styles:
031 * month-based, day-of-year-based, and week-based.
032 * </p>
033 * <h3>Month-Based</h3>
034 * <p>
035 * The month-based representation is the most common format of ISO8601, and is the format used in the XML standards for passing
036 * dates and times:
037 *
038 * <pre>
039 * yyyy-mm-ddTHH:MM:SS.SSSZ
040 * </pre>
041 *
042 * The fields are separated by dashes and consist of:
043 * <ul>
044 * <li>four digit year;</li>
045 * <li>two digit month, where 01 is Janurary and 12 is December;</li>
046 * <li>two digit day of month, from 01 to 31;</li>
047 * <li>two digit hour, from 00 to 23;</li>
048 * <li>two digit minute, from 00 to 59;</li>
049 * <li>two digit second, from 00 to 59;</li>
050 * <li>three decimal places for milliseconds, if required;</li>
051 * <li>time zone offset of the form <code>±HH:mm</code> (or '0' if UTC)</li>
052 * </ul>
053 * </p>
054 * <h3>Day of Year Based</h3>
055 * <p>
056 * This format of ISO-8601 uses a single field to represent the day of the year:
057 *
058 * <pre>
059 * yyyy-dddTHH:MM:SS.SSSZ
060 * </pre>
061 *
062 * The fields are separated by dashes and consist of:
063 * <ul>
064 * <li>four digit year</li>
065 * <li>three digit day of year, from 001 to 366;</li>
066 * <li>two digit hour, from 00 to 23;</li>
067 * <li>two digit minute, from 00 to 59;</li>
068 * <li>two digit second, from 00 to 59;</li>
069 * <li>three decimal places for milliseconds, if required;</li>
070 * <li>time zone offset of the form <code>±HH:mm</code> (or '0' if UTC)</li>
071 * </ul>
072 * </p>
073 * <h3>Week Based</h3>
074 * <p>
075 * This format of ISO-8601 uses a single field to represent the day of the year:
076 *
077 * <pre>
078 * yyyy-Www-dTHH:MM:SS.SSSZ
079 * </pre>
080 *
081 * The fields are separated by dashes and consist of:
082 * <ul>
083 * <li>four digit weekyear (see below)</li>
084 * <li>two digit week of year, from 01 to 53;</li>
085 * <li>one digit day of week, from 1 to 7 where 1 is Monday and 7 is Sunday;</li>
086 * <li>two digit hour, from 00 to 23;</li>
087 * <li>two digit minute, from 00 to 59;</li>
088 * <li>two digit second, from 00 to 59;</li>
089 * <li>three decimal places for milliseconds, if required;</li>
090 * <li>time zone offset of the form <code>±HH:mm</code> (or '0' if UTC)</li>
091 * </ul>
092 * </p>
093 * <p>
094 * From <a href="http://joda-time.sourceforge.net/cal_iso.html">Joda-Time</a>: Weeks are always complete, and the first week of a
095 * 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
096 * the previous year, and the last week finishes in the next year. The weekyear field is defined to refer to the year that owns
097 * the week, which may differ from the actual year.
098 * </p>
099 *
100 * @author Randall Hauch
101 */
102 public interface DateTimeFactory extends ValueFactory<DateTime> {
103
104 /**
105 * Create a date-time instance for the current time in the local time zone.
106 *
107 * @return the current date-time instance
108 * @see #createUtc()
109 */
110 DateTime create();
111
112 /**
113 * Create a date-time instance for the current time in UTC.
114 *
115 * @return the current date-time instance (in UTC)
116 * @see #create()
117 */
118 DateTime createUtc();
119
120 /**
121 * Create a date-time instance that is offset from the original by the specified amount.
122 *
123 * @param original
124 * @param offsetInMillis the offset in milliseconds (positive or negative)
125 * @return the offset date-time instance
126 */
127 DateTime create( DateTime original,
128 long offsetInMillis );
129
130 /**
131 * Create a date-time instance given the individual values for the fields
132 *
133 * @param year the year of the era
134 * @param monthOfYear the month of the year
135 * @param dayOfMonth the day of the month
136 * @param hourOfDay the hour of the day
137 * @param minuteOfHour the minute of the hour
138 * @param secondOfMinute the second of the minute
139 * @param millisecondsOfSecond the milliseconds of the second
140 * @return the date-time instance
141 */
142 DateTime create( int year,
143 int monthOfYear,
144 int dayOfMonth,
145 int hourOfDay,
146 int minuteOfHour,
147 int secondOfMinute,
148 int millisecondsOfSecond );
149
150 /**
151 * Create a date-time instance given the individual values for the fields
152 *
153 * @param year the year of the era
154 * @param monthOfYear the month of the year
155 * @param dayOfMonth the day of the month
156 * @param hourOfDay the hour of the day
157 * @param minuteOfHour the minute of the hour
158 * @param secondOfMinute the second of the minute
159 * @param millisecondsOfSecond the milliseconds of the second
160 * @param timeZoneOffsetHours the number of hours offset from UTC for the time zone
161 * @return the date-time instance
162 */
163 DateTime create( int year,
164 int monthOfYear,
165 int dayOfMonth,
166 int hourOfDay,
167 int minuteOfHour,
168 int secondOfMinute,
169 int millisecondsOfSecond,
170 int timeZoneOffsetHours );
171
172 /**
173 * Create a date-time instance given the individual values for the fields
174 *
175 * @param year the year of the era
176 * @param monthOfYear the month of the year
177 * @param dayOfMonth the day of the month
178 * @param hourOfDay the hour of the day
179 * @param minuteOfHour the minute of the hour
180 * @param secondOfMinute the second of the minute
181 * @param millisecondsOfSecond the milliseconds of the second
182 * @param timeZoneId the ID of the time zone (e.g, "PST", "UTC", "EDT"); may not be null
183 * @return the date-time instance
184 */
185 DateTime create( int year,
186 int monthOfYear,
187 int dayOfMonth,
188 int hourOfDay,
189 int minuteOfHour,
190 int secondOfMinute,
191 int millisecondsOfSecond,
192 String timeZoneId );
193
194 }