001 /*
002 * Copyright 2001-2011 Stephen Colebourne
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.joda.time;
017
018 import java.util.Locale;
019
020 /**
021 * Defines an instant in time that can be queried using datetime fields.
022 * <p>
023 * The implementation of this interface may be mutable or immutable.
024 * This interface only gives access to retrieve data, never to change it.
025 * <p>
026 * Methods in your application should be defined using <code>ReadableDateTime</code>
027 * as a parameter if the method only wants to read the datetime, and not perform
028 * any advanced manipulations.
029 *
030 * @author Stephen Colebourne
031 * @author Brian S O'Neill
032 * @since 1.0
033 */
034 public interface ReadableDateTime extends ReadableInstant {
035
036 /**
037 * Get the day of week field value.
038 * <p>
039 * The values for the day of week are defined in {@link DateTimeConstants}.
040 *
041 * @return the day of week
042 */
043 int getDayOfWeek();
044
045 /**
046 * Get the day of month field value.
047 *
048 * @return the day of month
049 */
050 int getDayOfMonth();
051
052 /**
053 * Get the day of year field value.
054 *
055 * @return the day of year
056 */
057 int getDayOfYear();
058
059 /**
060 * Get the week of weekyear field value.
061 * <p>
062 * This field is associated with the "weekyear" via {@link #getWeekyear()}.
063 * In the standard ISO8601 week algorithm, the first week of the year
064 * is that in which at least 4 days are in the year. As a result of this
065 * definition, day 1 of the first week may be in the previous year.
066 *
067 * @return the week of a week based year
068 */
069 int getWeekOfWeekyear();
070
071 /**
072 * Get the weekyear field value.
073 * <p>
074 * The weekyear is the year that matches with the weekOfWeekyear field.
075 * In the standard ISO8601 week algorithm, the first week of the year
076 * is that in which at least 4 days are in the year. As a result of this
077 * definition, day 1 of the first week may be in the previous year.
078 * The weekyear allows you to query the effective year for that day.
079 *
080 * @return the year of a week based year
081 */
082 int getWeekyear();
083
084 /**
085 * Get the month of year field value.
086 *
087 * @return the month of year
088 */
089 int getMonthOfYear();
090
091 /**
092 * Get the year field value.
093 *
094 * @return the year
095 */
096 int getYear();
097
098 /**
099 * Get the year of era field value.
100 *
101 * @return the year of era
102 */
103 int getYearOfEra();
104
105 /**
106 * Get the year of century field value.
107 *
108 * @return the year of century
109 */
110 int getYearOfCentury();
111
112 /**
113 * Get the year of era field value.
114 *
115 * @return the year of era
116 */
117 int getCenturyOfEra();
118
119 /**
120 * Get the era field value.
121 *
122 * @return the era
123 */
124 int getEra();
125
126 // Time field access methods
127 //-----------------------------------------------------------
128
129 /**
130 * Get the millis of second field value.
131 *
132 * @return the millis of second
133 */
134 int getMillisOfSecond();
135
136 /**
137 * Get the millis of day field value.
138 *
139 * @return the millis of day
140 */
141 int getMillisOfDay();
142
143 /**
144 * Get the second of minute field value.
145 *
146 * @return the second of minute
147 */
148 int getSecondOfMinute();
149
150 /**
151 * Get the second of day field value.
152 *
153 * @return the second of day
154 */
155 int getSecondOfDay();
156
157 /**
158 * Get the minute of hour field value.
159 *
160 * @return the minute of hour
161 */
162 int getMinuteOfHour();
163
164 /**
165 * Get the minute of day field value.
166 *
167 * @return the minute of day
168 */
169 int getMinuteOfDay();
170
171 /**
172 * Get the hour of day field value.
173 *
174 * @return the hour of day
175 */
176 int getHourOfDay();
177
178 /**
179 * Get this object as a DateTime.
180 * <p>
181 * If the implementation of the interface is a DateTime, it is returned directly.
182 *
183 * @return a DateTime using the same millis
184 */
185 DateTime toDateTime();
186
187 /**
188 * Get this object as a MutableDateTime, always returning a new instance.
189 *
190 * @return a MutableDateTime using the same millis
191 */
192 MutableDateTime toMutableDateTime();
193
194 /**
195 * Output the instant using the specified format pattern.
196 *
197 * @param pattern pattern specification
198 * @throws IllegalArgumentException if pattern is invalid
199 * @see org.joda.time.format.DateTimeFormat
200 */
201 String toString(String pattern) throws IllegalArgumentException;
202
203 /**
204 * Output the instant using the specified format pattern.
205 *
206 * @param pattern pattern specification
207 * @param locale Locale to use, or null for default
208 * @throws IllegalArgumentException if pattern is invalid
209 * @see org.joda.time.format.DateTimeFormat
210 */
211 String toString(String pattern, Locale locale) throws IllegalArgumentException;
212
213 }