1 /*
2 * Copyright 2001-2011 Stephen Colebourne
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.joda.time;
17
18 import java.util.Locale;
19
20 /**
21 * Defines an instant in time that can be queried using datetime fields.
22 * <p>
23 * The implementation of this interface may be mutable or immutable.
24 * This interface only gives access to retrieve data, never to change it.
25 * <p>
26 * Methods in your application should be defined using <code>ReadableDateTime</code>
27 * as a parameter if the method only wants to read the datetime, and not perform
28 * any advanced manipulations.
29 *
30 * @author Stephen Colebourne
31 * @author Brian S O'Neill
32 * @since 1.0
33 */
34 public interface ReadableDateTime extends ReadableInstant {
35
36 /**
37 * Get the day of week field value.
38 * <p>
39 * The values for the day of week are defined in {@link DateTimeConstants}.
40 *
41 * @return the day of week
42 */
43 int getDayOfWeek();
44
45 /**
46 * Get the day of month field value.
47 *
48 * @return the day of month
49 */
50 int getDayOfMonth();
51
52 /**
53 * Get the day of year field value.
54 *
55 * @return the day of year
56 */
57 int getDayOfYear();
58
59 /**
60 * Get the week of weekyear field value.
61 * <p>
62 * This field is associated with the "weekyear" via {@link #getWeekyear()}.
63 * In the standard ISO8601 week algorithm, the first week of the year
64 * is that in which at least 4 days are in the year. As a result of this
65 * definition, day 1 of the first week may be in the previous year.
66 *
67 * @return the week of a week based year
68 */
69 int getWeekOfWeekyear();
70
71 /**
72 * Get the weekyear field value.
73 * <p>
74 * The weekyear is the year that matches with the weekOfWeekyear field.
75 * In the standard ISO8601 week algorithm, the first week of the year
76 * is that in which at least 4 days are in the year. As a result of this
77 * definition, day 1 of the first week may be in the previous year.
78 * The weekyear allows you to query the effective year for that day.
79 *
80 * @return the year of a week based year
81 */
82 int getWeekyear();
83
84 /**
85 * Get the month of year field value.
86 *
87 * @return the month of year
88 */
89 int getMonthOfYear();
90
91 /**
92 * Get the year field value.
93 *
94 * @return the year
95 */
96 int getYear();
97
98 /**
99 * 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 }