View Javadoc

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("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("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 }