View Javadoc

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  /**
19   * Defines a partial time that does not support every datetime field, and is
20   * thus a local time.
21   * <p>
22   * A {@code ReadablePartial} supports a subset of those fields on the chronology.
23   * It cannot be compared to a {@code ReadableInstant}, as it does not fully
24   * specify an instant in time. The time it does specify is a local time, and does
25   * not include a time zone.
26   * <p>
27   * A {@code ReadablePartial} can be converted to a {@code ReadableInstant}
28   * using the {@code toDateTime} method. This works by providing a full base
29   * instant that can be used to 'fill in the gaps' and specify a time zone.
30   * <p>
31   * {@code ReadablePartial} is {@code Comparable} from v2.0.
32   * The comparison is based on the fields, compared in order, from largest to smallest.
33   * The first field that is non-equal is used to determine the result.
34   *
35   * @author Stephen Colebourne
36   * @since 1.0
37   */
38  public interface ReadablePartial extends Comparable<ReadablePartial> {
39  
40      /**
41       * Gets the number of fields that this partial supports.
42       *
43       * @return the number of fields supported
44       */
45      int size();
46  
47      /**
48       * Gets the field type at the specified index.
49       *
50       * @param index  the index to retrieve
51       * @return the field at the specified index
52       * @throws IndexOutOfBoundsException if the index is invalid
53       */
54      DateTimeFieldType getFieldType(int index);
55  
56      /**
57       * Gets the field at the specified index.
58       *
59       * @param index  the index to retrieve
60       * @return the field at the specified index
61       * @throws IndexOutOfBoundsException if the index is invalid
62       */
63      DateTimeField getField(int index);
64  
65      /**
66       * Gets the value at the specified index.
67       *
68       * @param index  the index to retrieve
69       * @return the value of the field at the specified index
70       * @throws IndexOutOfBoundsException if the index is invalid
71       */
72      int getValue(int index);
73  
74      /**
75       * Gets the chronology of the partial which is never null.
76       * <p>
77       * The {@link Chronology} is the calculation engine behind the partial and
78       * provides conversion and validation of the fields in a particular calendar system.
79       * 
80       * @return the chronology, never null
81       */
82      Chronology getChronology();
83  
84      /**
85       * Gets the value of one of the fields.
86       * <p>
87       * The field type specified must be one of those that is supported by the partial.
88       *
89       * @param field  a DateTimeFieldType instance that is supported by this partial
90       * @return the value of that field
91       * @throws IllegalArgumentException if the field is null or not supported
92       */
93      int get(DateTimeFieldType field);
94  
95      /**
96       * Checks whether the field type specified is supported by this partial.
97       *
98       * @param field  the field to check, may be null which returns false
99       * @return true if the field is supported
100      */
101     boolean isSupported(DateTimeFieldType field);
102 
103     /**
104      * Converts this partial to a full datetime by resolving it against another
105      * datetime.
106      * <p>
107      * This method takes the specified datetime and sets the fields from this
108      * instant on top. The chronology from the base instant is used.
109      * <p>
110      * For example, if this partial represents a time, then the result of this
111      * method will be the datetime from the specified base instant plus the
112      * time from this partial.
113      *
114      * @param baseInstant  the instant that provides the missing fields, null means now
115      * @return the combined datetime
116      */
117     DateTime toDateTime(ReadableInstant baseInstant);
118 
119     //-----------------------------------------------------------------------
120     /**
121      * Compares this partial with the specified object for equality based
122      * on the supported fields, chronology and values.
123      * <p>
124      * Two instances of ReadablePartial are equal if they have the same
125      * chronology, same field types (in same order) and same values.
126      *
127      * @param partial  the object to compare to
128      * @return true if equal
129      */
130     boolean equals(Object partial);
131 
132     /**
133      * Gets a hash code for the partial that is compatible with the 
134      * equals method.
135      * <p>
136      * The formula used must be:
137      * <pre>
138      *  int total = 157;
139      *  for (int i = 0; i < fields.length; i++) {
140      *      total = 23 * total + values[i];
141      *      total = 23 * total + fieldTypes[i].hashCode();
142      *  }
143      *  total += chronology.hashCode();
144      *  return total;
145      * </pre>
146      *
147      * @return a suitable hash code
148      */
149     int hashCode();
150 
151     //-----------------------------------------------------------------------
152 //  This is commented out to improve backwards compatibility
153 //    /**
154 //     * Compares this partial with another returning an integer
155 //     * indicating the order.
156 //     * <p>
157 //     * The fields are compared in order, from largest to smallest.
158 //     * The first field that is non-equal is used to determine the result.
159 //     * Thus a year-hour partial will first be compared on the year, and then
160 //     * on the hour.
161 //     * <p>
162 //     * The specified object must be a partial instance whose field types
163 //     * match those of this partial. If the partial instance has different
164 //     * fields then a {@code ClassCastException} is thrown.
165 //     *
166 //     * @param partial  an object to check against
167 //     * @return negative if this is less, zero if equal, positive if greater
168 //     * @throws ClassCastException if the partial is the wrong class
169 //     *  or if it has field types that don't match
170 //     * @throws NullPointerException if the partial is null
171 //     * @since 2.0, previously on {@code AbstractPartial}
172 //     */
173 //    int compareTo(ReadablePartial partial);
174 
175     //-----------------------------------------------------------------------
176     /**
177      * Get the value as a String in a recognisable ISO8601 format, only
178      * displaying supported fields.
179      * <p>
180      * The string output is in ISO8601 format to enable the String
181      * constructor to correctly parse it.
182      *
183      * @return the value as an ISO8601 string
184      */
185     String toString();
186 
187 }