GDateBuilder Class

com.bea.xml
GDateBuilder Class

public final class GDateBuilder

    extends Object
    implements GDateSpecification, Serializable

Used to build GDate.

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.


Hierarchy
Object
  GDateBuilder
All Implemented Interfaces

GDateSpecification, Serializable

Constructor Summary

GDateBuilder()

Constructs a GDateBuilder specifying no date or time
GDateBuilder(GDateSpecification gdate)

Construts a GDateBuilder by copying another GDateSpecificaiton.
GDateBuilder(int year, int month, int day, int hour, int minute, int second, 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.
GDateBuilder(int year, int month, int day, int hour, int minute, int second, BigDecimal fraction)

Constructs a GDateBuilder with the specified year, month, day, hours, minutes, seconds, and optional fractional seconds, in an unspecified timezone.
GDateBuilder(CharSequence string)

Constructs a GDateBuilder from a lexical representation.
GDateBuilder(Calendar calendar)

GDateBuilder(Date date)

Constructs a GDateBuilder based on a java.util.Date.
 

Method Summary

public void
addDuration(int sign, int year, int month, int day, int hour, int minute, int second, BigDecimal fraction)
Adds a given duration to the date/time.
public void
addGDuration(GDurationSpecification duration)
Adds a given duration to the date/time.
public String
canonicalString()
The canonical string representation.
public void
clearDay()
Clears the day-of-month.
public void
clearMonth()
Clears the month-of-year.
public void
clearTime()
Clears the time-of-day.
public void
clearTimeZone()
Clears the timezone.
public void
clearYear()
Clears the year.
public Object
clone()
Builds another GDateBuilder with the same value as this one.
public final int
compareToGDate(GDateSpecification datespec)
Comparison to another GDate.
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.
public XmlCalendar
getCalendar()
Retrieves the value of the current time as an XmlCalendar.
public Date
getDate()
Retrieves the value of the current time as a java.util.Date instance.
public final int
getDay()
Gets the day-of-month.
public int
getFlags()
Returns a combination of flags indicating the information contained by this GDate.
public final BigDecimal
getFraction()
Gets the fraction-of-second.
public final int
getHour()
Gets the hour-of-day.
public final int
getJulianDate()
Returns the Julian date corresponding to this Gregorian date.
public final int
getMillisecond()
Gets the rounded millisecond value.
public final int
getMinute()
Gets the minute-of-hour.
public final int
getMonth()
Gets the month-of-year.
public final int
getSecond()
Gets the second-of-minute.
public final int
getTimeZoneHour()
Gets the time zone hour.
public final int
getTimeZoneMinute()
Gets the time zone minutes.
public final int
getTimeZoneSign()
Gets the time zone sign.
public final int
getYear()
Gets the year.
public final boolean
hasDate()
True if this date/time specification specifies a full date (year, month, day)
public final boolean
hasDay()
True if this date/time specification specifies a day-of-month.
public final boolean
hasMonth()
True if this date/time specification specifies a month-of-year.
public final boolean
hasTime()
True if this date/time specification specifies a time-of-day.
public final boolean
hasTimeZone()
True if this date/time specification specifies a timezone.
public final boolean
hasYear()
True if this date/time specification specifies a year.
public boolean
isImmutable()
True if the instance is immutable.
public boolean
isValid()
True if all date fields lie within their legal ranges.
public void
normalize()
Normalizes the instance, ensuring date and time fields are within their normal ranges.
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.
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).
public void
setBuiltinTypeCode(int typeCode)
Clears the fields in this GDateBuilder that are not applicable for the given SchemaType date code.
public void
setDate(Date date)
Sets the current time and date based on a java.util.Date instance.
public void
setDay(int day)
Sets the day-of-month.
public void
setGDate(GDateSpecification gdate)
Copies a GDateSpecification, completely replacing the current information in this GDateBuilder.
public void
setJulianDate(int julianday)
Sets the Gregorian date based on the given Julian date.
public void
setMonth(int month)
Sets the month-of-year.
public void
setTime(int hour, int minute, int second, BigDecimal fraction)
Sets the time.
public void
setTimeZone(int tzSign, int tzHour, int tzMinute)
Sets the time zone without changing the other time fields.
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).
public void
setYear(int year)
Sets the year.
public void
subtractGDuration(GDurationSpecification duration)
Subtracts a given duration from the date/time.
public GDate
toGDate()
Builds a GDate from this GDateBuilder.
public final String
toString()
The natural string representation.
 
Methods from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
   
