com.davisor.data
Class DateFormatType

java.lang.Object
  java.text.Format
      com.davisor.data.Type
          com.davisor.data.LocaleType
              com.davisor.data.FormatType
                  com.davisor.data.DateFormatType

All Implemented Interfaces:

java.lang.Cloneable, java.util.Comparator, com.davisor.core.Dupable, java.io.Serializable

Direct Known Subclasses:

CalendarFieldType, TimestampType

public abstract class DateFormatType

extends FormatType

DateFormatType implements a base class for time related types. Date formats are specified by date locale, pattern, style, and time zone. An unspecified locale suggests SQL date formatting rules.

Date format locale is inherited from the LocaleType super-class. The format pattern is handled by the Java java.text.SimpleDateFormat class. The format style equals one of the Java java.text.DateFormat style codes:

• SHORT
• MEDIUM
• LONG
• FULL
• DEFAULT

The default time zone is assumed to be GMT (instead of e.g. system default). This makes time arithmetics more robust. It works well also in the typical cases where the data time zone and chart axis time zone are the same.

Format syntax

DateType format defines the syntax in which a date type instance reads and writes date and time strings. A short, inaccurate and only informal date format syntax summary would be:

 format := locale
           style|pattern ";" locale
           timeZone ";" style|pattern ";" locale

 locale   := language [ "_" country [ "_" variant ]]

 style    := "default" | "full" | "long" | "medium" | "short"
 pattern  := [prefix] { dateComponent } [suffix]

 timeZone := [ "+"|"-" ] offset
 

A dateComponent is a time and date field pattern letter as understood by the java.text.SimpleDateFormat class:

Letter	Date or Time Component	Presentation	Examples
G	Era designator	Text	AD
y	Year	Year	1996; 96
M	Month in year	Month	July; Jul; 07
w	Week in year	Number	27
W	Week in month	Number	2
D	Day in year	Number	189
d	Day in month	Number	10
F	Day of week in month	Number	2
E	Day in week	Text	Tuesday; Tue
a	Am/pm marker	Text	PM
H	Hour in day (0-23)	Number	0
k	Hour in day (1-24)	Number	24
K	Hour in am/pm (0-11)	Number	0
h	Hour in am/pm (1-12)	Number	12
m	Minute in hour	Number	30
s	Second in minute	Number	55
S	Millisecond	Number	978
z	Time zone	General time zone	Pacific Standard Time; PST; GMT-08:00
Z	Time zone	RFC 822 time zone	-0800

The number of pattern letters determines the exact presentation:

• Text: For formatting, if the number of pattern letters is 4 or more, the full form is used; otherwise a short or abbreviated form is used if available. For parsing, both forms are accepted, independent of the number of pattern letters.
• Number: For formatting, the number of pattern letters is the minimum number of digits, and shorter numbers are zero-padded to this amount. For parsing, the number of pattern letters is ignored unless it's needed to separate two adjacent fields.
• Year: For formatting, if the number of pattern letters is 2, the year is truncated to 2 digits; otherwise it is interpreted as a number. For parsing, if the number of pattern letters is more than 2, the year is interpreted literally, regardless of the number of digits.
• Month: If the number of pattern letters is 3 or more, the month is interpreted as text; otherwise, it is interpreted as a number.

Please see official java.text.SimpleDateFormat documentation for more complete documentation.

Since:

JDK1.1

See Also:

createCalendar(Date,TimeZone,Locale), DateType, TimestampType, Serialized Form

Nested Class Summary

Nested classes inherited from class java.text.Format

java.text.Format.Field

Field Summary

static java.util.TimeZone	GMT Greenwich Mean Time zone (GMT +0:00).
static java.util.TimeZone	LOCAL System default time zone, typically representing the local time zone.
protected int	M_style Date format style.
protected java.util.TimeZone	M_timeZone Date time zone.

Fields inherited from class com.davisor.data.FormatType

M_pattern, M_sample

Fields inherited from class com.davisor.data.LocaleType

DEFAULT_LOCALE, M_locale

Fields inherited from class com.davisor.data.Type

METADATA_GROUP, METADATA_NAME, METADATA_PARENT, METADATA_SUBCHANNELS, TYPENAME

Constructor Summary

protected	DateFormatType(DateFormatType dft) Deep copy constructor.
protected	DateFormatType(java.lang.String typeName, java.lang.String dataName, java.lang.String id, java.util.Map metaData, java.util.Locale locale, java.lang.String pattern, java.lang.Object sample, int style, java.util.TimeZone timeZone) Creates a new date format type.

Method Summary

