com.ibm.as400.access

Class AS400Date

  • All Implemented Interfaces:
    AS400DataType, java.io.Serializable, java.lang.Cloneable


    public class AS400Date
    extends AS400AbstractTime
    Provides a converter between a java.sql.Date object and an IBM i date value such as "12/31/97". In the IBM i programming reference, this type is referred to as the "Date Data Type", or DDS data type L. Note: Only date fields that are stored on the IBM i system as EBCDIC characters are currently supported by this class. (Some IBM i "logical files" have date fields stored as zoned or packed decimal values.)

    An IBM i date value simply indicates a year/month/day, and does not indicate a contextual time zone. Internally, this class interprets all date- and time-related strings as relative to the timezone of the server.

    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 same as the server, 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 the server TimeZone. For example: import java.text.SimpleDateFormat; java.sql.Date date1; // value to be generated by AS400Date SimpleDateFormat formatter = new SimpleDateFormat("yyyy-MM-dd"); // Set the formatter's time zone to GMT. formatter.setTimeZone(as400.getTimeZone()); ... System.out.println("Date value: " + formatter.format(date1));

    Suggestion: To avoid ambiguity and confusion between different kinds of "Date" objects, fully qualify all references to classes java.util.Date and java.sql.Date (especially if you import both java.util.* and java.sql.*).

    Note: In the descriptions of the "format" constants, all example dates represent the date April 25, 1997.

    See Also:
    AS400Time, AS400Timestamp, Serialized Form
    • Constructor Summary

      Constructors 
      Constructor and Description
      AS400Date()
      Constructs an AS400Date object.
      AS400Date(int format)
      Constructs an AS400Date object.
      AS400Date(int format, java.lang.Character separator)
      Constructs an AS400Date object.
      AS400Date(java.util.TimeZone timeZone)
      Constructs an AS400Date object.
      AS400Date(java.util.TimeZone timeZone, int format)
      Constructs an AS400Date object.
      AS400Date(java.util.TimeZone timeZone, int format, java.lang.Character separator)
      Constructs an AS400Date object.
    • Method Summary

      Methods 
      Modifier and Type Method and Description
      static int getByteLength(int format, java.lang.Character separator)
      Returns the number of bytes occupied on the IBM i system by a field of this type.
      java.lang.Object getDefaultValue()
      Returns a Java object representing the default value of the data type.
      int getFormat()
      Gets the format of this AS400Date object.
      int getInstanceType()
      Returns TYPE_DATE.
      java.lang.Class getJavaType()
      Returns the Java class that corresponds with this data type.
      java.lang.Character getSeparator()
      Gets the separator character of this AS400Date object.
      java.sql.Date parse(java.lang.String source)
      Converts a string representation of a date, to a Java object.
      static java.sql.Date parseXsdString(java.lang.String source)
      Converts the specified ISO representation of a date, to a Java object.
      static java.sql.Date parseXsdString(java.lang.String source, java.util.TimeZone timeZone)
      Converts the specified ISO representation of a date, to a Java object.
      void setFormat(int format)
      Sets the format of this AS400Date object.
      void setFormat(int format, char separator)
      Deprecated. 
      void setFormat(int format, java.lang.Character separator)
      Sets the format of this AS400Date object.
      int toBytes(java.lang.Object javaValue, byte[] as400Value, int offset)
      Converts the specified Java object into IBM i format in the specified byte array.
      static int toFormat(java.lang.String formatName)
      Returns the integer format value that corresponds to specified format name.
      java.lang.Object toObject(byte[] as400Value, int offset)
      Converts the specified IBM i data type to a Java object.
      java.lang.String toString(java.lang.Object javaValue)
      Converts the specified Java object into a String representation that is consistent with the format of this data type.
      static java.lang.String toXsdString(java.lang.Object javaValue)
      Converts the specified Java object into an XML Schema string representation.
      static java.lang.String toXsdString(java.lang.Object javaValue, java.util.TimeZone timeZone)
      Converts the specified Java object into an XML Schema string representation.
      static boolean validateFormat(int format)
      Validates the specified format value.
      • Methods inherited from class java.lang.Object

        equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • FORMAT_MDY

        public static final int FORMAT_MDY
        Date format MDY (mm/dd/yy).
        Example: 04/25/97
        Range of years: 1940-2039
        Default separator: '/'
        See Also:
        Constant Field Values
      • FORMAT_DMY

        public static final int FORMAT_DMY
        Date format DMY (dd/mm/yy).
        Example: 25/04/97
        Range of years: 1940-2039
        Default separator: '/'
        See Also:
        Constant Field Values
      • FORMAT_YMD

        public static final int FORMAT_YMD
        Date format YMD (yy/mm/dd).
        Example: 97/04/25
        Range of years: 1940-2039
        Default separator: '/'
        See Also:
        Constant Field Values
      • FORMAT_JUL

        public static final int FORMAT_JUL
        Date format JUL (yy/ddd).
        Example: 97/115
        Range of years: 1940-2039
        Default separator: '/'
        See Also:
        Constant Field Values
      • FORMAT_ISO

        public static final int FORMAT_ISO
        Date format ISO (yyyy-mm-dd).
        Example: 1997-04-25
        Range of years: 0001-9999
        Default separator: '-'
        See Also:
        Constant Field Values
      • FORMAT_USA

        public static final int FORMAT_USA
        Date format USA (mm/dd/yyyy).
        Example: 04/25/1997
        Range of years: 0001-9999
        Default separator: '/'
        See Also:
        Constant Field Values
      • FORMAT_EUR

        public static final int FORMAT_EUR
        Date format EUR (dd.mm.yyyy).
        Example: 25.04.1997
        Range of years: 0001-9999
        Default separator: '.'
        See Also:
        Constant Field Values
      • FORMAT_JIS

        public static final int FORMAT_JIS
        Date format JIS (yyyy-mm-dd).
        Example: 1997-04-25
        Range of years: 0001-9999
        Default separator: '-'
        See Also:
        Constant Field Values
      • FORMAT_CYMD

        public static final int FORMAT_CYMD
        Date format CYMD (cyy/mm/dd).
        Example: 097/04/25
        Range of years: 1900-2899
        Default separator: '/'
        See Also:
        Constant Field Values
      • FORMAT_CMDY

        public static final int FORMAT_CMDY
        Date format CMDY (cmm/dd/yy).
        Example: 004/25/97
        Range of years: 1900-2899
        Default separator: '/'
        See Also:
        Constant Field Values
      • FORMAT_CDMY

        public static final int FORMAT_CDMY
        Date format CDMY (cdd/mm/yy).
        Example: 025/04/97
        Range of years: 1900-2899
        Default separator: '/'
        See Also:
        Constant Field Values
      • FORMAT_LONGJUL

        public static final int FORMAT_LONGJUL
        Date format LONGJUL (yyyy/ddd).
        Example: 1997/115
        Range of years: 0001-9999
        Default separator: '/'
        See Also:
        Constant Field Values
      • FORMAT_MY

        public static final int FORMAT_MY
        Date format MY (mm/yy).
        Example: 04/97
        Range of years: 1940-2039
        Default separator: '/'
        See Also:
        Constant Field Values
      • FORMAT_YM

        public static final int FORMAT_YM
        Date format YM (yy/mm).
        Example: 97/04
        Range of years: 1940-2039
        Default separator: '/'
        See Also:
        Constant Field Values
      • FORMAT_MYY

        public static final int FORMAT_MYY
        Date format MYY (mm/yyyy).
        Example: 04/1997
        Range of years: 0001-9999
        Default separator: '/'
        See Also:
        Constant Field Values
      • FORMAT_YYM

        public static final int FORMAT_YYM
        Date format YYM (yyyy/mm).
        Example: 1997/04
        Range of years: 0001-9999
        Default separator: '/'
        See Also:
        Constant Field Values
    • Constructor Detail

      • AS400Date

        public AS400Date()
        Constructs an AS400Date object. Assumes the default GMT time zone. Format FORMAT_ISO and separator '-' are used.
      • AS400Date

        public AS400Date(java.util.TimeZone timeZone)
        Constructs an AS400Date object. Format FORMAT_ISO and separator '-' are used.
        Parameters:
        timeZone - timezone to use for this date
      • AS400Date

        public AS400Date(int format)
        Constructs an AS400Date object. The specified format's default separator is used. Assumes the default GMT timezone
        Parameters:
        format - The date format. For a list of valid values, refer to AS400Date(int,Character).
      • AS400Date

        public AS400Date(java.util.TimeZone timeZone,
                 int format)
        Constructs an AS400Date object. The specified format's default separator is used.
        Parameters:
        timeZone - Time zone to use for this object.
        format - The date format. For a list of valid values, refer to AS400Date(int,Character).
    >
    • Method Detail

      • getDefaultValue

        public java.lang.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.Date object with a value of January 1, 1970, 00:00:00 GMT.
      • getFormat

        public int getFormat()
        Gets the format of this AS400Date object.
        Returns:
        format The format for this object. For a list of possible values, refer to AS400Date(int,Character).
      • getSeparator

        public java.lang.Character getSeparator()
        Gets the separator character of this AS400Date object.
        Returns:
        separator The separator character. For a list of possible values, refer to AS400Date(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 AS400Date object. The specified format's default separator character is used.
        Parameters:
        format - The format for this object. For a list of valid values, refer to AS400Date(int,Character).
      • setFormat

        public void setFormat(int format,
                     java.lang.Character separator)
        Sets the format of this AS400Date object.
        Parameters:
        format - The format for this object. For a list of valid values, refer to AS400Date(int,Character).
        separator - The separator character. For a list of valid values, refer to AS400Date(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 AS400Date object.
        Parameters:
        format - The format for this object. For a list of valid values, refer to AS400Date(int,Character).
        separator - The separator character.
      • toFormat

        public static int toFormat(java.lang.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 date format name.
        Valid values are:
        • MDY
        • DMY
        • YMD
        • JUL
        • ISO
        • USA
        • EUR
        • JIS
        • CYMD
        • CMDY
        • CDMY
        • LONGJUL
        • MY
        • YM
        • MYY
        • YYM
        Returns:
        the format value. For example, if formatName is "ISO", then FORMAT_ISO is returned.
      • toBytes

        public int toBytes(java.lang.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.Date. Hours, minutes, seconds, and milliseconds 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:
        The number of bytes in the IBM i representation of the data type.
      • toObject

        public java.lang.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.Date object corresponding to the data type. The reference time zone for the object is GMT.
      • toString

        public java.lang.String toString(java.lang.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.Date, 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.
      • parse

        public java.sql.Date parse(java.lang.String source)
        Converts a string representation of a date, to a Java object.
        Parameters:
        source - A date value expressed as a string in the format specified for this AS400Date object.
        Returns:
        A java.sql.Date object representing the specified date. The reference time zone for the object is GMT.
      • parseXsdString

        public static java.sql.Date parseXsdString(java.lang.String source)
        Converts the specified ISO representation of a date, to a Java object. This method is provided for use by the PCML infrastructure; in particular, when parsing 'init=' values for 'date' data elements. This assumes the reference timezone to be GMT
        Parameters:
        source - A date value expressed as a string in format yyyy-MM-dd.
        Returns:
        A java.sql.Date object representing the specified date.
      • parseXsdString

        public static java.sql.Date parseXsdString(java.lang.String source,
                                   java.util.TimeZone timeZone)
        Converts the specified ISO representation of a date, to a Java object. This method is provided for use by the PCML infrastructure; in particular, when parsing 'init=' values for 'date' data elements.
        Parameters:
        source - A date value expressed as a string in format yyyy-MM-dd.
        timeZone - Time zone used by the date.
        Returns:
        A java.sql.Date object representing the specified date. The reference time zone must be passed as a parameter.
      • toXsdString

        public static java.lang.String toXsdString(java.lang.Object javaValue)
        Converts the specified Java object into an XML Schema string representation. This method is provided for use by the PCML infrastructure. This method assumes the use of the GMT timezone.
        Parameters:
        javaValue - The object corresponding to the data type. This must be an instance of java.sql.Date, and must be within the range specifiable by this data type.
        Returns:
        The date expressed as a string in format yyyy-MM-dd.
      • toXsdString

        public static java.lang.String toXsdString(java.lang.Object javaValue,
                                   java.util.TimeZone timeZone)
        Converts the specified Java object into an XML Schema string representation. 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.Date, and must be within the range specifiable by this data type.
        timeZone - The timezone used to evaluate the string.
        Returns:
        The date expressed as a string in format yyyy-MM-dd.
      • 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 AS400Date(int,Character).
        Returns:
        true if the format is valid; false otherwise.
      • getByteLength

        public static int getByteLength(int format,
                        java.lang.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. For a list of valid values, refer to AS400Date(int,Character).
        separator - The separator character. For a list of valid values, refer to AS400Date(int,Character).
        Returns:
        the number of bytes occupied.