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