java.util.Calendar	createCalendar() Creates a new calendar for the current locale and timezone, not set to any particular date.
static java.util.Calendar	createCalendar(CalendarField field) Creates a new calendar for the current locale and GMT time zone, set to zero date (January 1, 1970, 00:00:00 GMT) plus given field value.
static java.util.Calendar	createCalendar(CalendarField field1, CalendarField field2) Creates a new calendar for the current locale and GMT time zone, set to zero date (January 1, 1970, 00:00:00 GMT) plus given field values.
java.util.Calendar	createCalendar(java.util.Date date) Creates a new calendar for the current locale and time zone, set to given date.
java.util.Calendar	createCalendar(java.util.Date date, java.util.TimeZone timeZone) Creates a new calendar for the current locale and given time zone, set to a given date.
static java.util.Calendar	createCalendar(java.util.Date date, java.util.TimeZone timeZone, java.util.Locale locale) Creates a new calendar for the given locale and time zone, set to a given date.
protected java.text.Format	createFormatter() Creates a new format instance suitable for the purposes of this class.
java.util.Date	dateValue(java.lang.String stringValue, java.text.ParsePosition status) Parses a timestamp string as a timestamp.
boolean	equals(java.lang.Object o) Tests if this object is equal with another object.
java.lang.String	getFormat() Gets the date format specification string.
CalendarFieldData	getLast(DataValue dataValue) Gets the most significant calendar field value from given time-oriented data value.
int	getStyle() Gets the current date format style.
java.util.TimeZone	getTimeZone() Gets the current date format time zone.
java.lang.Class	getValueClass() Gets value container class.
int	hashCode() Returns a hash code value for the object.
void	setFormat(java.lang.String format) Sets the localization specification string.
void	setStyle(int style) Sets the current date format style.
void	setTimeZone(java.util.TimeZone timeZone) Sets the current date format time zone.
java.lang.String	stringValue(java.util.Date value) Formats a timestamp as a timestamp string.
void	strip(java.util.Calendar calendar) Clears selected calendar fields to make the calendar value consistent with current type.
DataValue	toData(java.util.Date date) Converts a date to a date value of a type best suited to represent it.
DataValue	toData(long milliseconds) Converts a milliseconds value to a date value of a type best suited to represent it.
DataValue	toData(java.lang.Object objectValue) Converts an object to a data value.
DataValue	toData(java.lang.String stringValue, java.text.ParsePosition status) Converts a string to a data value.

Methods inherited from class com.davisor.data.FormatType

clearFormatter, getFormatter, getPattern, getSample, setFormat, setLocale, setPattern, setSample

Methods inherited from class com.davisor.data.LocaleType

getLocale, setLocale

Methods inherited from class com.davisor.data.Type

ceil, check, check, compare, create, create, create, create, create, dup, dup, floor, format, getCompatibility, getDataName, getId, getID, getMetaData, getMetaData, getSpecs, getSQLCode, getSQLName, getSQLName, getTypeName, isNull, parseObject, register, register, setDataName, setId, setID, setMetaData, setMetaData, setSpecs, toData, toData, toString, toXML, xmlEnd, xmlStart, zero

Methods inherited from class java.text.Format

clone, format, formatToCharacterIterator, parseObject

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

GMT

public static final java.util.TimeZone GMT

Greenwich Mean Time zone (GMT +0:00).

LOCAL

public static final java.util.TimeZone LOCAL

System default time zone, typically representing the local time zone.

M_style

protected int M_style

Date format style.

M_timeZone

protected java.util.TimeZone M_timeZone

Date time zone.

Constructor Detail

DateFormatType

protected DateFormatType(DateFormatType dft)

Deep copy constructor.

DateFormatType

protected DateFormatType(java.lang.String typeName,
                         java.lang.String dataName,
                         java.lang.String id,
                         java.util.Map metaData,
                         java.util.Locale locale,
                         java.lang.String pattern,
                         java.lang.Object sample,
                         int style,
                         java.util.TimeZone timeZone)

Creates a new date format type.

Parameters:

typeName - type name

dataName - data name (may be null)

id - type identity (may be null)

metaData - type meta data map (may be null)

locale - type locale (may be null)

pattern - format pattern (may be null)

sample - format sample (may be null)

style - date format style as defined by DateFormat class

timeZone - date format time zone

Method Detail

createFormatter

protected java.text.Format createFormatter()

Creates a new format instance suitable for the purposes of this class.

This particular implementation returns a date-time instance. Current pattern is applied to it only if it is also a SimpleDateFormat instance. The format time zone is set as returned by getTimeZone().

Specified by:

createFormatter in class FormatType

See Also:

DateType.createFormatter(), TimeType.createFormatter()

equals

