KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > joda > time > field > PreciseDateTimeField


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.field;
17
18 import org.joda.time.DateTimeFieldType;
19 import org.joda.time.DurationField;
20
21 /**
22  * Precise datetime field, composed of two precise duration fields.
23  * <p>
24  * This DateTimeField is useful for defining DateTimeFields that are composed
25  * of precise durations, like time of day fields. If either duration field is
26  * imprecise, then an {@link ImpreciseDateTimeField} may be used instead.
27  * <p>
28  * PreciseDateTimeField is thread-safe and immutable.
29  *
30  * @author Brian S O'Neill
31  * @author Stephen Colebourne
32  * @since 1.0
33  * @see ImpreciseDateTimeField
34  */
35 public class PreciseDateTimeField extends PreciseDurationDateTimeField {
36
37     private static final long serialVersionUID = -5586801265774496376L;
38
39     /** The maximum range in the correct units */
40     private final int iRange;
41
42     private final DurationField iRangeField;
43
44     /**
45      * Constructor.
46      *
47      * @param type the field type this field uses
48      * @param unit precise unit duration, like "seconds()".
49      * @param range precise range duration, preferably a multiple of the unit,
50      * like "minutes()".
51      * @throws IllegalArgumentException if either duration field is imprecise
52      * @throws IllegalArgumentException if unit milliseconds is less than one
53      * or effective value range is less than two.
54      */
55     public PreciseDateTimeField(DateTimeFieldType type,
56                                 DurationField unit, DurationField range) {
57         super(type, unit);
58
59         if (!range.isPrecise()) {
60             throw new IllegalArgumentException JavaDoc("Range duration field must be precise");
61         }
62
63         long rangeMillis = range.getUnitMillis();
64         iRange = (int)(rangeMillis / getUnitMillis());
65         if (iRange < 2) {
66             throw new IllegalArgumentException JavaDoc("The effective range must be at least 2");
67         }
68
69         iRangeField = range;
70     }
71
72     /**
73      * Get the amount of fractional units from the specified time instant.
74      *
75      * @param instant the milliseconds from 1970-01-01T00:00:00Z to query
76      * @return the amount of fractional units extracted from the input.
77      */
78     public int get(long instant) {
79         if (instant >= 0) {
80             return (int) ((instant / getUnitMillis()) % iRange);
81         } else {
82             return iRange - 1 + (int) (((instant + 1) / getUnitMillis()) % iRange);
83         }
84     }
85
86     /**
87      * Add to the component of the specified time instant, wrapping around
88      * within that component if necessary.
89      *
90      * @param instant the milliseconds from 1970-01-01T00:00:00Z to add to
91      * @param amount the amount of units to add (can be negative).
92      * @return the updated time instant.
93      */
94     public long addWrapField(long instant, int amount) {
95         int thisValue = get(instant);
96         int wrappedValue = FieldUtils.getWrappedValue
97             (thisValue, amount, getMinimumValue(), getMaximumValue());
98         // copy code from set() to avoid repeat call to get()
99 return instant + (wrappedValue - thisValue) * getUnitMillis();
100     }
101
102     /**
103      * Set the specified amount of units to the specified time instant.
104      *
105      * @param instant the milliseconds from 1970-01-01T00:00:00Z to set in
106      * @param value value of units to set.
107      * @return the updated time instant.
108      * @throws IllegalArgumentException if value is too large or too small.
109      */
110     public long set(long instant, int value) {
111         FieldUtils.verifyValueBounds(this, value, getMinimumValue(), getMaximumValue());
112         return instant + (value - get(instant)) * iUnitMillis;
113     }
114
115     /**
116      * Returns the range duration of this field. For example, if this field
117      * represents "minute of hour", then the range duration field is an hours.
118      *
119      * @return the range duration of this field, or null if field has no range
120      */
121     public DurationField getRangeDurationField() {
122         return iRangeField;
123     }
124
125     /**
126      * Get the maximum value for the field.
127      *
128      * @return the maximum value
129      */
130     public int getMaximumValue() {
131         return iRange - 1;
132     }
133     
134     /**
135      * Returns the range of the field in the field's units.
136      * <p>
137      * For example, 60 for seconds per minute. The field is allowed values
138      * from 0 to range - 1.
139      *
140      * @return unit range
141      */
142     public int getRange() {
143         return iRange;
144     }
145
146 }
147
Popular Tags