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: /**
019: * Defines a partial time that does not support every datetime field, and is
020: * thus a local time.
021: * <p>
022: * A <code>ReadablePartial</code> supports a subset of those fields on the chronology.
023: * It cannot be compared to a <code>ReadableInstant</code>, as it does not fully
024: * specify an instant in time. The time it does specify is a local time, and does
025: * not include a time zone.
026: * <p>
027: * A <code>ReadablePartial</code> can be converted to a <code>ReadableInstant</code>
028: * using the <code>toDateTime</code> method. This works by providing a full base
029: * instant that can be used to 'fill in the gaps' and specify a time zone.
030: *
031: * @author Stephen Colebourne
032: * @since 1.0
033: */
034: public interface ReadablePartial {
035:
036: /**
037: * Gets the number of fields that this partial supports.
038: *
039: * @return the number of fields supported
040: */
041: int size();
042:
043: /**
044: * Gets the field type at the specified index.
045: *
046: * @param index the index to retrieve
047: * @return the field at the specified index
048: * @throws IndexOutOfBoundsException if the index is invalid
049: */
050: DateTimeFieldType getFieldType(int index);
051:
052: /**
053: * Gets the field at the specified index.
054: *
055: * @param index the index to retrieve
056: * @return the field at the specified index
057: * @throws IndexOutOfBoundsException if the index is invalid
058: */
059: DateTimeField getField(int index);
060:
061: /**
062: * Gets the value at the specified index.
063: *
064: * @param index the index to retrieve
065: * @return the value of the field at the specified index
066: * @throws IndexOutOfBoundsException if the index is invalid
067: */
068: int getValue(int index);
069:
070: /**
071: * Gets the chronology of the partial which is never null.
072: * <p>
073: * The {@link Chronology} is the calculation engine behind the partial and
074: * provides conversion and validation of the fields in a particular calendar system.
075: *
076: * @return the chronology, never null
077: */
078: Chronology getChronology();
079:
080: /**
081: * Gets the value of one of the fields.
082: * <p>
083: * The field type specified must be one of those that is supported by the partial.
084: *
085: * @param field a DateTimeFieldType instance that is supported by this partial
086: * @return the value of that field
087: * @throws IllegalArgumentException if the field is null or not supported
088: */
089: int get(DateTimeFieldType field);
090:
091: /**
092: * Checks whether the field type specified is supported by this partial.
093: *
094: * @param field the field to check, may be null which returns false
095: * @return true if the field is supported
096: */
097: boolean isSupported(DateTimeFieldType field);
098:
099: /**
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: }
|