KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > joda > time > 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 JavaDoc 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 JavaDoc toString();
186
187 }
188
Popular Tags