com.ibm.as400.access
Class AS400Timestamp

java.lang.Object
  extended by com.ibm.as400.access.AS400AbstractTime
      extended by com.ibm.as400.access.AS400Timestamp
All Implemented Interfaces:
AS400DataType, Serializable, Cloneable

public class AS400Timestamp
extends AS400AbstractTime

Provides a converter between a java.sql.Timestamp object and an IBM i timestamp value such as "1997-12-31-23.59.59.999999". In the IBM i programming reference, this type is referred to as the "Timestamp Data Type", or DDS data type Z.

The minimum value for an IBM i timestamp is 0001-01-01-00.00.00.000000, and the maximum value is 9999-12-31-24.00.00.000000.

Note that java.sql.Timestamp values have nanoseconds precision, whereas IBM i timestamp values have only microseconds precision. When converting Timestamp values to IBM i timestamp values, fractional microseconds are rounded to the nearest microsecond.

An IBM i timestamp value simply indicates a year/month/day/hour/minute/second/microsecond, and does not indicate a contextual time zone. Internally, this class interprets all date- and time-related strings as relative to time zone of the AS400 system.

Suggestion: To avoid confusion and unexpected results when crossing time zones:
Whenever creating or interpreting instances of java.sql.Date, java.sql.Time, or java.sql.Timestamp, always assume that the reference time zone for the object is the server time zone, and avoid using any deprecated methods. If it is necessary to convert date/time values between the server time zone and other time zones, use methods of Calendar. Rather than using toString() to display the value of a date/time object, use DateFormat.format() after specifying a server time zone. For example: import java.text.SimpleDateFormat; java.sql.Timestamp timestamp1; // value to be generated by AS400Timestamp SimpleDateFormat formatter = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS"); // Set the formatter's time zone to the servers time zone formatter.setTimeZone(as400.getTimeZone()); ... System.out.println("Timestamp value: " + formatter.format(timestamp1));

See Also:
AS400Date, AS400Time, Serialized Form

Field Summary
static int FORMAT_DEFAULT
          The standard IBM i timestamp format.
 
Fields inherited from interface com.ibm.as400.access.AS400DataType
TYPE_ARRAY, TYPE_BIN1, TYPE_BIN2, TYPE_BIN4, TYPE_BIN8, TYPE_BYTE_ARRAY, TYPE_DATE, TYPE_DECFLOAT, TYPE_FLOAT4, TYPE_FLOAT8, TYPE_PACKED, TYPE_STRUCTURE, TYPE_TEXT, TYPE_TIME, TYPE_TIME_OF_DAY, TYPE_TIMESTAMP, TYPE_UBIN1, TYPE_UBIN2, TYPE_UBIN4, TYPE_UBIN8, TYPE_ZONED
 
Constructor Summary
AS400Timestamp()
          Constructs an AS400Timestamp object.
AS400Timestamp(TimeZone timeZone)
          Constructs an AS400Timestamp object.
 
Method Summary
 Object getDefaultValue()
          Returns a Java object representing the default value of the data type.
 int getInstanceType()
          Returns TYPE_TIMESTAMP.
 Class getJavaType()
          Returns the Java class that corresponds with this data type.
 Timestamp parse(String source)
          Converts a string representation of a timestamp, to a Java object.
static Timestamp parseXsdString(String source)
          Converts the specified ISO representation of a timestamp, to a Java object.
static Timestamp parseXsdString(String source, TimeZone timeZone)
          Converts the specified ISO representation of a timestamp, to a Java object.
 int toBytes(Object javaValue, byte[] as400Value, int offset)
          Converts the specified Java object into IBM i format in the specified byte array.
 Date toDate(Timestamp timestamp, TimeZone timezone)
          Creates a new java.util.Date object representing the Timestamp's nominal value, in the context of the specified time zone.
 Object toObject(byte[] as400Value, int offset)
          Converts the specified IBM i data type to a Java object.
 String toString(Object javaValue)
          Converts the specified Java object into a String representation that is consistent with the format of this data type.
 Timestamp toTimestamp(byte[] as400Value)
          Converts the specified IBM i data type to a Java object.
 Timestamp toTimestamp(byte[] as400Value, int offset)
          Converts the specified IBM i data type to a Java object.