public boolean equals(java.lang.Object o)

Tests if this object is equal with another object.

Date format types are equal if their super-classes and styles are.

Specified by:

equals in interface java.util.Comparator

Overrides:

equals in class FormatType

See Also:

FormatType.equals(java.lang.Object)

hashCode

public int hashCode()

Returns a hash code value for the object.

Overrides:

hashCode in class FormatType

See Also:

Compare.hashCode(java.lang.Object)

createCalendar

public java.util.Calendar createCalendar()

Creates a new calendar for the current locale and timezone, not set to any particular date.

See Also:

createCalendar(Date), createCalendar(Date,TimeZone), createCalendar(Date,TimeZone,Locale), createCalendar(CalendarField), createCalendar(CalendarField,CalendarField)

createCalendar

public java.util.Calendar createCalendar(java.util.Date date)

Creates a new calendar for the current locale and time zone, set to given date.

See Also:

createCalendar(), createCalendar(Date,TimeZone), createCalendar(Date,TimeZone,Locale), createCalendar(CalendarField), createCalendar(CalendarField,CalendarField)

createCalendar

public java.util.Calendar createCalendar(java.util.Date date,
                                         java.util.TimeZone timeZone)

Creates a new calendar for the current locale and given time zone, set to a given date.

Parameters:

date - calendar initial date (may be null)

timeZone - calendar time zone (may be null)

See Also:

createCalendar(), createCalendar(Date), createCalendar(Date,TimeZone,Locale), createCalendar(CalendarField), createCalendar(CalendarField,CalendarField), LocaleType.getLocale()

createCalendar

public static java.util.Calendar createCalendar(java.util.Date date,
                                                java.util.TimeZone timeZone,
                                                java.util.Locale locale)

Creates a new calendar for the given locale and time zone, set to a given date. If the given locale is null, the system default locale is used. If the given time zone is null, the default GMT time zone is used. If the given date is null, a null calendar is returned.

Parameters:

date - calendar initial date (may be null)

timeZone - calendar time zone (may be null)

locale - calendar locale (may be null)

See Also:

createCalendar(), createCalendar(Date), createCalendar(Date,TimeZone), createCalendar(CalendarField), createCalendar(CalendarField,CalendarField)

createCalendar

public static java.util.Calendar createCalendar(CalendarField field)

Creates a new calendar for the current locale and GMT time zone, set to zero date (January 1, 1970, 00:00:00 GMT) plus given field value.

Parameters:

field - calendar field code

See Also:

createCalendar(), createCalendar(Date), createCalendar(Date,TimeZone), createCalendar(Date,TimeZone,Locale), createCalendar(CalendarField,CalendarField)

createCalendar

public static java.util.Calendar createCalendar(CalendarField field1,
                                                CalendarField field2)

Creates a new calendar for the current locale and GMT time zone, set to zero date (January 1, 1970, 00:00:00 GMT) plus given field values.

Parameters:

field1 - first calendar field

field2 - second calendar field

See Also:

createCalendar(), createCalendar(Date), createCalendar(Date,TimeZone), createCalendar(Date,TimeZone,Locale), createCalendar(CalendarField)

dateValue

public java.util.Date dateValue(java.lang.String stringValue,
                                java.text.ParsePosition status)
                         throws InvalidDataException

Parses a timestamp string as a timestamp. The string is expected to contain a timestamp string, formatted as the current format settings dictate.

Parameters:

stringValue - timestamp string

status - parse status (may be null)

Returns:

Date object corresponding 'value'.

Throws:

InvalidDataException - 'value' is invalid as a timestamp string

See Also:

FormatType.getFormatter()

getLast

public CalendarFieldData getLast(DataValue dataValue)
                          throws InvalidDataException

Gets the most significant calendar field value from given time-oriented data value. Supported data value types are:

• CalendarData
• CalendarFieldData
• TimestampData
• java.util.Date

Parameters:

dataValue - value to get the most significant time field value from

Returns:

the most significant time field value

Throws:

InvaliDataException - if given data value type is not supported

InvalidDataException

getStyle

public int getStyle()

Gets the current date format style.

See Also:

setStyle(int)

getTimeZone

public java.util.TimeZone getTimeZone()

Gets the current date format time zone. If no time zone has been defined, the default GMT time zone is returned.

See Also:

setTimeZone(java.util.TimeZone)

setStyle

public void setStyle(int style)

Sets the current date format style.

See Also:

getStyle()

setTimeZone

public void setTimeZone(java.util.TimeZone timeZone)

Sets the current date format time zone. A null time zone indicates the default GMT time zone.

See Also:

getTimeZone()

stringValue

