KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > joda > time > Duration


1 /*
2  * Copyright 2001-2005 Stephen Colebourne
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package org.joda.time;
17
18 import java.io.Serializable JavaDoc;
19
20 import org.joda.time.base.BaseDuration;
21 import org.joda.time.field.FieldUtils;
22
23 /**
24  * An immutable duration specifying a length of time in milliseconds.
25  * <p>
26  * A duration is defined by a fixed number of milliseconds.
27  * There is no concept of fields, such as days or seconds, as these fields can vary in length.
28  * A duration may be converted to a {@link Period} to obtain field values.
29  * This conversion will typically cause a loss of precision however.
30  * <p>
31  * Duration is thread-safe and immutable.
32  *
33  * @author Brian S O'Neill
34  * @author Stephen Colebourne
35  * @since 1.0
36  */
37 public final class Duration
38         extends BaseDuration
39         implements ReadableDuration, Serializable JavaDoc {
40
41     /** Constant representing zero millisecond duration */
42     public static final Duration ZERO = new Duration(0L);
43
44     /** Serialization version */
45     private static final long serialVersionUID = 2471658376918L;
46
47     /**
48      * Creates a duration from the given millisecond duration.
49      *
50      * @param duration the duration, in milliseconds
51      */
52     public Duration(long duration) {
53         super(duration);
54     }
55
56     /**
57      * Creates a duration from the given interval endpoints.
58      *
59      * @param startInstant interval start, in milliseconds
60      * @param endInstant interval end, in milliseconds
61      * @throws ArithmeticException if the duration exceeds a 64 bit long
62      */
63     public Duration(long startInstant, long endInstant) {
64         super(startInstant, endInstant);
65     }
66
67     /**
68      * Creates a duration from the given interval endpoints.
69      *
70      * @param start interval start, null means now
71      * @param end interval end, null means now
72      * @throws ArithmeticException if the duration exceeds a 64 bit long
73      */
74     public Duration(ReadableInstant start, ReadableInstant end) {
75         super(start, end);
76     }
77
78     /**
79      * Creates a duration from the specified object using the
80      * {@link org.joda.time.convert.ConverterManager ConverterManager}.
81      *
82      * @param duration duration to convert
83      * @throws IllegalArgumentException if duration is invalid
84      */
85     public Duration(Object JavaDoc duration) {
86         super(duration);
87     }
88
89     //-----------------------------------------------------------------------
90 /**
91      * Get this duration as an immutable <code>Duration</code> object
92      * by returning <code>this</code>.
93      *
94      * @return <code>this</code>
95      */
96     public Duration toDuration() {
97         return this;
98     }
99
100     //-----------------------------------------------------------------------
101 /**
102      * Creates a new Duration instance with a different milisecond length.
103      *
104      * @param duration the new length of the duration
105      * @return the new duration instance
106      */
107     public Duration withMillis(long duration) {
108         if (duration == getMillis()) {
109             return this;
110         }
111         return new Duration(duration);
112     }
113
114     /**
115      * Returns a new duration with this length plus that specified multiplied by the scalar.
116      * This instance is immutable and is not altered.
117      * <p>
118      * If the addition is zero, this instance is returned.
119      *
120      * @param durationToAdd the duration to add to this one
121      * @param scalar the amount of times to add, such as -1 to subtract once
122      * @return the new duration instance
123      */
124     public Duration withDurationAdded(long durationToAdd, int scalar) {
125         if (durationToAdd == 0 || scalar == 0) {
126             return this;
127         }
128         long add = FieldUtils.safeMultiply(durationToAdd, scalar);
129         long duration = FieldUtils.safeAdd(getMillis(), add);
130         return new Duration(duration);
131     }
132
133     /**
134      * Returns a new duration with this length plus that specified multiplied by the scalar.
135      * This instance is immutable and is not altered.
136      * <p>
137      * If the addition is zero, this instance is returned.
138      *
139      * @param durationToAdd the duration to add to this one, null means zero
140      * @param scalar the amount of times to add, such as -1 to subtract once
141      * @return the new duration instance
142      */
143     public Duration withDurationAdded(ReadableDuration durationToAdd, 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 }
210
Popular Tags