static String toXsdString(Object javaValue)
          Converts the specified Java object into a String representation that is consistent with the format of this data type.
static String toXsdString(Object javaValue, TimeZone timeZone)
          Converts the specified Java object into a String representation that is consistent with the format of this data type.
 
Methods inherited from class com.ibm.as400.access.AS400AbstractTime
clone, getByteLength, getTimeZone, toBytes, toBytes, toObject
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

FORMAT_DEFAULT

public static final int FORMAT_DEFAULT
The standard IBM i timestamp format.

See Also:
Constant Field Values
Constructor Detail

AS400Timestamp

public AS400Timestamp()
Constructs an AS400Timestamp object. Assumes the timezone to be GTM.


AS400Timestamp

public AS400Timestamp(TimeZone timeZone)
Constructs an AS400Timestamp object.

Method Detail

getDefaultValue

public Object getDefaultValue()
Returns a Java object representing the default value of the data type.

Specified by:
getDefaultValue in interface AS400DataType
Specified by:
getDefaultValue in class AS400AbstractTime
Returns:
a java.sql.Timestamp object with a value of January 1, 1970, 00:00:00 GMT

getInstanceType

public int getInstanceType()
Returns TYPE_TIMESTAMP.

Specified by:
getInstanceType in interface AS400DataType
Specified by:
getInstanceType in class AS400AbstractTime
Returns:
AS400DataType.TYPE_TIMESTAMP.

getJavaType

public Class getJavaType()
Returns the Java class that corresponds with this data type.

Specified by:
getJavaType in interface AS400DataType
Specified by:
getJavaType in class AS400AbstractTime
Returns:
java.sql.Timestamp.class.

toBytes

public int toBytes(Object javaValue,
                   byte[] as400Value,
                   int offset)
Converts the specified Java object into IBM i format in the specified byte array.

Specified by:
toBytes in interface AS400DataType
Overrides:
toBytes in class AS400AbstractTime
Parameters:
javaValue - The object corresponding to the data type. It must be an instance of java.sql.Timestamp.
as400Value - The array to receive the data type in IBM i format. There must be enough space to hold the IBM i value.
offset - The offset into the byte array for the start of the IBM i value. It must be greater than or equal to zero.
Returns:
The number of bytes in the IBM i representation of the data type.

toObject

public Object toObject(byte[] as400Value,
                       int offset)
Converts the specified IBM i data type to a Java object.

Specified by:
toObject in interface AS400DataType
Specified by:
toObject in class AS400AbstractTime
Parameters:
as400Value - The array containing the data type in IBM i format. The entire data type must be represented.
offset - The offset into the byte array for the start of the IBM i value. It must be greater than or equal to zero.
Returns:
a java.sql.Timestamp object corresponding to the data type. The reference time zone for the object is GMT.

toTimestamp

public Timestamp toTimestamp(byte[] as400Value)
Converts the specified IBM i data type to a Java object. This method is simply a convenience front-end to the toObject(byte[]) method.

Parameters:
as400Value - The array containing the data type in IBM i format. The entire data type must be represented.
Returns:
a java.sql.Timestamp object corresponding to the data type. The reference time zone for the object is GMT.

toTimestamp

public Timestamp toTimestamp(byte[] as400Value,
                             int offset)
Converts the specified IBM i data type to a Java object. This method is simply a convenience front-end to the toObject(byte[],int) method.

