KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > joda > time > base > AbstractPartial


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.base;
17
18 import org.joda.time.Chronology;
19 import org.joda.time.DateTime;
20 import org.joda.time.DateTimeField;
21 import org.joda.time.DateTimeFieldType;
22 import org.joda.time.DateTimeUtils;
23 import org.joda.time.DurationFieldType;
24 import org.joda.time.ReadableInstant;
25 import org.joda.time.ReadablePartial;
26 import org.joda.time.field.FieldUtils;
27 import org.joda.time.format.DateTimeFormatter;
28
29 /**
30  * AbstractPartial provides a standard base implementation of most methods
31  * in the ReadablePartial interface.
32  * <p>
33  * Calculations on are performed using a {@link Chronology}.
34  * This chronology is set to be in the UTC time zone for all calculations.
35  * <p>
36  * The methods on this class use {@link ReadablePartial#size()},
37  * {@link AbstractPartial#getField(int, Chronology)} and
38  * {@link ReadablePartial#getValue(int)} to calculate their results.
39  * Subclasses may have a better implementation.
40  * <p>
41  * AbstractPartial allows subclasses may be mutable and not thread-safe.
42  *
43  * @author Stephen Colebourne
44  * @since 1.0
45  */

46 public abstract class AbstractPartial
47         implements ReadablePartial, Comparable JavaDoc {
48
49     //-----------------------------------------------------------------------
50
/**
51      * Constructor.
52      */

53     protected AbstractPartial() {
54         super();
55     }
56
57     //-----------------------------------------------------------------------
58
/**
59      * Gets the field for a specific index in the chronology specified.
60      * <p>
61      * This method must not use any instance variables.
62      *
63      * @param index the index to retrieve
64      * @param chrono the chronology to use
65      * @return the field
66      * @throws IndexOutOfBoundsException if the index is invalid
67      */

68     protected abstract DateTimeField getField(int index, Chronology chrono);
69
70     //-----------------------------------------------------------------------
71
/**
72      * Gets the field type at the specifed index.
73      *
74      * @param index the index
75      * @return the field type
76      * @throws IndexOutOfBoundsException if the index is invalid
77      */

78     public DateTimeFieldType getFieldType(int index) {
79         return getField(index, getChronology()).getType();
80     }
81
82     /**
83      * Gets an array of the field types that this partial supports.
84      * <p>
85      * The fields are returned largest to smallest, for example Hour, Minute, Second.
86      *
87      * @return the fields supported in an array that may be altered, largest to smallest
88      */

89     public DateTimeFieldType[] getFieldTypes() {
90         DateTimeFieldType[] result = new DateTimeFieldType[size()];
91         for (int i = 0; i < result.length; i++) {
92             result[i] = getFieldType(i);
93         }
94         return result;
95     }
96
97     /**
98      * Gets the field at the specifed index.
99      *
100      * @param index the index
101      * @return the field
102      * @throws IndexOutOfBoundsException if the index is invalid
103      */

104     public DateTimeField getField(int index) {
105         return getField(index, getChronology());
106     }
107
108     /**
109      * Gets an array of the fields that this partial supports.
110      * <p>
111      * The fields are returned largest to smallest, for example Hour, Minute, Second.
112      *
113      * @return the fields supported in an array that may be altered, largest to smallest
114      */

115     public DateTimeField[] getFields() {
116         DateTimeField[] result = new DateTimeField[size()];
117         for (int i = 0; i < result.length; i++) {
118             result[i] = getField(i);
119         }
120         return result;
121     }
122
123     /**
124      * Gets an array of the value of each of the fields that this partial supports.
125      * <p>
126      * The fields are returned largest to smallest, for example Hour, Minute, Second.
127      * Each value corresponds to the same array index as <code>getFields()</code>
128      *
129      * @return the current values of each field in an array that may be altered, largest to smallest
130      */

131     public int[] getValues() {
132         int[] result = new int[size()];
133         for (int i = 0; i < result.length; i++) {
134             result[i] = getValue(i);
135         }
136         return result;
137     }
138
139     //-----------------------------------------------------------------------
140
/**
141      * Get the value of one of the fields of a datetime.
142      * <p>
143      * The field specified must be one of those that is supported by the partial.
144      *
145      * @param type a DateTimeFieldType instance that is supported by this partial
146      * @return the value of that field
147      * @throws IllegalArgumentException if the field is null or not supported
148      */

149     public int get(DateTimeFieldType type) {
150         return getValue(indexOfSupported(type));
151     }
152
153     /**
154      * Checks whether the field specified is supported by this partial.
155      *
156      * @param type the type to check, may be null which returns false
157      * @return true if the field is supported
158      */

159     public boolean isSupported(DateTimeFieldType type) {
160         return (indexOf(type) != -1);
161     }
162
163     /**
164      * Gets the index of the specified field, or -1 if the field is unsupported.
165      *
166      * @param type the type to check, may be null which returns -1
167      * @return the index of the field, -1 if unsupported
168      */

169     public int indexOf(DateTimeFieldType type) {
170         for (int i = 0, isize = size(); i < isize; i++) {
171             if (getFieldType(i) == type) {
172                 return i;
173             }
174         }
175         return -1;
176     }
177
178     /**
179      * Gets the index of the specified field, throwing an exception if the
180      * field is unsupported.
181      *
182      * @param type the type to check, not null
183      * @return the index of the field
184      * @throws IllegalArgumentException if the field is null or not supported
185      */

186     protected int indexOfSupported(DateTimeFieldType type) {
187         int index = indexOf(type);
188         if (index == -1) {
189             throw new IllegalArgumentException JavaDoc("Field '" + type + "' is not supported");
190         }
191         return index;
192     }
193
194     /**
195      * Gets the index of the first fields to have the specified duration,
196      * or -1 if the field is unsupported.
197      *
198      * @param type the type to check, may be null which returns -1
199      * @return the index of the field, -1 if unsupported
200      */

201     protected int indexOf(DurationFieldType type) {
202         for (int i = 0, isize = size(); i < isize; i++) {
203             if (getFieldType(i).getDurationType() == type) {
204                 return i;
205             }
206         }
207         return -1;
208     }
209
210     /**
211      * Gets the index of the first fields to have the specified duration,
212      * throwing an exception if the field is unsupported.
213      *
214      * @param type the type to check, not null
215      * @return the index of the field
216      * @throws IllegalArgumentException if the field is null or not supported
217      */

218     protected int indexOfSupported(DurationFieldType type) {
219         int index = indexOf(type);
220         if (index == -1) {
221             throw new IllegalArgumentException JavaDoc("Field '" + type + "' is not supported");
222         }
223         return index;
224     }
225
226     //-----------------------------------------------------------------------
227
/**
228      * Resolves this partial against another complete instant to create a new
229      * full instant. The combination is performed using the chronology of the
230      * specified instant.
231      * <p>
232      * For example, if this partial represents a time, then the result of this
233      * method will be the datetime from the specified base instant plus the
234      * time from this partial.
235      *
236      * @param baseInstant the instant that provides the missing fields, null means now
237      * @return the combined datetime
238      */

239     public DateTime toDateTime(ReadableInstant baseInstant) {
240         Chronology chrono = DateTimeUtils.getInstantChronology(baseInstant);
241         long instantMillis = DateTimeUtils.getInstantMillis(baseInstant);
242         long resolved = chrono.set(this, instantMillis);
243         return new DateTime(resolved, chrono);
244     }
245
246     //-----------------------------------------------------------------------
247
/**
248      * Compares this ReadablePartial with another returning true if the chronology,
249      * field types and values are equal.
250      *
251      * @param partial an object to check against
252      * @return true if fields and values are equal
253      */

254     public boolean equals(Object JavaDoc partial) {
255         if (this == partial) {
256             return true;
257         }
258         if (partial instanceof ReadablePartial == false) {
259             return false;
260         }
261         ReadablePartial other = (ReadablePartial) partial;
262         if (size() != other.size()) {
263             return false;
264         }
265         for (int i = 0, isize = size(); i < isize; i++) {
266             if (getValue(i) != other.getValue(i) || getFieldType(i) != other.getFieldType(i)) {
267                 return false;
268             }
269         }
270         return FieldUtils.equals(getChronology(), other.getChronology());
271     }
272
273     /**
274      * Gets a hash code for the ReadablePartial that is compatible with the
275      * equals method.
276      *
277      * @return a suitable hash code
278      */

279     public int hashCode() {
280         int total = 157;
281         for (int i = 0, isize = size(); i < isize; i++) {
282             total = 23 * total + getValue(i);
283             total = 23 * total + getFieldType(i).hashCode();
284         }
285         total += getChronology().hashCode();
286         return total;
287     }
288
289     //-----------------------------------------------------------------------
290
/**
291      * Compares this partial with another returning an integer
292      * indicating the order.
293      * <p>
294      * The fields are compared in order, from largest to smallest.
295      * The first field that is non-equal is used to determine the result.
296      * <p>
297      * The specified object must be a partial instance whose field types
298      * match those of this partial.
299      * <p>
300      * NOTE: This implementation violates the Comparable contract.
301      * This method will accept any instance of ReadablePartial as input.
302      * However, it is possible that some implementations of ReadablePartial
303      * exist that do not extend AbstractPartial, and thus will throw a
304      * ClassCastException if compared in the opposite direction.
305      * The cause of this problem is that ReadablePartial doesn't define
306      * the compareTo() method, however we can't change that until v2.0.
307      *
308      * @param partial an object to check against
309      * @return negative if this is less, zero if equal, positive if greater
310      * @throws ClassCastException if the partial is the wrong class
311      * or if it has field types that don't match
312      * @throws NullPointerException if the partial is null
313      * @since 1.1
314      */

315     public int compareTo(Object JavaDoc partial) {
316         if (this == partial) {
317             return 0;
318         }
319         ReadablePartial other = (ReadablePartial) partial;
320         if (size() != other.size()) {
321             throw new ClassCastException JavaDoc("ReadablePartial objects must have matching field types");
322         }
323         for (int i = 0, isize = size(); i < isize; i++) {
324             if (getFieldType(i) != other.getFieldType(i)) {
325                 throw new ClassCastException JavaDoc("ReadablePartial objects must have matching field types");
326             }
327         }
328         // fields are ordered largest first
329
for (int i = 0, isize = size(); i < isize; i++) {
330             if (getValue(i) > other.getValue(i)) {
331                 return 1;
332             }
333             if (getValue(i) < other.getValue(i)) {
334                 return -1;
335             }
336         }
337         return 0;
338     }
339
340     /**
341      * Is this partial later than the specified partial.
342      * <p>
343      * The fields are compared in order, from largest to smallest.
344      * The first field that is non-equal is used to determine the result.
345      * <p>
346      * You may not pass null into this method. This is because you need
347      * a time zone to accurately determine the current date.
348      *
349      * @param partial a partial to check against, must not be null
350      * @return true if this date is after the date passed in
351      * @throws IllegalArgumentException if the specified partial is null
352      * @throws ClassCastException if the partial has field types that don't match
353      * @since 1.1
354      */

355     public boolean isAfter(ReadablePartial partial) {
356         if (partial == null) {
357             throw new IllegalArgumentException JavaDoc("Partial cannot be null");
358         }
359         return compareTo(partial) > 0;
360     }
361
362     /**
363      * Is this partial earlier than the specified partial.
364      * <p>
365      * The fields are compared in order, from largest to smallest.
366      * The first field that is non-equal is used to determine the result.
367      * <p>
368      * You may not pass null into this method. This is because you need
369      * a time zone to accurately determine the current date.
370      *
371      * @param partial a partial to check against, must not be null
372      * @return true if this date is before the date passed in
373      * @throws IllegalArgumentException if the specified partial is null
374      * @throws ClassCastException if the partial has field types that don't match
375      * @since 1.1
376      */

377     public boolean isBefore(ReadablePartial partial) {
378         if (partial == null) {
379             throw new IllegalArgumentException JavaDoc("Partial cannot be null");
380         }
381         return compareTo(partial) < 0;
382     }
383
384     /**
385      * Is this partial the same as the specified partial.
386      * <p>
387      * The fields are compared in order, from largest to smallest.
388      * If all fields are equal, the result is true.
389      * <p>
390      * You may not pass null into this method. This is because you need
391      * a time zone to accurately determine the current date.
392      *
393      * @param partial a partial to check against, must not be null
394      * @return true if this date is the same as the date passed in
395      * @throws IllegalArgumentException if the specified partial is null
396      * @throws ClassCastException if the partial has field types that don't match
397      * @since 1.1
398      */

399     public boolean isEqual(ReadablePartial partial) {
400         if (partial == null) {
401             throw new IllegalArgumentException JavaDoc("Partial cannot be null");
402         }
403         return compareTo(partial) == 0;
404     }
405
406     //-----------------------------------------------------------------------
407
/**
408      * Uses the specified formatter to convert this partial to a String.
409      *
410      * @param formatter the formatter to use, null means use <code>toString()</code>.
411      * @return the formatted string
412      * @since 1.1
413      */

414     public String JavaDoc toString(DateTimeFormatter formatter) {
415         if (formatter == null) {
416             return toString();
417         }
418         return formatter.print(this);
419     }
420
421 }
422
Popular Tags