GDateBuilder (XMLBeans 2.7.0 Documentation)

java.lang.Object
- org.apache.poi.xmlbeans.GDateBuilder

All Implemented Interfaces:

java.io.Serializable, GDateSpecification
```
public final class GDateBuilder
extends java.lang.Object
implements GDateSpecification, java.io.Serializable
```
Used to build GDates.
Like GDate, a GDateBuilder represents an Gregorian Date, Time, and Timezone, or subset of information (Year, Month, Day, Time, Timezone, or some combination). Wherever it provides guidance, the XML Schema 1.0 specification (plus published errata) is followed.
Instances may separately set or clear the year, month, day-of-month, and time-of-day. Not all operations are meaningful on all combinations. In particular, timezone normalization is only possible if there is a time, or a time together with a full date.

See Also:

Serialized Form

Field Summary
- Fields inherited from interface org.apache.poi.xmlbeans.GDateSpecification
  HAS_DAY, HAS_MONTH, HAS_TIME, HAS_TIMEZONE, HAS_YEAR

Constructor Summary

Constructors
Constructor and Description
`GDateBuilder()` Constructs a GDateBuilder specifying no date or time
`GDateBuilder(java.util.Calendar calendar)`
`GDateBuilder(java.lang.CharSequence string)` Constructs a GDateBuilder from a lexical representation.
`GDateBuilder(java.util.Date date)` Constructs a GDateBuilder based on a java.util.Date.
`GDateBuilder(GDateSpecification gdate)` Construts a GDateBuilder by copying another GDateSpecificaiton.
`GDateBuilder(int year, int month, int day, int hour, int minute, int second, java.math.BigDecimal fraction)` Constructs a GDateBuilder with the specified year, month, day, hours, minutes, seconds, and optional fractional seconds, in an unspecified timezone.
`GDateBuilder(int year, int month, int day, int hour, int minute, int second, java.math.BigDecimal fraction, int tzSign, int tzHour, int tzMinute)` Constructs an absolute GDateBuilder with the specified year, month, day, hours, minutes, seconds, and optional fractional seconds, and in the timezone specified.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addDuration(int sign, int year, int month, int day, int hour, int minute, int second, java.math.BigDecimal fraction)` Adds a given duration to the date/time.
`void`	`addGDuration(GDurationSpecification duration)` Adds a given duration to the date/time.
`java.lang.String`	`canonicalString()` The canonical string representation.
`void`	`clearDay()` Clears the day-of-month.
`void`	`clearMonth()` Clears the month-of-year.
`void`	`clearTime()` Clears the time-of-day.
`void`	`clearTimeZone()` Clears the timezone.
`void`	`clearYear()` Clears the year.
`java.lang.Object`	`clone()` Builds another GDateBuilder with the same value as this one.
`int`	`compareToGDate(GDateSpecification datespec)` Comparison to another GDate.
`int`	`getBuiltinTypeCode()` Returns the builtin type code for the shape of the information contained in this instance, or 0 if the instance doesn't contain information corresponding to a Schema type.
`XmlCalendar`	`getCalendar()` Retrieves the value of the current time as an `XmlCalendar`.
`java.util.Date`	`getDate()` Retrieves the value of the current time as a java.util.Date instance.
`int`	`getDay()` Gets the day-of-month.
`int`	`getFlags()` Returns a combination of flags indicating the information contained by this GDate.
`java.math.BigDecimal`	`getFraction()` Gets the fraction-of-second.
`int`	`getHour()` Gets the hour-of-day.
`int`	`getJulianDate()` Returns the Julian date corresponding to this Gregorian date.
`int`	`getMillisecond()` Gets the rounded millisecond value.
`int`	`getMinute()` Gets the minute-of-hour.
`int`	`getMonth()` Gets the month-of-year.
`int`	`getSecond()` Gets the second-of-minute.
`int`	`getTimeZoneHour()` Gets the time zone hour.
`int`	`getTimeZoneMinute()` Gets the time zone minutes.
`int`	`getTimeZoneSign()` Gets the time zone sign.
`int`	`getYear()` Gets the year.
`boolean`	`hasDate()` True if this date/time specification specifies a full date (year, month, day)
`boolean`	`hasDay()` True if this date/time specification specifies a day-of-month.
`boolean`	`hasMonth()` True if this date/time specification specifies a month-of-year.
`boolean`	`hasTime()` True if this date/time specification specifies a time-of-day.
`boolean`	`hasTimeZone()` True if this date/time specification specifies a timezone.
`boolean`	`hasYear()` True if this date/time specification specifies a year.
`boolean`	`isImmutable()` True if the instance is immutable.
`boolean`	`isValid()` True if all date fields lie within their legal ranges.
`void`	`normalize()` Normalizes the instance, ensuring date and time fields are within their normal ranges.
`void`	`normalizeToTimeZone(int tzTotalMinutes)` Normalizes to a time zone specified by a number of offset minutes rather than sign/hour/minute; for example, normalizeToTimeZone(-60) is the same as normalizeToTimeZone(-1, 1, 0).
`void`	`normalizeToTimeZone(int tzSign, int tzHour, int tzMinute)` If the time and timezone are known, this method changes the timezone to the specified UTC offset, altering minutes, hours, day, month, and year as necessary to ensure that the actual described moment in time is the same.
`void`	`setBuiltinTypeCode(int typeCode)` Clears the fields in this GDateBuilder that are not applicable for the given SchemaType date code.
`void`	`setDate(java.util.Date date)` Sets the current time and date based on a java.util.Date instance.
`void`	`setDay(int day)` Sets the day-of-month.
`void`	`setGDate(GDateSpecification gdate)` Copies a GDateSpecification, completely replacing the current information in this GDateBuilder.
`void`	`setJulianDate(int julianday)` Sets the Gregorian date based on the given Julian date.
`void`	`setMonth(int month)` Sets the month-of-year.
`void`	`setTime(int hour, int minute, int second, java.math.BigDecimal fraction)` Sets the time.
`void`	`setTimeZone(int tzTotalMinutes)` Sets the time zone based on a number of offset minutes rather than sign/hour/minute; for example, setTimeZone(-60) is the same as setTimeZone(-1, 1, 0).
`void`	`setTimeZone(int tzSign, int tzHour, int tzMinute)` Sets the time zone without changing the other time fields.
`void`	`setYear(int year)` Sets the year.
`void`	`subtractGDuration(GDurationSpecification duration)` Subtracts a given duration from the date/time.
`GDate`	`toGDate()` Builds a GDate from this GDateBuilder.
`java.lang.String`	`toString()` The natural string representation.

Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - GDateBuilder
```
public GDateBuilder()
```
    Constructs a GDateBuilder specifying no date or time
  - GDateBuilder
```
public GDateBuilder(GDateSpecification gdate)
```
    Construts a GDateBuilder by copying another GDateSpecificaiton.
  - GDateBuilder
```
public GDateBuilder(java.lang.CharSequence string)
```
    Constructs a GDateBuilder from a lexical representation. The lexical space contains the union of the lexical spaces of all the schema date/time types (except for duration).
  - GDateBuilder
```
public GDateBuilder(java.util.Calendar calendar)
```
  - GDateBuilder
```
public GDateBuilder(int year,
                    int month,
                    int day,
                    int hour,
                    int minute,
                    int second,
                    java.math.BigDecimal fraction)
