ReadablePartial


1   /*
2    *  Copyright 2001-2005 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</code> supports a subset of those fields on the chronology.
23   * It cannot be compared to a <code>ReadableInstant</code>, 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</code> can be converted to a <code>ReadableInstant</code>
28   * using the <code>toDateTime</code> 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   *
31   * @author Stephen Colebourne
32   * @since 1.0
33   */
34  public interface ReadablePartial {
35  
36      /**
37       * Gets the number of fields that this partial supports.
38       *
39       * @return the number of fields supported
40       */
41      int size();
42  
43      /**
44       * Gets the field type at the specified index.
45       *
46       * @param index  the index to retrieve
47       * @return the field at the specified index
48       * @throws IndexOutOfBoundsException if the index is invalid
49       */
50      DateTimeFieldType getFieldType(int index);
51  
52      /**
53       * Gets the field at the specified index.
54       *
55       * @param index  the index to retrieve
56       * @return the field at the specified index
57       * @throws IndexOutOfBoundsException if the index is invalid
58       */
59      DateTimeField getField(int index);
60  
61      /**
62       * Gets the value at the specified index.
63       *
64       * @param index  the index to retrieve
65       * @return the value of the field at the specified index
66       * @throws IndexOutOfBoundsException if the index is invalid
67       */
68      int getValue(int index);
69  
70      /**
71       * Gets the chronology of the partial which is never null.
72       * <p>
73       * The {@link Chronology} is the calculation engine behind the partial and
74       * provides conversion and validation of the fields in a particular calendar system.
75       * 
76       * @return the chronology, never null
77       */
78      Chronology getChronology();
79  
80      /**
81       * Gets the value of one of the fields.
82       * <p>
83       * The field type specified must be one of those that is supported by the partial.
84       *
85       * @param field  a DateTimeFieldType instance that is supported by this partial
86       * @return the value of that field
87       * @throws IllegalArgumentException if the field is null or not supported
88       */
89      int get(DateTimeFieldType field);
90  
91      /**
92       * Checks whether the field type specified is supported by this partial.
93       *
94       * @param field  the field to check, may be null which returns false
95       * @return true if the field is supported
96       */
97      boolean isSupported(DateTimeFieldType field);
98  
99      /**
100      * Converts this partial to a full datetime by resolving it against another
101      * datetime.
102      * <p>
103      * This method takes the specified datetime and sets the fields from this
104      * instant on top. The chronology from the base instant is used.
105      * <p>
106      * For example, if this partial represents a time, then the result of this
107      * method will be the datetime from the specified base instant plus the
108      * time from this partial.
109      *
110      * @param baseInstant  the instant that provides the missing fields, null means now
111      * @return the combined datetime
112      */
113     DateTime toDateTime(ReadableInstant baseInstant);
114 
115     //-----------------------------------------------------------------------
116     /**
117      * Compares this partial with the specified object for equality based
118      * on the supported fields, chronology and values.
119      * <p>
120      * Two instances of ReadablePartial are equal if they have the same
121      * chronology, same field types (in same order) and same values.
122      *
123      * @param partial  the object to compare to
124      * @return true if equal
125      */
126     boolean equals(Object   partial);
127 
128     /**
129      * Gets a hash code for the partial that is compatible with the 
130      * equals method.
131      * <p>
132      * The formula used must be:
133      * <pre>
134      *  int total = 157;
135      *  for (int i = 0; i < fields.length; i++) {
136      *      total = 23 * total + values[i];
137      *      total = 23 * total + fieldTypes[i].hashCode();
138      *  }
139      *  total += chronology.hashCode();
140      *  return total;
141      * </pre>
142      *
143      * @return a suitable hash code
144      */
145     int hashCode();
146 
147 // NOTE: This method should have existed in Joda-Time v1.0.
148 // We STRONGLY recommend that all implementations of ReadablePartial
149 // implement this method, as per AbstractPartial.
150 // The simplest way to do this is to extend AbstractPartial.
151 // v2.0 of Joda-Time will include this method in this interface.
152 //    //-----------------------------------------------------------------------
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 YearHour 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 parial instance has different
164 //     * fields then a 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
172 //     */
173 //    int compareTo(Object 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 }
188
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags