ca.uhn.hl7v2.model.primitive

Class CommonTS

java.lang.Object

ca.uhn.hl7v2.model.primitive.CommonTS

All Implemented Interfaces:

Serializable

public class CommonTS
extends Object
implements Serializable

This class contains functionality used by the TS class in the version 2.3.0, 2.3.1, and 2.4 packages

Note: The class description below has been excerpted from the Hl7 2.4 documentation. Sectional references made below also refer to the same documentation.

Format: YYYY[MM[DD[HHMM[SS[.S[S[S[S]]]]]]]][+/-ZZZZ]^

Contains the exact time of an event, including the date and time. The date portion of a time stamp follows the rules of a date field and the time portion follows the rules of a time field. The time zone (+/-ZZZZ) is represented as +/-HHMM offset from UTC (formerly Greenwich Mean Time (GMT)), where +0000 or -0000 both represent UTC (without offset). The specific data representations used in the HL7 encoding rules are compatible with ISO 8824-1987(E). In prior versions of HL7, an optional second component indicates the degree of precision of the time stamp (Y = year, L = month, D = day, H = hour, M = minute, S = second). This optional second component is retained only for purposes of backward compatibility.

By site-specific agreement, YYYYMMDD[HHMM[SS[.S[S[S[S]]]]]][+/-ZZZZ]^ may be used where backward compatibility must be maintained. In the current and future versions of HL7, the precision is indicated by limiting the number of digits used, unless the optional second component is present. Thus, YYYY is used to specify a precision of "year," YYYYMM specifies a precision of "month," YYYYMMDD specifies a precision of "day," YYYYMMDDHH is used to specify a precision of "hour," YYYYMMDDHHMM is used to specify a precision of "minute," YYYYMMDDHHMMSS is used to specify a precision of seconds, and YYYYMMDDHHMMSS.SSSS is used to specify a precision of ten thousandths of a second. In each of these cases, the time zone is an optional component. Note that if the time zone is not included, the timezone defaults to that of the local time zone of the sender. Also note that a TS valued field with the HHMM part set to "0000" represents midnight of the night extending from the previous day to the day given by the YYYYMMDD part (see example below). Maximum length of the time stamp is 26.

Examples:
|19760704010159-0500|
1:01:59 on July 4, 1976 in the Eastern Standard Time zone (USA).
|19760704010159-0400|
1:01:59 on July 4, 1976 in the Eastern Daylight Saving Time zone (USA).
|198807050000|
Midnight of the night extending from July 4 to July 5, 1988 in the local time zone of the sender.
|19880705|
Same as prior example, but precision extends only to the day. Could be used for a birthdate, if the time of birth is unknown.
|19981004010159+0100|
1:01:59 on October 4, 1998 in Amsterdam, NL. (Time zone=+0100).

The HL7 Standard strongly recommends that all systems routinely send the time zone offset but does not require it. All HL7 systems are required to accept the time zone offset, but its implementation is application specific. For many applications the time of interest is the local time of the sender. For example, an application in the Eastern Standard Time zone receiving notification of an admission that takes place at 11:00 PM in San Francisco on December 11 would prefer to treat the admission as having occurred on December 11 rather than advancing the date to December 12.

Note: The time zone [+/-ZZZZ], when used, is restricted to legally-defined time zones and is represented in HHMM format.

One exception to this rule would be a clinical system that processed patient data collected in a clinic and a nearby hospital that happens to be in a different time zone. Such applications may choose to convert the data to a common representation. Similar concerns apply to the transitions to and from daylight saving time. HL7 supports such requirements by requiring that the time zone information be present when the information is sent. It does not, however, specify which of the treatments discussed here will be applied by the receiving system.

Author:

Neal Acharya

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
CommonTS() Creates new ValidTS zero argument constructor.
CommonTS(String val) Constructs a TS object with the given value.

Method Summary

Methods