Methods from interface com.bea.xml.GDateSpecification
canonicalString, compareToGDate, getBuiltinTypeCode, getCalendar, getDate, getDay, getFlags, getFraction, getHour, getJulianDate, getMillisecond, getMinute, getMonth, getSecond, getTimeZoneHour, getTimeZoneMinute, getTimeZoneSign, getYear, hasDate, hasDay, hasMonth, hasTime, hasTimeZone, hasYear, isImmutable, isValid, toString
 

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(int year, 
                    int month, 
                    int day, 
                    int hour, 
                    int minute, 
                    int second, 
                    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.


GDateBuilder

public GDateBuilder(int year, 
                    int month, 
                    int day, 
                    int hour, 
                    int minute, 
                    int second, 
                    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.


GDateBuilder

public GDateBuilder(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(Calendar calendar)

GDateBuilder

public GDateBuilder(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.

 

Method Detail

addDuration(int, int, int, int, int, int, int, BigDecimal) Method

public void addDuration(int sign, 
                        int year, 
                        int month, 
                        int day, 
                        int hour, 
                        int minute, 
                        int second, 
                        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)

addGDuration(GDurationSpecification) Method

public void addGDuration(GDurationSpecification duration)
Adds a given duration to the date/time.

Parameters

duration
the duration to add

canonicalString() Method

public 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.


clearDay() Method

public void clearDay()
Clears the day-of-month. After clearing. hasDay returns false and the value of getDay is undefined.


clearMonth() Method

public void clearMonth()
Clears the month-of-year. After clearing. hasMonth returns false and the value of getMonth is undefined.


clearTime() Method

public void clearTime()
Clears the time-of-day. After clearing. hasTime returns false and the value of getTime is undefined.


clearTimeZone() Method

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.


clearYear() Method

public void clearYear()
Clears the year. After clearing, hasYear returns false and the value of getYear is undefined.


clone() Method

public Object clone()
Builds another GDateBuilder with the same value as this one.

Overrides
Object.clone()

compareToGDate(GDateSpecification) Method

public final int compareToGDate(GDateSpecification datespec)
Comparison to another GDate. Two instances are incomparable if they have different amounts of information.

Parameters

datespec
the date to compare against

getBuiltinTypeCode() Method

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.


getCalendar() Method

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().


getDate() Method

public Date getDate()
Retrieves the value of the current time as a java.util.Date instance.


getDay() Method

public final int getDay()
Gets the day-of-month. The first day of each month is 1.


getFlags() Method

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.


getFraction() Method

public final BigDecimal getFraction()
Gets the fraction-of-second. Range from 0 (inclusive) to 1 (exclusive).


getHour() Method

public final int getHour()
Gets the hour-of-day. Midnight is 0, and 11PM is 23.


getJulianDate() Method

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 (= -4712 January 1).


getMillisecond() Method

public final int getMillisecond()
Gets the rounded millisecond value. Range from 0 to 999


getMinute() Method

public final int getMinute()
Gets the minute-of-hour. Range from 0 to 59.


getMonth() Method

public final int getMonth()
Gets the month-of-year. January is 1.


getSecond() Method

public final int getSecond()
Gets the second-of-minute. Range from 0 to 59.


getTimeZoneHour() Method

public final int getTimeZoneHour()
Gets the time zone hour. This is always positive: for the sign, look at getTimeZoneSign().


getTimeZoneMinute() Method

public final int getTimeZoneMinute()
Gets the time zone minutes. This is always positive: for the sign, look at getTimeZoneSign().


getTimeZoneSign() Method

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.


getYear() Method

public final int getYear()
Gets the year. Should be a four-digit year specification.


hasDate() Method

public final boolean hasDate()
True if this date/time specification specifies a full date (year, month, day)


hasDay() Method

public final boolean hasDay()
True if this date/time specification specifies a day-of-month.


hasMonth() Method

public final boolean hasMonth()
True if this date/time specification specifies a month-of-year.


hasTime() Method

public final boolean hasTime()
True if this date/time specification specifies a time-of-day.


hasTimeZone() Method

public final boolean hasTimeZone()
True if this date/time specification specifies a timezone.


hasYear() Method

public final boolean hasYear()
True if this date/time specification specifies a year.


isImmutable() Method

public boolean isImmutable()
True if the instance is immutable.


isValid() Method

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.


normalize() Method

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(int, int, int) Method

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(int) Method

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).


setBuiltinTypeCode(int) Method

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

setDate(Date) Method

public void setDate(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

setDay(int) Method

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

setGDate(GDateSpecification) Method

public void setGDate(GDateSpecification gdate)
Copies a GDateSpecification, completely replacing the current information in this GDateBuilder.

Parameters

gdate
the GDateSpecification to copy

setJulianDate(int) Method

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 (= -4712 January 1).

Parameters

julianday
the julian day number

setMonth(int) Method

public void setMonth(int month)
Sets the month-of-year. January is 1.

Parameters

month
the month, from 1-12

setTime(int, int, int, BigDecimal) Method

public void setTime(int hour, 
                    int minute, 
                    int second, 
                    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
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(int, int, int) Method

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(int) Method

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).


setYear(int) Method

public void setYear(int year)
Sets the year. Should be a four-digit year specification.

Parameters

year
the year

subtractGDuration(GDurationSpecification) Method

public void subtractGDuration(GDurationSpecification duration)
Subtracts a given duration from the date/time.

Parameters

duration
the duration to subtract

toGDate() Method

public GDate toGDate()
Builds a GDate from this GDateBuilder.


toString() Method

public final 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.

Overrides
Object.toString()