```
    Constructs a GDateBuilder with the specified year, month, day, hours, minutes, seconds, and optional fractional seconds, in an unspecified timezone.
    Note that by not specifying the timezone the GDateBuilder becomes partially unordered with respect to timesthat do have a specified timezone.
    
    Parameters:
    
    year - The year
    
    month - The month, from 1-12
    
    day - The day of month, from 1-31
    
    hour - The hour of day, from 0-23
    
    minute - The minute of hour, from 0-59
    
    second - The second of minute, from 0-59
    
    fraction - The fraction of second, 0.0 to 0.999... (may be null)
  - GDateBuilder
```
public GDateBuilder(int year,
                    int month,
                    int day,
                    int hour,
                    int minute,
                    int second,
                    java.math.BigDecimal fraction,
                    int tzSign,
                    int tzHour,
                    int tzMinute)
```
    Constructs an absolute GDateBuilder with the specified year, month, day, hours, minutes, seconds, and optional fractional seconds, and in the timezone specified.
    Note that you can reexpress the GDateBuilder in any timezone using normalizeToTimeZone(). The normalize() method normalizes to UTC.
    If you wish to have a time or date that isn't in a specified timezone, then use the constructor that does not include the timezone arguments.
    
    Parameters:
    
    year - the year
    
    month - the month, from 1-12
    
    day - the day of month, from 1-31
    
    hour - the hour of day, from 0-23
    
    minute - the minute of hour, from 0-59
    
    second - the second of minute, from 0-59
    
    fraction - the fraction of second, 0.0 to 0.999... (may be null)
    
    tzSign - the timezone offset sign, either +1, 0, or -1
    
    tzHour - the timezone offset hour
    
    tzMinute - the timezone offset minute
  - GDateBuilder
```
public GDateBuilder(java.util.Date date)
```
    Constructs a GDateBuilder based on a java.util.Date.
    The current offset of the default timezone is used as the timezone.
    For example, if eastern daylight time is in effect at the given date, the timezone on the east coast of the united states translates to GMT-05:00 (EST) + 1:00 (DT offset) == GMT-04:00.
    
    Parameters:
    
    date - the date object to copy
- Method Detail
  - clone
```
public java.lang.Object clone()
```
    Builds another GDateBuilder with the same value as this one.
    
    Overrides:
    
    clone in class java.lang.Object
  - toGDate
```
public GDate toGDate()
```
    Builds a GDate from this GDateBuilder.
  - isImmutable
```
public boolean isImmutable()
```
    True if the instance is immutable.
    
    Specified by:
    
    isImmutable in interface GDateSpecification
  - getFlags
```
public int getFlags()
```
    Returns a combination of flags indicating the information contained by this GDate. The five flags are HAS_TIMEZONE, HAS_YEAR, HAS_MONTH, HAS_DAY, and HAS_TIME.
    
    Specified by:
    
    getFlags in interface GDateSpecification
  - hasTimeZone
```
public final boolean hasTimeZone()
```
    True if this date/time specification specifies a timezone.
    
    Specified by:
    
    hasTimeZone in interface GDateSpecification
  - hasYear
```
public final boolean hasYear()
```
    True if this date/time specification specifies a year.
    
    Specified by:
    
    hasYear in interface GDateSpecification
  - hasMonth
```
public final boolean hasMonth()
```
    True if this date/time specification specifies a month-of-year.
    
    Specified by:
    
    hasMonth in interface GDateSpecification
  - hasDay
```
public final boolean hasDay()
```
    True if this date/time specification specifies a day-of-month.
    
    Specified by:
    
    hasDay in interface GDateSpecification
  - hasTime
```
public final boolean hasTime()
```
    True if this date/time specification specifies a time-of-day.
    
    Specified by:
    
    hasTime in interface GDateSpecification
  - hasDate
```
public final boolean hasDate()
```
    True if this date/time specification specifies a full date (year, month, day)
    
    Specified by:
    
    hasDate in interface GDateSpecification
  - getYear
```
public final int getYear()
```
    Gets the year. Should be a four-digit year specification.
    
    Specified by:
    
    getYear in interface GDateSpecification
  - getMonth
```
public final int getMonth()
```
    Gets the month-of-year. January is 1.
    
    Specified by:
    
    getMonth in interface GDateSpecification
  - getDay
```
public final int getDay()
```
    Gets the day-of-month. The first day of each month is 1.
    
    Specified by:
    
    getDay in interface GDateSpecification
  - getHour
```
public final int getHour()
```
    Gets the hour-of-day. Midnight is 0, and 11PM is 23.
    
    Specified by:
    
    getHour in interface GDateSpecification
  - getMinute
```
public final int getMinute()
```
    Gets the minute-of-hour. Range from 0 to 59.
    
    Specified by:
    
    getMinute in interface GDateSpecification
  - getSecond
```
public final int getSecond()
```
    Gets the second-of-minute. Range from 0 to 59.
    
    Specified by:
    
    getSecond in interface GDateSpecification
  - getFraction
```
public final java.math.BigDecimal getFraction()
```
    Gets the fraction-of-second. Range from 0 (inclusive) to 1 (exclusive).
    
    Specified by:
    
    getFraction in interface GDateSpecification
  - getMillisecond
```
public final int getMillisecond()
```
    Gets the rounded millisecond value. Range from 0 to 999
    
    Specified by:
    
    getMillisecond in interface GDateSpecification
  - getTimeZoneSign
```
public final int getTimeZoneSign()
```
    Gets the time zone sign. For time zones east of GMT, this is positive; for time zones west, this is negative.
    
    Specified by:
    
    getTimeZoneSign in interface GDateSpecification
  - getTimeZoneHour
```
public final int getTimeZoneHour()
```
    Gets the time zone hour. This is always positive: for the sign, look at getTimeZoneSign().
    
    Specified by:
    
    getTimeZoneHour in interface GDateSpecification
  - getTimeZoneMinute
```
public final int getTimeZoneMinute()
```
    Gets the time zone minutes. This is always positive: for the sign, look at getTimeZoneSign().
    
    Specified by:
    
    getTimeZoneMinute in interface GDateSpecification
  - setYear
```
public void setYear(int year)
```
    Sets the year. Should be a four-digit year specification.
    
    Parameters:
    
    year - the year
  - setMonth
```
public void setMonth(int month)
```
    Sets the month-of-year. January is 1.
    
    Parameters:
    
    month - the month, from 1-12
  - setDay
```
public void setDay(int day)
```
    Sets the day-of-month. The first day of each month is 1.
    
    Parameters:
    
    day - the day of month, from 1-31
  - setTime
```
public void setTime(int hour,
                    int minute,
                    int second,
                    java.math.BigDecimal fraction)
