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 }