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     */
016    package org.joda.time.field;
017    
018    import java.io.Serializable;
019    
020    import org.joda.time.DurationField;
021    import 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     */
038    public 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    }