GDurationBuilder (xmlbeans API)

org.apache.xmlbeans

## Class GDurationBuilder

- java.lang.Object
- - org.apache.xmlbeans.GDurationBuilder

- All Implemented Interfaces:
    Serializable, GDurationSpecification

      public class GDurationBuilder
      extends Object
      implements GDurationSpecification, Serializable

  Used to build `GDurations`.
  See Also:
    Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `GDurationBuilder()` Constructs an empty GDurationBuilder representing zero seconds.
    `GDurationBuilder(GDurationSpecification gDuration)` Constructs a GDurationBuilder from another GDurationBuilderSpecification.
    `GDurationBuilder(int sign, int year, int month, int day, int hour, int minute, int second, BigDecimal fraction)` Constructs a GDurationBuilder with the specified sign, year, month, day, hours, minutes, seconds, and optional fractional seconds.
    `GDurationBuilder(String s)` Constructs a GDuration from a lexical representation.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addGDuration(GDurationSpecification duration)` Adds to this duration.
    `Object` | `clone()` Builds another GDurationBuilder with the same value as this one.
    `int` | `compareToGDuration(GDurationSpecification duration)` Comparison to another GDuration.
    `int` | `getDay()` Gets the day-of-month component.
    `BigDecimal` | `getFraction()` Gets the fraction-of-second.
    `int` | `getHour()` Gets the hour-of-day component.
    `int` | `getMinute()` Gets the minute-of-hour component.
    `int` | `getMonth()` Gets the month-of-year component.
    `int` | `getSecond()` Gets the second-of-minute component.
    `int` | `getSign()` Returns the sign of the duration: +1 is forwards and -1 is backwards in time.
    `int` | `getYear()` Gets the year component.
    `boolean` | `isImmutable()` All GDuration instances return true.
    `boolean` | `isValid()` Returns true if all of the individual components of the duration are nonnegative.
    `void` | `normalize()` Normalize a duration value.
    `void` | `setDay(int day)` Sets the day component.
    `void` | `setFraction(BigDecimal fraction)` Sets the fraction-of-second component.
    `void` | `setHour(int hour)` Sets the hour component.
    `void` | `setMinute(int minute)` Sets the minute component.
    `void` | `setMonth(int month)` Sets the month component.
    `void` | `setSecond(int second)` Sets the second component.
    `void` | `setSign(int sign)` Sets the sign.
    `void` | `setYear(int year)` Sets the year component.
    `static String` | `stripTrailingZeros(String s)`
    `void` | `subtractGDuration(GDurationSpecification duration)` Subtracts from this duration.
    `GDuration` | `toGDuration()` Builds a GDuration from this GDurationBuilder.
    `static String` | `toPlainString(BigDecimal bd)`
    `String` | `toString()` The natural string representation of the duration.

    - ### Methods inherited from class java.lang.Object

      `equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### GDurationBuilder

          public GDurationBuilder()

      Constructs an empty GDurationBuilder representing zero seconds.

    - #### GDurationBuilder

          public GDurationBuilder(String s)

      Constructs a GDuration from a lexical representation.

    - #### GDurationBuilder

          public GDurationBuilder(int sign,
                                  int year,
                                  int month,
                                  int day,
                                  int hour,
                                  int minute,
                                  int second,
                                  BigDecimal fraction)

      Constructs a GDurationBuilder with the specified sign, year, month, day, hours, minutes, seconds, and optional fractional seconds.
      Parameters:
        `sign` - +1 for a positive duration, -1 for a negative duration
      Throws:
        `IllegalArgumentException` - if the sign is not 1 or -1

    - #### GDurationBuilder

          public GDurationBuilder(GDurationSpecification gDuration)

      Constructs a GDurationBuilder from another GDurationBuilderSpecification.

  - ### Method Detail

    - #### clone

          public Object clone()

      Builds another GDurationBuilder with the same value as this one.
      Overrides:
        `clone` in class `Object`

    - #### toGDuration

          public GDuration toGDuration()

      Builds a GDuration from this GDurationBuilder.

    - #### addGDuration

          public void addGDuration(GDurationSpecification duration)

      Adds to this duration. Does a fieldwise add, with no normalization.

    - #### subtractGDuration

          public void subtractGDuration(GDurationSpecification duration)

      Subtracts from this duration. Does a fieldwise subtraction, with no normalization.

    - #### setSign

          public final void setSign(int sign)

      Sets the sign.

    - #### setYear

          public void setYear(int year)

      Sets the year component.

    - #### setMonth

          public void setMonth(int month)

      Sets the month component.

    - #### setDay

          public void setDay(int day)

      Sets the day component.

    - #### setHour

          public void setHour(int hour)

      Sets the hour component.

    - #### setMinute

          public void setMinute(int minute)

      Sets the minute component.

    - #### setSecond

          public void setSecond(int second)

      Sets the second component.

    - #### setFraction

          public void setFraction(BigDecimal fraction)

      Sets the fraction-of-second component.

    - #### isImmutable

          public final boolean isImmutable()

      All GDuration instances return true.
      Specified by:
        `isImmutable` in interface `GDurationSpecification`

    - #### getSign

          public final int getSign()

      Returns the sign of the duration: +1 is forwards and -1 is backwards in time. This value does not necessarily reflect the true direction of the duration if the duration is not normalized or not normalizable.
      Specified by:
        `getSign` in interface `GDurationSpecification`

    - #### getYear

          public final int getYear()

      Gets the year component.
      Specified by:
        `getYear` in interface `GDurationSpecification`

    - #### getMonth

          public final int getMonth()

      Gets the month-of-year component.
      Specified by:
        `getMonth` in interface `GDurationSpecification`

    - #### getDay

          public final int getDay()

      Gets the day-of-month component.
      Specified by:
        `getDay` in interface `GDurationSpecification`

    - #### getHour

          public final int getHour()

      Gets the hour-of-day component.
      Specified by:
        `getHour` in interface `GDurationSpecification`

    - #### getMinute

          public final int getMinute()

      Gets the minute-of-hour component.
      Specified by:
        `getMinute` in interface `GDurationSpecification`

    - #### getSecond

          public final int getSecond()

      Gets the second-of-minute component.
      Specified by:
        `getSecond` in interface `GDurationSpecification`

    - #### getFraction

          public BigDecimal getFraction()

      Gets the fraction-of-second. Range from 0 (inclusive) to 1 (exclusive).
      Specified by:
        `getFraction` in interface `GDurationSpecification`

    - #### isValid

          public boolean isValid()

      Returns true if all of the individual components of the duration are nonnegative.
      Specified by:
        `isValid` in interface `GDurationSpecification`

    - #### normalize

          public void normalize()

      Normalize a duration value. This ensures that months, hours, minutes, seconds, and fractions are positive and within the ranges 0..11, 0..23, 0..59, etc. Negative durations are indicated by a negative sign rather than negative components.

      Most duration specifications can be normalized to valid durations with all positive components, but not all of them can.

      The only situations which cannot be normalized are where the year/month and the day/hour/minute/second offsets are of opposite sign. Days cannot be carried into months since the length of a Gregorian month is variable depending on when the duration is applied. In these cases, this method normalizes the components so that "day" is the only negative component.

    - #### compareToGDuration

          public final int compareToGDuration(GDurationSpecification duration)

      Comparison to another GDuration.
      - Returns -1 if this < duration. (less-than)
      - Returns 0 if this == duration. (equal)
      - Returns 1 if this > duration. (greater-than)
      - Returns 2 if this <> duration. (incomparable)
      Two instances are incomparable if they have different amounts of information.
      Specified by:
        `compareToGDuration` in interface `GDurationSpecification`

    - #### toString

          public String toString()

      The natural string representation of the duration.

      Any components that are zero are omitted. Note that if the duration is invalid, i.e., it has negative components, those negative components are serialized out here. To check for validity, use the isValid() method; and to normalize most durations to a valid form use the normalize() method.

      Overrides:
        `toString` in class `Object`

    - #### toPlainString

          public static String toPlainString(BigDecimal bd)

    - #### stripTrailingZeros

          public static String stripTrailingZeros(String s)