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;
017:
018: import java.io.Serializable;
019:
020: import org.joda.time.base.BaseDuration;
021: import org.joda.time.field.FieldUtils;
022:
023: /**
024: * An immutable duration specifying a length of time in milliseconds.
025: * <p>
026: * A duration is defined by a fixed number of milliseconds.
027: * There is no concept of fields, such as days or seconds, as these fields can vary in length.
028: * A duration may be converted to a {@link Period} to obtain field values.
029: * This conversion will typically cause a loss of precision however.
030: * <p>
031: * Duration is thread-safe and immutable.
032: *
033: * @author Brian S O'Neill
034: * @author Stephen Colebourne
035: * @since 1.0
036: */
037: public final class Duration extends BaseDuration implements
038: ReadableDuration, Serializable {
039:
040: /** Constant representing zero millisecond duration */
041: public static final Duration ZERO = new Duration(0L);
042:
043: /** Serialization version */
044: private static final long serialVersionUID = 2471658376918L;
045:
046: /**
047: * Creates a duration from the given millisecond duration.
048: *
049: * @param duration the duration, in milliseconds
050: */
051: public Duration(long duration) {
052: super (duration);
053: }
054:
055: /**
056: * Creates a duration from the given interval endpoints.
057: *
058: * @param startInstant interval start, in milliseconds
059: * @param endInstant interval end, in milliseconds
060: * @throws ArithmeticException if the duration exceeds a 64 bit long
061: */
062: public Duration(long startInstant, long endInstant) {
063: super (startInstant, endInstant);
064: }
065:
066: /**
067: * Creates a duration from the given interval endpoints.
068: *
069: * @param start interval start, null means now
070: * @param end interval end, null means now
071: * @throws ArithmeticException if the duration exceeds a 64 bit long
072: */
073: public Duration(ReadableInstant start, ReadableInstant end) {
074: super (start, end);
075: }
076:
077: /**
078: * Creates a duration from the specified object using the
079: * {@link org.joda.time.convert.ConverterManager ConverterManager}.
080: *
081: * @param duration duration to convert
082: * @throws IllegalArgumentException if duration is invalid
083: */
084: public Duration(Object duration) {
085: super (duration);
086: }
087:
088: //-----------------------------------------------------------------------
089: /**
090: * Get this duration as an immutable <code>Duration</code> object
091: * by returning <code>this</code>.
092: *
093: * @return <code>this</code>
094: */
095: public Duration toDuration() {
096: return this ;
097: }
098:
099: //-----------------------------------------------------------------------
100: /**
101: * Creates a new Duration instance with a different milisecond length.
102: *
103: * @param duration the new length of the duration
104: * @return the new duration instance
105: */
106: public Duration withMillis(long duration) {
107: if (duration == getMillis()) {
108: return this ;
109: }
110: return new Duration(duration);
111: }
112:
113: /**
114: * Returns a new duration with this length plus that specified multiplied by the scalar.
115: * This instance is immutable and is not altered.
116: * <p>
117: * If the addition is zero, this instance is returned.
118: *
119: * @param durationToAdd the duration to add to this one
120: * @param scalar the amount of times to add, such as -1 to subtract once
121: * @return the new duration instance
122: */
123: public Duration withDurationAdded(long durationToAdd, int scalar) {
124: if (durationToAdd == 0 || scalar == 0) {
125: return this ;
126: }
127: long add = FieldUtils.safeMultiply(durationToAdd, scalar);
128: long duration = FieldUtils.safeAdd(getMillis(), add);
129: return new Duration(duration);
130: }
131:
132: /**
133: * Returns a new duration with this length plus that specified multiplied by the scalar.
134: * This instance is immutable and is not altered.
135: * <p>
136: * If the addition is zero, this instance is returned.
137: *
138: * @param durationToAdd the duration to add to this one, null means zero
139: * @param scalar the amount of times to add, such as -1 to subtract once
140: * @return the new duration instance
141: */
142: public Duration withDurationAdded(ReadableDuration durationToAdd,
143: int scalar) {
144: if (durationToAdd == null || scalar == 0) {
145: return this ;
146: }
147: return withDurationAdded(durationToAdd.getMillis(), scalar);
148: }
149:
150: //-----------------------------------------------------------------------
151: /**
152: * Returns a new duration with this length plus that specified.
153: * This instance is immutable and is not altered.
154: * <p>
155: * If the addition is zero, this instance is returned.
156: *
157: * @param amount the duration to add to this one
158: * @return the new duration instance
159: */
160: public Duration plus(long amount) {
161: return withDurationAdded(amount, 1);
162: }
163:
164: /**
165: * Returns a new duration with this length plus that specified.
166: * This instance is immutable and is not altered.
167: * <p>
168: * If the amount is zero, this instance is returned.
169: *
170: * @param amount the duration to add to this one, null means zero
171: * @return the new duration instance
172: */
173: public Duration plus(ReadableDuration amount) {
174: if (amount == null) {
175: return this ;
176: }
177: return withDurationAdded(amount.getMillis(), 1);
178: }
179:
180: /**
181: * Returns a new duration with this length minus that specified.
182: * This instance is immutable and is not altered.
183: * <p>
184: * If the addition is zero, this instance is returned.
185: *
186: * @param amount the duration to take away from this one
187: * @return the new duration instance
188: */
189: public Duration minus(long amount) {
190: return withDurationAdded(amount, -1);
191: }
192:
193: /**
194: * Returns a new duration with this length minus that specified.
195: * This instance is immutable and is not altered.
196: * <p>
197: * If the amount is zero, this instance is returned.
198: *
199: * @param amount the duration to take away from this one, null means zero
200: * @return the new duration instance
201: */
202: public Duration minus(ReadableDuration amount) {
203: if (amount == null) {
204: return this ;
205: }
206: return withDurationAdded(amount.getMillis(), -1);
207: }
208:
209: }
|