com.ibm.as400.access
Class AS400Time

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

public class AS400Time
extends AS400AbstractTime

Provides a converter between a java.sql.Time object and an IBM i time value such as "23:59:59" or "11:59 PM". In the IBM i programming reference, this type is referred to as the "Time Data Type", or DDS data type T.

An IBM i time value simply indicates an hour/minute/second within some (unspecified) 24-hour period, and does not indicate a contextual day, month, year, or time zone. Internally, this class interprets all date- and time-related strings as relative to the server's time zone.

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's time zone, and avoid using any deprecated methods. If it is necessary to convert date/time values between the server's 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 the server timezone. For example: import java.text.SimpleDateFormat; java.sql.Time time1; // value to be generated by AS400Time SimpleDateFormat formatter = new SimpleDateFormat("HH:mm:ss"); // Set the formatter's time zone to the server timezone. formatter.setTimeZone(as400.getTimeZone()); ... System.out.println("Time value: " + formatter.format(time1));

See Also:
AS400Timestamp, AS400Date, Serialized Form

Field Summary
static int FORMAT_EUR
          Format EUR: hh.mm.ss
Default separator: '.'
static int FORMAT_HMS
          Format HMS: hh:mm:ss
Default separator: ':'
static int FORMAT_ISO
          Format ISO: hh.mm.ss
Default separator: '.'
static int FORMAT_JIS
          Format JIS: hh:mm:ss
Default separator: ':'
static int FORMAT_USA
          Format USA: hh:mm AM or hh:mm PM
Default separator: ':'
Note: Unlike the other formats, this format has a granularity of minutes rather than seconds.
static Time MAX_VALUE
          The maximum value representable by this date type.
static Time MIN_VALUE
          The minimum value representable by this date type.
 
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
AS400Time()
          Constructs an AS400Time object.
AS400Time(int format)
          Constructs an AS400Time object.
AS400Time(int format, Character separator)
          Constructs an AS400Time object.
AS400Time(TimeZone timeZone)
          Constructs an AS400Time object.
AS400Time(TimeZone timeZone, int format)
          Constructs an AS400Time object.
AS400Time(TimeZone timeZone, int format, Character separator)
          Constructs an AS400Time object.
 
Method Summary
static int getByteLength(int format, Character separator)
          Returns the number of bytes occupied on the IBM i system by a field of this type.
 Object getDefaultValue()
          Returns a Java object representing the default value of the data type.
 int getFormat()
          Gets the format of this AS400Time object.
 int getInstanceType()
          Returns TYPE_TIME.
 Class getJavaType()
          Returns the Java class that corresponds with this data type.
 Character getSeparator()
          Gets the separator character of this AS400Time object.
 Time parse(String source)
          Converts a string representation of a time, to a Java object.
static Time parseXsdString(String source)
          Converts the specified HMS representation of a time, to a Java object.
static Time parseXsdString(String source, TimeZone timeZone)
          Converts the specified HMS representation of a time, to a Java object.
 void setFormat(int format)
          Sets the format of this AS400Time object.
 void setFormat(int format, char separator)
          Deprecated. Use setFormat(int,Character) instead.
 void setFormat(int format, Character separator)
          Sets the format of this AS400Time object.
 int toBytes(Object javaValue, byte[] as400Value, int offset)
          Converts the specified Java object into IBM i format in the specified byte array.
static int toFormat(String formatName)
          Returns the integer format value that corresponds to specified format name.
 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.
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.
static boolean validateFormat(int format)
          Validates the specified format value.
 
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

MIN_VALUE

public static final Time MIN_VALUE
The minimum value representable by this date type. This value represents the time 00:00:00.


MAX_VALUE

public static final Time MAX_VALUE
The maximum value representable by this date type. This value represents the time 23:59:59.999.


FORMAT_HMS

public static final int FORMAT_HMS
Format HMS: hh:mm:ss
Default separator: ':'

See Also:
Constant Field Values

FORMAT_ISO

public static final int FORMAT_ISO
Format ISO: hh.mm.ss
Default separator: '.'

See Also:
Constant Field Values

FORMAT_USA

public static final int FORMAT_USA
Format USA: hh:mm AM or hh:mm PM
Default separator: ':'
Note: Unlike the other formats, this format has a granularity of minutes rather than seconds.

See Also:
Constant Field Values

FORMAT_EUR

public static final int FORMAT_EUR
Format EUR: hh.mm.ss
Default separator: '.'

See Also:
Constant Field Values

FORMAT_JIS

public static final int FORMAT_JIS
Format JIS: hh:mm:ss
Default separator: ':'

See Also:
Constant Field Values
Constructor Detail

AS400Time

public AS400Time()
Constructs an AS400Time object. This uses the GMT time zone. The timezone is used when converting from a string to a "Time" object. The time object will use the timezone of the current JVM. Format FORMAT_ISO and separator '.' are used.


AS400Time

public AS400Time(TimeZone timeZone)
Constructs an AS400Time object. Format FORMAT_ISO and separator '.' are used.


AS400Time

public AS400Time(int format)
Constructs an AS400Time object. The specified format's default separator is used. The default GMT timezone is used

