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     */
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         * 
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    }