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 java.io.Serializable;
019    import org.joda.time.DurationField;
020    import 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     */
037    public 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    }