```
    Sets the time. Hours in the day range from 0 to 23; minutes and seconds range from 0 to 59; and fractional seconds range from 0 (inclusive) to 1 (exclusive). The fraction can be null and is assumed to be zero.
    
    Parameters:
    
    hour - the hour of day, from 0-23 or 24 only if min, sec and fraction are 0
    
    minute - the minute of hour, from 0-59
    
    second - the second of minute, from 0-59
    
    fraction - the fraction of second, 0.0 to 0.999... (may be null)
  - setTimeZone
```
public void setTimeZone(int tzSign,
                        int tzHour,
                        int tzMinute)
```
    Sets the time zone without changing the other time fields. If you with to adjust other time fields to express the same actual moment in time in a different time zone, use normalizeToTimeZone.
    Timezones must be between -14:00 and +14:00. Sign must be -1 or 1 (or 0 for UTC only), and the offset hours and minute arguments must be nonnegative.
    
    Parameters:
    
    tzSign - the timezone offset sign, either +1, 0, or -1
    
    tzHour - the timezone offset hour
    
    tzMinute - the timezone offset minute
  - setTimeZone
```
public void setTimeZone(int tzTotalMinutes)
```
    Sets the time zone based on a number of offset minutes rather than sign/hour/minute; for example, setTimeZone(-60) is the same as setTimeZone(-1, 1, 0).
  - clearYear
```
public void clearYear()
```
    Clears the year. After clearing, hasYear returns false and the value of getYear is undefined.
  - clearMonth
```
public void clearMonth()
```
    Clears the month-of-year. After clearing. hasMonth returns false and the value of getMonth is undefined.
  - clearDay
```
public void clearDay()
```
    Clears the day-of-month. After clearing. hasDay returns false and the value of getDay is undefined.
  - clearTime
```
public void clearTime()
```
    Clears the time-of-day. After clearing. hasTime returns false and the value of getTime is undefined.
  - clearTimeZone
```
public void clearTimeZone()
```
    Clears the timezone. After clearing. hasTimeZone returns false and the value of getTimeZoneHour and getTimeZoneMinute are undefined. Does not change the other time fields.
  - isValid
```
public boolean isValid()
```
    True if all date fields lie within their legal ranges. A GDateBuilder can be invalid, for example, if you change the month to February and the day-of-month is 31.
    
    Specified by:
    
    isValid in interface GDateSpecification
  - normalize
```
public void normalize()
```
    Normalizes the instance, ensuring date and time fields are within their normal ranges.
    If no timezone or no time is specified, or if a partial date is specified, this method does nothing, and leaves the timezone information as-is.
    If a time or time and date is specified, this method normalizes the timezone to UTC.
  - normalizeToTimeZone
```
public void normalizeToTimeZone(int tzSign,
                                int tzHour,
                                int tzMinute)