Parameters:
as400Value - The array containing the data type in IBM i format. The entire data type must be represented.
offset - The offset into the byte array for the start of the IBM i value. It must be greater than or equal to zero.
Returns:
a java.sql.Timestamp object corresponding to the data type. The reference time zone for the object is GMT.

toDate

public Date toDate(Timestamp timestamp,
                   TimeZone timezone)
Creates a new java.util.Date object representing the Timestamp's nominal value, in the context of the specified time zone. That is, the timestamp is re-interpreted as if its reference context were the specified time zone. This assume that the current timestamp is represented in GMT.

For example, if timestamp represents "2000-01-01-00.00.00.000000 GMT", and timezone specifies CST, then this method will return a java.util.Date object representing "2000-01-01-00.00.00.000000 CST".

Note that java.util.Date has milliseconds precision, whereas java.sql.Timestamp has nanoseconds precision. When converting from Timestamp to Date, nanoseconds are rounded to the nearest millisecond.

Parameters:
timestamp - The timestamp object.
timezone - The desired reference time zone to assign to the returned Date object.
Returns:
A Date object representing the same nominal timestamp value as represented by timestamp, with time zone context timezone.

toString

public String toString(Object javaValue)
Converts the specified Java object into a String representation that is consistent with the format of this data type.

Specified by:
toString in class AS400AbstractTime
Parameters:
javaValue - The object corresponding to the data type. This must be an instance of java.sql.Timestamp, and must be within the range specifiable by this data type.
Returns:
A String representation of the specified value, formatted appropriately for this data type.
Throws:
ExtendedIllegalArgumentException - if the specified date is outside of the range representable by this data type.

parse

public Timestamp parse(String source)
Converts a string representation of a timestamp, to a Java object.

Parameters:
source - A timestamp value expressed as a string in standard IBM i timestamp format.
Returns:
A java.sql.Timestamp object representing the specified timestamp. The reference time zone for the object is GMT.

parseXsdString

public static Timestamp parseXsdString(String source)
Converts the specified ISO representation of a timestamp, to a Java object. This method is provided for use by the PCML infrastructure. in particular, when parsing 'init=' values for 'timestamp' data elements. The timezone used by this method is GMT.

Parameters:
source - A timestamp value expressed as a string in format yyyy-MM-ddTHH:mm:ss.SSSSSSSSS. For example: 2010-01-01T23:59:59.999999999
Returns:
A java.sql.Timestamp object representing the specified timestamp.

parseXsdString

public static Timestamp parseXsdString(String source,
                                       TimeZone timeZone)
Converts the specified ISO representation of a timestamp, to a Java object. This method is provided for use by the PCML infrastructure. in particular, when parsing 'init=' values for 'timestamp' data elements.

Parameters:
source - A timestamp value expressed as a string in format yyyy-MM-ddTHH:mm:ss.SSSSSSSSS. For example: 2010-01-01T23:59:59.999999999
timeZone - time zone to used for the conversion.
Returns:
A java.sql.Timestamp object representing the specified timestamp.

toXsdString

public static String toXsdString(Object javaValue)
Converts the specified Java object into a String representation that is consistent with the format of this data type. This method is provided for use by the PCML infrastructure. This version assumes the GMT timezone.

Parameters:
javaValue - The object corresponding to the data type. This must be an instance of java.sql.Timestamp, and must be within the range specifiable by this data type.
Returns:
The timestamp expressed as a string in format yyyy-MM-ddTHH:mm:ss.SSSSSSSSS.

toXsdString

public static String toXsdString(Object javaValue,
                                 TimeZone timeZone)
Converts the specified Java object into a String representation that is consistent with the format of this data type. This method is provided for use by the PCML infrastructure.

Parameters:
javaValue - The object corresponding to the data type. This must be an instance of java.sql.Timestamp, and must be within the range specifiable by this data type.
timeZone - Time zone used to interpret the value.
Returns:
The timestamp expressed as a string in format yyyy-MM-ddTHH:mm:ss.SSSSSSSSS.