Modifier and Type	Method and Description
int	getDay() Returns the day as an integer.
float	getFractSecond() Returns the fractional second value as a float.
int	getGMTOffset() Returns the GMT offset value as an integer.
int	getHour() Returns the hour as an integer.
int	getMinute() Returns the minute as an integer.
int	getMonth() Returns the month as an integer.
int	getSecond() Returns the second as an integer.
String	getValue() Returns the HL7 TS string value.
Calendar	getValueAsCalendar() Return the value as a calendar object.
Date	getValueAsDate() Return the value as a date objectIf the value is null (e.g.
int	getYear() Returns the year as an integer.
static void	main(String[] args)
void	setDateMinutePrecision(int yr, int mnth, int dy, int hr, int min) This method takes in integer values for the year, month, day, hour and minute and performs validations, it then sets the value in the object formatted as an HL7 Time Stamp value with year&month&day&hour&minute precision (YYYYMMDDHHMM).
void	setDatePrecision(int yr, int mnth, int dy) This method takes in integer values for the year and month and day and performs validations, it then sets the value in the object formatted as an HL7 Time Stamp value with year&month&day precision (YYYYMMDD).
void	setDateSecondPrecision(int yr, int mnth, int dy, int hr, int min, float sec) This method takes in integer values for the year, month, day, hour, minute, seconds, and fractional seconds (going to the tenthousandths precision).
void	setOffset(int signedOffset) This method takes in the four digit (signed) GMT offset and sets the offset field
void	setValue(Calendar theCalendar) Convenience setter which sets the value using a Calendar object.
void	setValue(Date theDate) Convenience setter which sets the value using a Calendar object.
void	setValue(String val) This method takes in a string HL7 Time Stamp value and performs validations.
void	setValueToMinute(Calendar theCalendar) Convenience setter which sets the value using a Calendar object.
void	setValueToMinute(Date theDate) Convenience setter which sets the value using a Date object.
void	setValueToSecond(Calendar theCalendar) Convenience setter which sets the value using a Calendar object.
void	setValueToSecond(Date theDate) Convenience setter which sets the value using a Date object.
static String	toHl7TSFormat(GregorianCalendar cal) Returns a string value representing the input Gregorian Calendar object in an Hl7 TimeStamp Format.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CommonTS

public CommonTS()

Creates new ValidTS zero argument constructor. Creates an uninitailized TS datatype

CommonTS

public CommonTS(String val)
         throws DataTypeException

Constructs a TS object with the given value. The stored value will be in the following format YYYY[MM[DD[HHMM[SS[.S[S[S[S]]]]]]]][+/-ZZZZ]

Throws:

DataTypeException

Method Detail

getDay

public int getDay()

Returns the day as an integer.

getFractSecond

public float getFractSecond()

Returns the fractional second value as a float.

getGMTOffset

public int getGMTOffset()

Returns the GMT offset value as an integer.

getHour

public int getHour()

Returns the hour as an integer.

getMinute

public int getMinute()

Returns the minute as an integer.

getMonth

public int getMonth()

Returns the month as an integer.

getSecond

public int getSecond()

Returns the second as an integer.

getValue

public String getValue()

Returns the HL7 TS string value.

getValueAsCalendar

public Calendar getValueAsCalendar()

Return the value as a calendar object. If the value is null (e.g. no value has been set), returns null

Since:

1.1

getValueAsDate

public Date getValueAsDate()

Return the value as a date objectIf the value is null (e.g. no value has been set), returns null

Since:

1.1

getYear

public int getYear()

Returns the year as an integer.

setDateMinutePrecision

public void setDateMinutePrecision(int yr,
                          int mnth,
                          int dy,
                          int hr,
                          int min)
                            throws DataTypeException

This method takes in integer values for the year, month, day, hour and minute and performs validations, it then sets the value in the object formatted as an HL7 Time Stamp value with year&month&day&hour&minute precision (YYYYMMDDHHMM).

Throws:

DataTypeException

setDatePrecision

public void setDatePrecision(int yr,
                    int mnth,
                    int dy)
                      throws DataTypeException

This method takes in integer values for the year and month and day and performs validations, it then sets the value in the object formatted as an HL7 Time Stamp value with year&month&day precision (YYYYMMDD).

Throws:

DataTypeException

setDateSecondPrecision

public void setDateSecondPrecision(int yr,
                          int mnth,
                          int dy,
                          int hr,
                          int min,
                          float sec)
                            throws DataTypeException

This method takes in integer values for the year, month, day, hour, minute, seconds, and fractional seconds (going to the tenthousandths precision). The method performs validations and then sets the value in the object formatted as an HL7 time value with a precision that starts from the year and goes down to the tenthousandths of a second (YYYYMMDDHHMMSS.SSSS). The Gmt Offset will not be effected. Note: all of the precisions from tenths down to tenthousandths of a second are optional. If the precision goes below tenthousandths of a second then the second value will be rounded to the nearest tenthousandths of a second.

Throws:

DataTypeException

setOffset

public void setOffset(int signedOffset)
               throws DataTypeException

This method takes in the four digit (signed) GMT offset and sets the offset field

Throws:

DataTypeException

setValue

public void setValue(Calendar theCalendar)
              throws DataTypeException

Convenience setter which sets the value using a Calendar object. Passing in null clears any existing value. Note: Sets fields using precision up to the millisecond, including timezone offset

Parameters:

theCalendar - The calendar object from which to retrieve values

Throws:

DataTypeException

Since:

1.1

setValue

public void setValue(Date theDate)
              throws DataTypeException

Convenience setter which sets the value using a Calendar object. Passing in null clears any existing value. Note: Sets fields using precision up to the millisecond, and sets the timezone offset to the current system offset

Parameters:

theDate - The calendar object from which to retrieve values

Throws:

DataTypeException

Since:

1.1

setValue

public void setValue(String val)
              throws DataTypeException

This method takes in a string HL7 Time Stamp value and performs validations. The stored value will be in the following format YYYY[MM[DD[HHMM[SS[.S[S[S[S]]]]]]]][+/-ZZZZ]. Note: Trailing zeros supplied in the time value (HHMM[SS[.S[S[S[S]]]]]]) and GMT offset ([+/-ZZZZ]) will be preserved. Note: If the GMT offset is not supplied then the local time zone (using standard time zone format which is not modified for daylight savings) will be stored as a default. Passing in null clears any existing value.