```
    If the time and timezone are known, this method changes the timezone to the specified UTC offset, altering minutes, hours, day, month, and year as necessary to ensure that the actual described moment in time is the same.
    It is an error to operate on instances without a time or timezone, or with a partially specified date.
    
    Parameters:
    
    tzSign - the timezone offset sign, either +1, 0, or -1
    
    tzHour - the timezone offset hour
    
    tzMinute - the timezone offset minute
  - normalizeToTimeZone
```
public void normalizeToTimeZone(int tzTotalMinutes)
```
    Normalizes to a time zone specified by a number of offset minutes rather than sign/hour/minute; for example, normalizeToTimeZone(-60) is the same as normalizeToTimeZone(-1, 1, 0).
  - addGDuration
```
public void addGDuration(GDurationSpecification duration)
```
    Adds a given duration to the date/time.
    
    Parameters:
    
    duration - the duration to add
  - subtractGDuration
```
public void subtractGDuration(GDurationSpecification duration)
```
    Subtracts a given duration from the date/time.
    
    Parameters:
    
    duration - the duration to subtract
  - addDuration
```
public void addDuration(int sign,
                        int year,
                        int month,
                        int day,
                        int hour,
                        int minute,
                        int second,
                        java.math.BigDecimal fraction)
```
    Adds a given duration to the date/time.
    
    Parameters:
    
    sign - +1 to add, -1 to subtract
    
    year - the number of years to add
    
    month - the number of months to add
    
    day - the number of days to add
    
    hour - the number of hours to add
    
    minute - the number of minutes to add
    
    second - the number of seconds to add
    
    fraction - the number of fractional seconds to add (may be null)
  - getJulianDate
```
public final int getJulianDate()
```
    Returns the Julian date corresponding to this Gregorian date. The Julian date (JD) is a continuous count of days from 1 January 4713 BC.
    
    Specified by:
    
    getJulianDate in interface GDateSpecification
  - setJulianDate
```
public void setJulianDate(int julianday)
```
    Sets the Gregorian date based on the given Julian date. The Julian date (JD) is a continuous count of days from 1 January 4713 BC.
    
    Parameters:
    
    julianday - the julian day number
  - setDate
```
public void setDate(java.util.Date date)
```
    Sets the current time and date based on a java.util.Date instance.
    The timezone offset used is based on the default TimeZone. (The default TimeZone is consulted to incorporate daylight savings offsets if applicable for the current date as well as the base timezone offset.)
    If you wish to normalize the timezone, e.g., to UTC, follow this with a call to normalizeToTimeZone.
    
    Parameters:
    
    date - the Date object to copy
  - setGDate
```
public void setGDate(GDateSpecification gdate)
```
    Copies a GDateSpecification, completely replacing the current information in this GDateBuilder.
    
    Parameters:
    
    gdate - the GDateSpecification to copy
  - getCalendar
```
public XmlCalendar getCalendar()
```
    Retrieves the value of the current time as an XmlCalendar.
    XmlCalendar is a subclass of GregorianCalendar which is slightly customized to match XML schema date rules.
    The returned XmlCalendar has only those time and date fields set that are reflected in the GDate object. Because of the way the Calendar contract works, any information in the isSet() vanishes as soon as you view any unset field using get() methods. This means that if it is important to understand which date fields are set, you must call isSet() first before get().
    
    Specified by:
    
    getCalendar in interface GDateSpecification
  - getDate
```
public java.util.Date getDate()
```
    Retrieves the value of the current time as a java.util.Date instance.
    
    Specified by:
    
    getDate in interface GDateSpecification
  - compareToGDate
```
public final int compareToGDate(GDateSpecification datespec)
```
    Comparison to another GDate.
    - Returns -1 if this < date. (less-than)
    - Returns 0 if this == date. (equal)
    - Returns 1 if this > date. (greater-than)
    - Returns 2 if this <> date. (incomparable)
    Two instances are incomparable if they have different amounts of information.
    Specified by:
    
    compareToGDate in interface GDateSpecification
    
    Parameters:
    
    datespec - the date to compare against
  - getBuiltinTypeCode
```
public final int getBuiltinTypeCode()
```
    Returns the builtin type code for the shape of the information contained in this instance, or 0 if the instance doesn't contain information corresponding to a Schema type.
    Value will be equal to SchemaType.BTC_NOT_BUILTIN, SchemaType.BTC_G_YEAR, SchemaType.BTC_G_YEAR_MONTH, SchemaType.BTC_G_MONTH, SchemaType.BTC_G_MONTH_DAY, SchemaType.BTC_G_DAY, SchemaType.BTC_DATE, SchemaType.BTC_DATE_TIME, or SchemaType.BTC_TIME.
    
    Specified by:
    
    getBuiltinTypeCode in interface GDateSpecification
  - setBuiltinTypeCode
```
public void setBuiltinTypeCode(int typeCode)
```
    Clears the fields in this GDateBuilder that are not applicable for the given SchemaType date code. The code should be SchemaType.BTC_G_YEAR, SchemaType.BTC_G_YEAR_MONTH, SchemaType.BTC_G_MONTH, SchemaType.BTC_G_MONTH_DAY, SchemaType.BTC_G_DAY, SchemaType.BTC_DATE, SchemaType.BTC_DATE_TIME, or SchemaType.BTC_TIME.
    
    Parameters:
    
    typeCode - the type code to apply
  - canonicalString
```
public java.lang.String canonicalString()
```
    The canonical string representation. Specific moments or times-of-day in a specified timezone are normalized to UTC time to produce a canonical string form for them. Other recurring time specifications keep their timezone information.
    
    Specified by:
    
    canonicalString in interface GDateSpecification
  - toString
```
public final java.lang.String toString()
```
    The natural string representation. This represents the information that is available, including timezone. For types that correspond to defined schema types (schemaBuiltinTypeCode() > 0), this provides the natural lexical representation.
    When both time and timezone are specified, this string is not the canonical representation unless the timezone is UTC (Z) (since the same moment in time can be expressed in different timezones). To get a canonical string, use the canonicalString() method.
    
    Specified by:
    
    toString in interface GDateSpecification
    
    Overrides:
    
    toString in class java.lang.Object

Class GDateBuilder

Field Summary

Fields inherited from interface org.apache.poi.xmlbeans.GDateSpecification

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

GDateBuilder

GDateBuilder

GDateBuilder

GDateBuilder

GDateBuilder

GDateBuilder

GDateBuilder

Method Detail

clone

toGDate

isImmutable

getFlags

hasTimeZone

hasYear

hasMonth

hasDay

hasTime

hasDate

getYear

getMonth

getDay

getHour

getMinute

getSecond

getFraction

getMillisecond

getTimeZoneSign

getTimeZoneHour

getTimeZoneMinute

setYear

setMonth

setDay

setTime

setTimeZone

setTimeZone

clearYear

clearMonth

clearDay

clearTime

clearTimeZone

isValid

normalize

normalizeToTimeZone

normalizeToTimeZone

addGDuration

subtractGDuration

addDuration

getJulianDate

setJulianDate

setDate

setGDate

getCalendar

getDate

compareToGDate

getBuiltinTypeCode

setBuiltinTypeCode

canonicalString

toString