Class SqlInterval

java.lang.Object
com.pyranid.SqlInterval

@Immutable public final class SqlInterval extends Object
An immutable SQL interval with independent calendar-month, calendar-day and elapsed-time components. Months and days are never converted into a guessed elapsed length, and elapsed hours are never carried into calendar days. Each component may have its own sign.

Equality compares these fields exactly: one calendar day differs from 24 elapsed hours, and one month differs from 30 days. Database interval equality can use different rules. This type has no natural ordering and does not implement TemporalAmount: applying calendar fields to a zoned timestamp requires an explicit application policy, which can differ from the database's daylight-saving resolution.

Binding and reading depend on the configured database's interval families, precision and range. Column qualifiers, rounding and other SQL coercions can change the stored fields.

Oracle and generic drivers need target-family metadata to bind ZERO, because the value does not remember which factory created it. Computed values such as SqlInterval.of(Duration.between(a, a)) are also ZERO. Oracle exposes that metadata for direct assignment/comparison with an interval column and supported explicit interval casts, such as CAST(:value AS INTERVAL DAY TO SECOND). Uncast expressions, MERGE, PL/SQL blocks and INSERT ... SELECT can lack identifying metadata; ZERO then fails even though nonzero values bind. A cast must select the schema's actual interval family and is not a universal workaround; PL/SQL can still lack metadata. A CustomParameterBinder that handles only ZERO and returns fallback() otherwise can choose the family explicitly.

Since:
4.9.0
  • Field Details

    • ZERO

      public static final @NonNull SqlInterval ZERO
      The zero interval, without a YEAR-MONTH or DAY-SECOND family preference.
  • Method Details

    • of

      public static @NonNull SqlInterval of(@NonNull Duration time)
      Creates an elapsed-only interval. Duration.ofDays(1) remains 24 elapsed hours, not a calendar day.
      Parameters:
      time - elapsed time
      Returns:
      an interval with no calendar components
    • of

      public static @NonNull SqlInterval of(@NonNull Period period)
      Creates a calendar-only interval, folding years into total months while retaining calendar days. The period's year/month decomposition is not retained.
      Parameters:
      period - calendar period
      Returns:
      a calendar interval
      Throws:
      DateTimeException - if total months do not fit a signed 32-bit integer
    • of

      public static @NonNull SqlInterval of(@NonNull Period period, @NonNull Duration time)
      Creates an interval from calendar and elapsed components without combining days and hours.
      Parameters:
      period - calendar period, with years folded into total months
      time - elapsed time
      Returns:
      an interval retaining the independent components
      Throws:
      DateTimeException - if total months do not fit a signed 32-bit integer
    • of

      public static @NonNull SqlInterval of(@NonNull Integer months, @NonNull Integer days, @NonNull Duration time)
      Creates an interval without normalizing its three fields. Precision and database-specific range checks happen when binding; a value may retain nanoseconds even when a particular database supports only microseconds.
      Parameters:
      months - total calendar months
      days - calendar days
      time - elapsed time
      Returns:
      an interval retaining all three fields
    • getMonths

      Returns total calendar months, with years already folded in.
      Returns:
      total calendar months, with years already folded in
    • getDays

      Returns calendar days, independent of elapsed hours.
      Returns:
      calendar days, independent of elapsed hours
    • getTime

      Returns elapsed time, independent of calendar months and days.
      Returns:
      elapsed time, independent of calendar months and days
    • toDuration

      Returns the elapsed component only when there are no calendar components. Calendar days are deliberately not assumed to be 24 hours; use Duration.between(java.time.temporal.Temporal, java.time.temporal.Temporal) on original instant-compatible timestamps to calculate elapsed time.
      Returns:
      elapsed time
      Throws:
      DateTimeException - if months or days are nonzero
    • toPeriod

      Returns a normalized calendar period only when the elapsed component is zero. Normalization splits total months into years and months, retaining the day component unchanged.
      Returns:
      calendar period
      Throws:
      DateTimeException - if elapsed time is nonzero
    • equals

      public boolean equals(@Nullable Object other)
      Overrides:
      equals in class Object
    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object
    • toString

      Returns an ISO-style field representation with independent component signs, for example P14M-3DT4H5M6.789S. This is a value display, not portable SQL literal syntax. No public parser or text-storage convention is implied.
      Overrides:
      toString in class Object
      Returns:
      a representation retaining all components