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.field;
017:
018: import org.joda.time.DateTimeFieldType;
019: import org.joda.time.DurationField;
020:
021: /**
022: * Precise datetime field, composed of two precise duration fields.
023: * <p>
024: * This DateTimeField is useful for defining DateTimeFields that are composed
025: * of precise durations, like time of day fields. If either duration field is
026: * imprecise, then an {@link ImpreciseDateTimeField} may be used instead.
027: * <p>
028: * PreciseDateTimeField is thread-safe and immutable.
029: *
030: * @author Brian S O'Neill
031: * @author Stephen Colebourne
032: * @since 1.0
033: * @see ImpreciseDateTimeField
034: */
035: public class PreciseDateTimeField extends PreciseDurationDateTimeField {
036:
037: private static final long serialVersionUID = -5586801265774496376L;
038:
039: /** The maximum range in the correct units */
040: private final int iRange;
041:
042: private final DurationField iRangeField;
043:
044: /**
045: * Constructor.
046: *
047: * @param type the field type this field uses
048: * @param unit precise unit duration, like "seconds()".
049: * @param range precise range duration, preferably a multiple of the unit,
050: * like "minutes()".
051: * @throws IllegalArgumentException if either duration field is imprecise
052: * @throws IllegalArgumentException if unit milliseconds is less than one
053: * or effective value range is less than two.
054: */
055: public PreciseDateTimeField(DateTimeFieldType type,
056: DurationField unit, DurationField range) {
057: super (type, unit);
058:
059: if (!range.isPrecise()) {
060: throw new IllegalArgumentException(
061: "Range duration field must be precise");
062: }
063:
064: long rangeMillis = range.getUnitMillis();
065: iRange = (int) (rangeMillis / getUnitMillis());
066: if (iRange < 2) {
067: throw new IllegalArgumentException(
068: "The effective range must be at least 2");
069: }
070:
071: iRangeField = range;
072: }
073:
074: /**
075: * Get the amount of fractional units from the specified time instant.
076: *
077: * @param instant the milliseconds from 1970-01-01T00:00:00Z to query
078: * @return the amount of fractional units extracted from the input.
079: */
080: public int get(long instant) {
081: if (instant >= 0) {
082: return (int) ((instant / getUnitMillis()) % iRange);
083: } else {
084: return iRange
085: - 1
086: + (int) (((instant + 1) / getUnitMillis()) % iRange);
087: }
088: }
089:
090: /**
091: * Add to the component of the specified time instant, wrapping around
092: * within that component if necessary.
093: *
094: * @param instant the milliseconds from 1970-01-01T00:00:00Z to add to
095: * @param amount the amount of units to add (can be negative).
096: * @return the updated time instant.
097: */
098: public long addWrapField(long instant, int amount) {
099: int this Value = get(instant);
100: int wrappedValue = FieldUtils.getWrappedValue(this Value,
101: amount, getMinimumValue(), getMaximumValue());
102: // copy code from set() to avoid repeat call to get()
103: return instant + (wrappedValue - this Value) * getUnitMillis();
104: }
105:
106: /**
107: * Set the specified amount of units to the specified time instant.
108: *
109: * @param instant the milliseconds from 1970-01-01T00:00:00Z to set in
110: * @param value value of units to set.
111: * @return the updated time instant.
112: * @throws IllegalArgumentException if value is too large or too small.
113: */
114: public long set(long instant, int value) {
115: FieldUtils.verifyValueBounds(this , value, getMinimumValue(),
116: getMaximumValue());
117: return instant + (value - get(instant)) * iUnitMillis;
118: }
119:
120: /**
121: * Returns the range duration of this field. For example, if this field
122: * represents "minute of hour", then the range duration field is an hours.
123: *
124: * @return the range duration of this field, or null if field has no range
125: */
126: public DurationField getRangeDurationField() {
127: return iRangeField;
128: }
129:
130: /**
131: * Get the maximum value for the field.
132: *
133: * @return the maximum value
134: */
135: public int getMaximumValue() {
136: return iRange - 1;
137: }
138:
139: /**
140: * Returns the range of the field in the field's units.
141: * <p>
142: * For example, 60 for seconds per minute. The field is allowed values
143: * from 0 to range - 1.
144: *
145: * @return unit range
146: */
147: public int getRange() {
148: return iRange;
149: }
150:
151: }
|