View Javadoc
1   /*
2    * ====================================================================
3    * Licensed to the Apache Software Foundation (ASF) under one
4    * or more contributor license agreements.  See the NOTICE file
5    * distributed with this work for additional information
6    * regarding copyright ownership.  The ASF licenses this file
7    * to you under the Apache License, Version 2.0 (the
8    * "License"); you may not use this file except in compliance
9    * with the License.  You may obtain a copy of the License at
10   *
11   *   http://www.apache.org/licenses/LICENSE-2.0
12   *
13   * Unless required by applicable law or agreed to in writing,
14   * software distributed under the License is distributed on an
15   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16   * KIND, either express or implied.  See the License for the
17   * specific language governing permissions and limitations
18   * under the License.
19   * ====================================================================
20   *
21   * This software consists of voluntary contributions made by many
22   * individuals on behalf of the Apache Software Foundation.  For more
23   * information on the Apache Software Foundation, please see
24   * <http://www.apache.org/>.
25   *
26   */
27  
28  package org.apache.hc.core5.util;
29  
30  import java.text.ParseException;
31  import java.util.concurrent.TimeUnit;
32  
33  import org.apache.hc.core5.annotation.Contract;
34  import org.apache.hc.core5.annotation.ThreadingBehavior;
35  
36  /**
37   * Represents a timeout value as a non-negative {@code long} time and {@link TimeUnit}.
38   *
39   * @since 5.0
40   */
41  @Contract(threading = ThreadingBehavior.IMMUTABLE)
42  public class Timeout extends TimeValue {
43  
44      /**
45       * A zero milliseconds {@link Timeout}.
46       */
47      public static final Timeout ZERO_MILLISECONDS = Timeout.of(0, TimeUnit.MILLISECONDS);
48  
49      /**
50       * A disabled timeout represented as 0 {@code MILLISECONDS}.
51       */
52      public static final Timeout DISABLED = ZERO_MILLISECONDS;
53  
54      /**
55       * Returns the given {@code timeout} if it is not {@code null}, if {@code null} then returns {@link #DISABLED}.
56       *
57       * @param timeout may be {@code null}
58       * @return {@code timeValue} or {@link #DISABLED}
59       */
60      public static TimeoutTimeout">Timeout defaultsToDisabled(final Timeout timeout) {
61          return defaultsTo(timeout, DISABLED);
62      }
63  
64      /**
65       * Creates a Timeout.
66       *
67       * @param duration the time duration in the given {@code timeUnit}.
68       * @param timeUnit the time unit for the given duration.
69       * @return a Timeout
70       */
71      public static Timeout of(final long duration, final TimeUnit timeUnit) {
72          return new Timeout(duration, timeUnit);
73      }
74  
75      /**
76       * Creates a Timeout.
77       *
78       * @param days the duration in days and the given {@code timeUnit}.
79       * @return a Timeout
80       */
81      public static Timeout ofDays(final long days) {
82          return of(days, TimeUnit.DAYS);
83      }
84  
85      /**
86       * Creates a Timeout.
87       *
88       * @param hours the duration in hours and the given {@code timeUnit}.
89       * @return a Timeout
90       */
91      public static Timeout ofHours(final long hours) {
92          return of(hours, TimeUnit.HOURS);
93      }
94  
95      /**
96       * Creates a Timeout.
97       *
98       * @param microseconds the duration in seconds and the given {@code timeUnit}.
99       * @return a Timeout
100      */
101     public static Timeout ofMicroseconds(final long microseconds) {
102         return of(microseconds, TimeUnit.MICROSECONDS);
103     }
104 
105     /**
106      * Creates a Timeout.
107      *
108      * @param milliseconds the duration in milliseconds and the given {@code timeUnit}.
109      * @return a Timeout
110      * @deprecated Use {@link #ofMicroseconds(long)}
111      */
112     @Deprecated
113     public static Timeout ofMillis(final long milliseconds) {
114         return of(milliseconds, TimeUnit.MILLISECONDS);
115     }
116 
117     /**
118      * Creates a Timeout.
119      *
120      * @param milliseconds the duration in milliseconds and the given {@code timeUnit}.
121      * @return a Timeout
122      */
123     public static Timeout ofMilliseconds(final long milliseconds) {
124         return of(milliseconds, TimeUnit.MILLISECONDS);
125     }
126 
127     /**
128      * Creates a Timeout.
129      *
130      * @param minutes the duration in minutes and the given {@code timeUnit}.
131      * @return a Timeout
132      */
133     public static Timeout ofMinutes(final long minutes) {
134         return of(minutes, TimeUnit.MINUTES);
135     }
136 
137     /**
138      * Creates a Timeout.
139      *
140      * @param nanoseconds the duration in seconds and the given {@code timeUnit}.
141      * @return a Timeout
142      */
143     public static Timeout ofNanoseconds(final long nanoseconds) {
144         return of(nanoseconds, TimeUnit.NANOSECONDS);
145     }
146 
147     /**
148      * Creates a Timeout.
149      *
150      * @param seconds the duration in seconds and the given {@code timeUnit}.
151      * @return a Timeout
152      */
153     public static Timeout ofSeconds(final long seconds) {
154         return of(seconds, TimeUnit.SECONDS);
155     }
156 
157     /**
158      * Parses a Timeout in the format {@code <Integer><SPACE><TimeUnit>}, for example {@code "1,200 MILLISECONDS"}
159      *
160      * @param value the TimeValue to parse
161      * @return a new TimeValue
162      * @throws ParseException if the number cannot be parsed
163      */
164     public static Timeout parse(final String value) throws ParseException {
165         return TimeValue.parse(value).toTimeout();
166     }
167 
168     Timeout(final long duration, final TimeUnit timeUnit) {
169         super(Args.notNegative(duration, "duration"), Args.notNull(timeUnit, "timeUnit"));
170     }
171 
172     /**
173      * Whether this timeout is disabled.
174      *
175      * @return Whether this timeout is disabled.
176      */
177     public boolean isDisabled() {
178         return getDuration() == 0;
179     }
180 
181     /**
182      * Whether this timeout is enabled.
183      *
184      * @return Whether this timeout is disabled.
185      */
186     public boolean isEnabled() {
187         return !isDisabled();
188     }
189 
190 }