Parameters:
format - The format for this object. For a list of valid values, refer to AS400Time(int,Character).

AS400Time

public AS400Time(TimeZone timeZone,
                 int format)
Constructs an AS400Time object. The specified format's default separator is used.

Parameters:
format - The format for this object. For a list of valid values, refer to AS400Time(int,Character).

AS400Time

public AS400Time(int format,
                 Character separator)
Constructs an AS400Time object. The specified format's default separator is used. The default GMT time zone will be used.

Parameters:
format - The format for this object. Valid values are:
separator - The separator character. Valid values are:
  • ' ' (blank)
  • ':' (colon)
  • '.' (period)
  • ',' (comma)
  • '&' (ampersand)
  • (null)
A null value indicates "no separator". Refer to the IBM i programming reference to determine which separator characters are valid with each format.

AS400Time

public AS400Time(TimeZone timeZone,
                 int format,
                 Character separator)
Constructs an AS400Time object. The specified format's default separator is used.

Parameters:
format - The format for this object. Valid values are:
separator - The separator character. Valid values are:
  • ' ' (blank)
  • ':' (colon)
  • '.' (period)
  • ',' (comma)
  • '&' (ampersand)
  • (null)
A null value indicates "no separator". Refer to the IBM i programming reference to determine which separator characters are valid with each format.
Method Detail

getFormat

public int getFormat()
Gets the format of this AS400Time object.

Returns:
format The format for this object. For a list of possible values, refer to AS400Time(int,Character).

getSeparator

public Character getSeparator()
Gets the separator character of this AS400Time object.

Returns:
separator The separator character. For a list of possible values, refer to AS400Time(int,Character). If the format contains no separators, null is returned.
See Also:
setFormat(int,Character)

setFormat

public void setFormat(int format)
Sets the format of this AS400Time object. The specified format's default separator is used.

Parameters:
format - The format for this object. For a list of valid values, refer to AS400Time(int,Character).

setFormat

public void setFormat(int format,
                      Character separator)
Sets the format of this AS400Time object.

Parameters:
format - The format for this object. For a list of valid values, refer to AS400Time(int,Character).
separator - The separator character. For a list of valid values, refer to AS400Time(int,Character). A null value indicates "no separator". Refer to the IBM i programming reference to determine which separator characters are valid with each format.

setFormat

public void setFormat(int format,
                      char separator)
Deprecated. Use setFormat(int,Character) instead.

Sets the format of this AS400Time object.

Parameters:
format - The format for this object. For a list of valid values, refer to AS400Time(int,Character).
separator - The separator character.

toFormat

public static int toFormat(String formatName)
Returns the integer format value that corresponds to specified format name. If null is specified, the default format (FORMAT_ISO) is returned. This method is provided for use by the PCML infrastructure.

Parameters:
formatName - The format name. Valid values are:
  • HMS
  • ISO
  • USA
  • EUR
  • JIS
Returns:
the format value. For example, if formatName is "ISO", then FORMAT_ISO is returned.

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.Time object representing time 00:00:00 GMT (on January 1, 1970).

getInstanceType

public int getInstanceType()
Returns TYPE_TIME.

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

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.Time.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.Time. The range of valid values is MIN_VALUE through MAX_VALUE. Year, month, day-of-month, and fractional seconds are disregarded.
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:
Eight (8), 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.Time object, representing the number of milliseconds into the day. The reference time zone for the object is the timezone specified on the constructor.

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.Time, and must be within the range representable by this data type. Any timezone context is disregarded.
Returns:
A String representation of the specified value, formatted appropriately for this data type.

parse

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

Parameters:
source - A time value expressed as a string in the format specified for this AS400Time object.
Returns:
A java.sql.Time object representing the specified time. The reference timezone is the timezone specified for the object.

parseXsdString

public static Time parseXsdString(String source)
Converts the specified HMS representation of a time, to a Java object. This method is provided for use by the PCML infrastructure; in particular, when parsing 'init=' values for 'time' data elements. This method assumes that the reference timezone is GMT

Parameters:
source - A time value expressed as a string in format HH:mm:ss.
Returns:
A java.sql.Time object representing the specified time.

parseXsdString

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

Parameters:
source - A time value expressed as a string in format HH:mm:ss.
timeZone - The time zone used to interpret the value.
Returns:
A java.sql.Time object representing the specified time.

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 uses the GMT timezone.

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

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.Time, and must be within the range specifiable by this data type.
timeZone - The time zone used to interpret the value.
Returns:
The time expressed as a string in format HH:mm:ss.

validateFormat

public static boolean validateFormat(int format)
Validates the specified format value. This method is provided for use by the PCML infrastructure.

Parameters:
format - The format. For a list of valid values, refer to AS400Time(int,Character).
Returns:
true if the format is valid; false otherwise.

getByteLength

public static int getByteLength(int format,
                                Character separator)
Returns the number of bytes occupied on the IBM i system by a field of this type. This method is provided for use by the PCML infrastructure.

Parameters:
format - The format. This argument is ignored. For a list of valid values, refer to AS400Time(int,Character).
separator - The separator character. This argument is ignored. For a list of valid values, refer to AS400Time(int,Character).
Returns:
the number of bytes occupied.