public java.lang.String stringValue(java.util.Date value)

Formats a timestamp as a timestamp string.

Parameters:

value - timestamp value (may be null)

Returns:

String representation of 'value', formatted according to the current timestamp format. If the value is null or the time of value is TimestampData.NaT, the return value is an empty string.

See Also:

FormatType.getFormatter(), setFormat(java.lang.String)

strip

public void strip(java.util.Calendar calendar)

Clears selected calendar fields to make the calendar value consistent with current type.

This default implementation does not clear any fields.

Parameters:

calendar - calendar to be stripped (will be modified)

toData

public DataValue toData(long milliseconds)

Converts a milliseconds value to a date value of a type best suited to represent it.

Parameters:

milliseconds - milliseconds value

See Also:

toData(Date)

toData

public DataValue toData(java.util.Date date)

Converts a date to a date value of a type best suited to represent it.

If the date represents a date only, a DateData data object is returned. If the date represents time only, a TimeData data object is returned. Otherwise, a TimestampData object is returned.

If the date is null, or the value of the date is TimestampData.NaT, a new TimestampData object with a TimestampData.NaT value is returned.

Parameters:

date - date value (may be null)

See Also:

strip(java.util.Calendar), CalendarFields.isDate(), CalendarFields.isTime(), CalendarFields.isTimestamp()

getFormat

public java.lang.String getFormat()

Gets the date format specification string. The string is composed of a time zone raw offset value, a Java format style keyword or pattern, and a locale specification string, all separated by a ; characters.

Overrides:

getFormat in class FormatType

See Also:

setFormat(java.lang.String)

setFormat

public void setFormat(java.lang.String format)

Sets the localization specification string. The string is expected to be composed of a time zone raw offset value, a Java date format style keyword or pattern, and a locale specification string, all separated by ; characters. Any component may also be missing.

The time zone, if present, is expressed as a integer value that tells the time difference in hours to Greenwhich Mean Time. If time zone is not set, the default GMT time zone is assumed.

A style keyword, if present, must be one of the following:

• default - corresponds to DateFormat.DEFAULT
• full - corresponds to DateFormat.FULL
• long - corresponds to DateFormat.LONG
• medium - corresponds to DateFormat.MEDIUM
• short - corresponds to DateFormat.SHORT

Java date format pattern, if present, must conform to the pattern rules set by standard SimpleDateFormat, except that the pattern must not contain the ; characters.

Style keyword and date pattern are mutually exclusive settings, and they must not appear together. If both are missing, SQL date format will be used.

Locale, if present, is expressed as a language, country, and variant triplets, as understood by the LocaleParser class. If locale setting is missing, system default locale will be used.

Examples

• en - English language locale with SQL date formatting
• en_US - US english language locale
• long;en_US - US english locale with long date format
• +4;long;en_US - US english locale with long date format in GTM +4:00 time zone
• -4;yyyy - system default locale with 'yyyy' date pattern in GTM -4:00 time zone
• 2 - system default locale with SQL date pattern in GTM +2:00 time zone

Overrides:

setFormat in class FormatType

Parameters:

format - type specification string as described above (may be null)

See Also:

getFormat(), FormatType.getFormatter(), getStyle(), LocaleParser, LocaleType.setFormat(java.lang.String)

getValueClass

public java.lang.Class getValueClass()

Gets value container class.

Overrides:

getValueClass in class FormatType

toData

public DataValue toData(java.lang.Object objectValue)
                 throws InvalidDataException

Converts an object to a data value.

The following object types are converted directly, others are converted first to strings, then to time values.

• CalendarData - converted to a new CalendarData object
• CalendarFieldData - converted to a new CalendarFieldData object
• Calendar - converted to a new CalendarData object
• Date - converted to a date object best suited to represent the value

Overrides:

toData in class Type

Parameters:

objectValue - data object

Returns:

a data value object corresponding to given object value

Throws:

InvalidDataException - if given object value could not be parsed

See Also:

toData(String,ParsePosition), toData(java.util.Date), CalendarData, CalendarFieldData, DateData, TimeData, TimestampData

toData

public DataValue toData(java.lang.String stringValue,
                        java.text.ParsePosition status)
                 throws InvalidDataException

Converts a string to a data value.

Timestamp type expects the given value to contain a timestamp string compatible with current timestamp pattern, and returns a corresponding TimestampData value.

Specified by:

toData in class Type

Parameters:

stringValue - data string

status - parse status (may be null)

Returns:

a data value object corresponding given string value

Throws:

InvalidDataException - if given string value could not be parsed

See Also:

dateValue(String,ParsePosition), toData(java.util.Date), toData(Object), TimestampData