Throws:

DataTypeException

setValueToMinute

public void setValueToMinute(Calendar theCalendar)
                      throws DataTypeException

Convenience setter which sets the value using a Calendar object. Passing in null clears any existing value. Note: Sets fields using precision up to the minute

Parameters:

theCalendar - The calendar object from which to retrieve values

Throws:

DataTypeException

Since:

1.1

setValueToMinute

public void setValueToMinute(Date theDate)
                      throws DataTypeException

Convenience setter which sets the value using a Date object. Passing in null clears any existing value. Note: Sets fields using precision up to the minute

Parameters:

theCalendar - The calendar object from which to retrieve values

Throws:

DataTypeException

Since:

1.1

setValueToSecond

public void setValueToSecond(Calendar theCalendar)
                      throws DataTypeException

Convenience setter which sets the value using a Calendar object. Passing in null clears any existing value. Note: Sets fields using precision up to the second

Parameters:

theCalendar - The calendar object from which to retrieve values

Throws:

DataTypeException

Since:

1.1

setValueToSecond

public void setValueToSecond(Date theDate)
                      throws DataTypeException

Convenience setter which sets the value using a Date object. Passing in null clears any existing value. Note: Sets fields using precision up to the second

Parameters:

theCalendar - The calendar object from which to retrieve values

Throws:

DataTypeException

Since:

1.1

toHl7TSFormat

public static String toHl7TSFormat(GregorianCalendar cal)
                            throws DataTypeException

Returns a string value representing the input Gregorian Calendar object in an Hl7 TimeStamp Format.

Throws:

DataTypeException

main

public static void main(String[] args)
                 throws DataTypeException

Throws:

DataTypeException