001/*
002 *  Copyright 2001-2009 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 */
016package org.joda.time.field;
017
018import java.io.Serializable;
019
020import org.joda.time.DurationField;
021import org.joda.time.DurationFieldType;
022
023/**
024 * BaseDurationField provides the common behaviour for DurationField
025 * implementations.
026 * <p>
027 * This class should generally not be used directly by API users. The
028 * DurationField class should be used when different kinds of DurationField
029 * objects are to be referenced.
030 * <p>
031 * BaseDurationField is thread-safe and immutable, and its subclasses must
032 * be as well.
033 *
034 * @author Brian S O'Neill
035 * @see DecoratedDurationField
036 * @since 1.0
037 */
038public abstract class BaseDurationField extends DurationField implements Serializable {
039
040    /** Serialization lock. */
041    private static final long serialVersionUID = -2554245107589433218L;
042
043    /** A desriptive name for the field. */
044    private final DurationFieldType iType;
045
046    protected BaseDurationField(DurationFieldType type) {
047        super();
048        if (type == null) {
049            throw new IllegalArgumentException("The type must not be null");
050        }
051        iType = type;
052    }
053
054    public final DurationFieldType getType() {
055        return iType;
056    }
057
058    public final String getName() {
059        return iType.getName();
060    }
061
062    /**
063     * @return true always
064     */
065    public final boolean isSupported() {
066        return true;
067    }
068
069    //------------------------------------------------------------------------
070    /**
071     * Get the value of this field from the milliseconds, which is approximate
072     * if this field is imprecise.
073     *
074     * @param duration  the milliseconds to query, which may be negative
075     * @return the value of the field, in the units of the field, which may be
076     * negative
077     */
078    public int getValue(long duration) {
079        return FieldUtils.safeToInt(getValueAsLong(duration));
080    }
081
082    /**
083     * Get the value of this field from the milliseconds, which is approximate
084     * if this field is imprecise.
085     *
086     * @param duration  the milliseconds to query, which may be negative
087     * @return the value of the field, in the units of the field, which may be
088     * negative
089     */
090    public long getValueAsLong(long duration) {
091        return duration / getUnitMillis();
092    }
093
094    /**
095     * Get the value of this field from the milliseconds relative to an
096     * instant.
097     *
098     * <p>If the milliseconds is positive, then the instant is treated as a
099     * "start instant". If negative, the instant is treated as an "end
100     * instant".
101     *
102     * <p>The default implementation returns
103     * <code>Utils.safeToInt(getAsLong(millisDuration, instant))</code>.
104     * 
105     * @param duration  the milliseconds to query, which may be negative
106     * @param instant  the start instant to calculate relative to
107     * @return the value of the field, in the units of the field, which may be
108     * negative
109     */
110    public int getValue(long duration, long instant) {
111        return FieldUtils.safeToInt(getValueAsLong(duration, instant));
112    }
113
114    /**
115     * Get the millisecond duration of this field from its value, which is
116     * approximate if this field is imprecise.
117     * 
118     * @param value  the value of the field, which may be negative
119     * @return the milliseconds that the field represents, which may be
120     * negative
121     */
122    public long getMillis(int value) {
123        return value * getUnitMillis();  // safe
124    }
125
126    /**
127     * Get the millisecond duration of this field from its value, which is
128     * approximate if this field is imprecise.
129     * 
130     * @param value  the value of the field, which may be negative
131     * @return the milliseconds that the field represents, which may be
132     * negative
133     */
134    public long getMillis(long value) {
135        return FieldUtils.safeMultiply(value, getUnitMillis());
136    }
137
138    // Calculation API
139    //------------------------------------------------------------------------
140    public int getDifference(long minuendInstant, long subtrahendInstant) {
141        return FieldUtils.safeToInt(getDifferenceAsLong(minuendInstant, subtrahendInstant));
142    }
143
144    //------------------------------------------------------------------------
145    public int compareTo(DurationField otherField) {
146        long otherMillis = otherField.getUnitMillis();
147        long thisMillis = getUnitMillis();
148        // cannot do (thisMillis - otherMillis) as can overflow
149        if (thisMillis == otherMillis) {
150            return 0;
151        }
152        if (thisMillis < otherMillis) {
153            return -1;
154        } else {
155            return 1;
156        }
157    }
158
159    /**
160     * Get a suitable debug string.
161     * 
162     * @return debug string
163     */
164    public String toString() {
165        return "DurationField[" + getName() + ']';
166    }
167
168}