Preconditions for validating Duration instances

[kluever]

We have the following precondition-style utilities inside of google:

Durations.checkNotNegative(duration)
Durations.checkPositive(duration)

They throw IllegalArgumentException if the duration is negative or not positive (respectively). Negative durations often are a bug, so it's nice to validate Duration parameters like RPC timeouts or cache expirations. E.g.,

public final class Frobber {
  private final Duration timeout;
  public Frobber(Duration timeout) {
    this.timeout = checkPositive(timeout);
  }
}

Any chance we could find a home for these in threeten-extra?

[jodastephen]

And yes, this is an ideal addition.

The ThreeTen-Extra home for utilities is Temporals. While we could create an Amounts or Durations, I think Temporals would do just fine.

(If you can think of other validation-type things, then perhaps a TemporalValidation class might make sense, but when it is just two methods, the existing utils works OK.)

[kluever]

We have other things in our Durations static utility class if that helps make a case for a whole separate class? These just probably aren't as useful as the precondition-style APIs:

public static Duration ofMicros(long micros) { }
public static Duration ofSeconds(double seconds) { } // for legacy reasons, we have a *lot* of `double seconds` floating around inside of Google...yuck
public static Duration of(long value, TimeUnit timeUnit) { } // this is obsolete as of JDK9
public static long toMicros(Duration duration) { }
public static long toMicrosSaturated(Duration duration) { }
public static long toMillisSaturated(Duration duration) { }
public static long toNanosSaturated(Duration duration) { }
public static double toSecondsAsDouble(Duration duration) { }
public static DiscreteDomain<Duration> domain() { }

Makes Kotlin's extension-method feature look really appetizing, huh?

Also, minor thing, but we (Java Core Libs team) are generally -1 on the Utils suffix for classes. We probably could live with DurationUtils though if that's the consensus.

[jodastephen]

So, Temporals already has 5 methods that operate on Duration. I think that is likely the best fit, even if we end up adding more.

[jodastephen]

Actually, those 5 methods are on a branch (not master), so we do have naming room. Would you want another class named Durations though?