001/*
002 *  Copyright 2001-2005 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 */
016package org.joda.time;
017
018import 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 */
034public 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     * 
062     * @return the week of a week based year
063     */
064    int getWeekOfWeekyear();
065
066    /**
067     * Get the weekyear field value.
068     * 
069     * @return the year of a week based year
070     */
071    int getWeekyear();
072
073    /**
074     * Get the month of year field value.
075     * 
076     * @return the month of year
077     */
078    int getMonthOfYear();
079
080    /**
081     * Get the year field value.
082     * 
083     * @return the year
084     */
085    int getYear();
086
087    /**
088     * Get the year of era field value.
089     * 
090     * @return the year of era
091     */
092    int getYearOfEra();
093
094    /**
095     * Get the year of century field value.
096     * 
097     * @return the year of century
098     */
099    int getYearOfCentury();
100
101    /**
102     * Get the year of era field value.
103     * 
104     * @return the year of era
105     */
106    int getCenturyOfEra();
107
108    /**
109     * Get the era field value.
110     * 
111     * @return the era
112     */
113    int getEra();
114
115    // Time field access methods
116    //-----------------------------------------------------------
117
118    /**
119     * Get the millis of second field value.
120     *
121     * @return the millis of second
122     */
123    int getMillisOfSecond();
124
125    /**
126     * Get the millis of day field value.
127     *
128     * @return the millis of day
129     */
130    int getMillisOfDay();
131
132    /**
133     * Get the second of minute field value.
134     *
135     * @return the second of minute
136     */
137    int getSecondOfMinute();
138
139    /**
140     * Get the second of day field value.
141     *
142     * @return the second of day
143     */
144    int getSecondOfDay();
145
146    /**
147     * Get the minute of hour field value.
148     *
149     * @return the minute of hour
150     */
151    int getMinuteOfHour();
152
153    /**
154     * Get the minute of day field value.
155     *
156     * @return the minute of day
157     */
158    int getMinuteOfDay();
159
160    /**
161     * Get the hour of day field value.
162     *
163     * @return the hour of day
164     */
165    int getHourOfDay();
166
167    /**
168     * Get this object as a DateTime.
169     * <p>
170     * If the implementation of the interface is a DateTime, it is returned directly.
171     * 
172     * @return a DateTime using the same millis
173     */
174    DateTime toDateTime();
175
176    /**
177     * Get this object as a MutableDateTime, always returning a new instance.
178     * 
179     * @return a MutableDateTime using the same millis
180     */
181    MutableDateTime toMutableDateTime();
182
183    /**
184     * Output the instant using the specified format pattern.
185     *
186     * @param pattern  pattern specification
187     * @throws IllegalArgumentException  if pattern is invalid
188     * @see  org.joda.time.format.DateTimeFormat
189     */
190    String toString(String pattern) throws IllegalArgumentException;
191
192    /**
193     * Output the instant using the specified format pattern.
194     *
195     * @param pattern  pattern specification
196     * @param locale  Locale to use, or null for default
197     * @throws IllegalArgumentException  if pattern is invalid
198     * @see  org.joda.time.format.DateTimeFormat
199     */
200    String toString(String pattern, Locale locale) throws IllegalArgumentException;
201    
202}