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 one milliseconds {@link Timeout}. 51 */ 52 public static final Timeout ONE_MILLISECOND = Timeout.of(1, TimeUnit.MILLISECONDS); 53 54 /** 55 * A disabled timeout represented as 0 {@code MILLISECONDS}. 56 */ 57 public static final Timeout DISABLED = ZERO_MILLISECONDS; 58 59 /** 60 * Returns the given {@code timeout} if it is not {@code null}, if {@code null} then returns {@link #DISABLED}. 61 * 62 * @param timeout may be {@code null} 63 * @return {@code timeValue} or {@link #DISABLED} 64 */ 65 public static TimeoutTimeout">Timeout defaultsToDisabled(final Timeout timeout) { 66 return defaultsTo(timeout, DISABLED); 67 } 68 69 /** 70 * Creates a Timeout. 71 * 72 * @param duration the time duration in the given {@code timeUnit}. 73 * @param timeUnit the time unit for the given duration. 74 * @return a Timeout 75 */ 76 public static Timeout of(final long duration, final TimeUnit timeUnit) { 77 return new Timeout(duration, timeUnit); 78 } 79 80 /** 81 * Creates a Timeout. 82 * 83 * @param days the duration in days and the given {@code timeUnit}. 84 * @return a Timeout 85 */ 86 public static Timeout ofDays(final long days) { 87 return of(days, TimeUnit.DAYS); 88 } 89 90 /** 91 * Creates a Timeout. 92 * 93 * @param hours the duration in hours and the given {@code timeUnit}. 94 * @return a Timeout 95 */ 96 public static Timeout ofHours(final long hours) { 97 return of(hours, TimeUnit.HOURS); 98 } 99 100 /** 101 * Creates a Timeout. 102 * 103 * @param microseconds the duration in seconds and the given {@code timeUnit}. 104 * @return a Timeout 105 */ 106 public static Timeout ofMicroseconds(final long microseconds) { 107 return of(microseconds, TimeUnit.MICROSECONDS); 108 } 109 110 /** 111 * Creates a Timeout. 112 * 113 * @param milliseconds the duration in milliseconds and the given {@code timeUnit}. 114 * @return a Timeout 115 */ 116 public static Timeout ofMilliseconds(final long milliseconds) { 117 return of(milliseconds, TimeUnit.MILLISECONDS); 118 } 119 120 /** 121 * Creates a Timeout. 122 * 123 * @param minutes the duration in minutes and the given {@code timeUnit}. 124 * @return a Timeout 125 */ 126 public static Timeout ofMinutes(final long minutes) { 127 return of(minutes, TimeUnit.MINUTES); 128 } 129 130 /** 131 * Creates a Timeout. 132 * 133 * @param nanoseconds the duration in seconds and the given {@code timeUnit}. 134 * @return a Timeout 135 */ 136 public static Timeout ofNanoseconds(final long nanoseconds) { 137 return of(nanoseconds, TimeUnit.NANOSECONDS); 138 } 139 140 /** 141 * Creates a Timeout. 142 * 143 * @param seconds the duration in seconds and the given {@code timeUnit}. 144 * @return a Timeout 145 */ 146 public static Timeout ofSeconds(final long seconds) { 147 return of(seconds, TimeUnit.SECONDS); 148 } 149 150 /** 151 * Parses a Timeout in the format {@code <Integer><SPACE><TimeUnit>}, for example {@code "1,200 MILLISECONDS"} 152 * 153 * @param value the TimeValue to parse 154 * @return a new TimeValue 155 * @throws ParseException if the number cannot be parsed 156 */ 157 public static Timeout parse(final String value) throws ParseException { 158 return TimeValue.parse(value).toTimeout(); 159 } 160 161 Timeout(final long duration, final TimeUnit timeUnit) { 162 super(Args.notNegative(duration, "duration"), Args.notNull(timeUnit, "timeUnit")); 163 } 164 165 /** 166 * Whether this timeout is disabled. 167 * 168 * @return Whether this timeout is disabled. 169 */ 170 public boolean isDisabled() { 171 return getDuration() == 0; 172 } 173 174 /** 175 * Whether this timeout is enabled. 176 * 177 * @return Whether this timeout is disabled. 178 */ 179 public boolean isEnabled() { 180 return !isDisabled(); 181 } 182 183 }