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 }