Package oracle.kv.table

# Interface TimestampDef

All Superinterfaces:
  `FieldDef`

public interface TimestampDef extends FieldDef
TimestampDef is an extension of `FieldDef` to encapsulate a Timestamp type.

Since:
  4.3

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from interface oracle.kv.table.FieldDef

  `FieldDef.Type`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `DEFAULT_PATTERN`
  The default pattern of Timestamp string, it is the pattern used to format a TimestampValue to a string or parse TimestampValue from a string, the time zone for formatting and parsing is UTC zone.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `TimestampDef`
  `clone()`
  Perform a deep copy of this FieldDef instance.
  `TimestampValue`
  `currentTimestamp()`
  Creates a TimestampValue instant set to the current system millisecond time.
  `TimestampValue`
  `fromString(String timestampString)`
  Creates a TimestampValue instance from a String, the string must be in the format of `DEFAULT_PATTERN` with UTC zone.
  `TimestampValue`
  `fromString(String timestampString, String pattern, boolean withZoneUTC)`
  Creates a TimestampValue instance from a String with specified pattern.
  `int`
  `getPrecision()`

  ### Methods inherited from interface oracle.kv.table.FieldDef

  `asAny, asAnyAtomic, asAnyJsonAtomic, asAnyRecord, asArray, asBinary, asBoolean, asDouble, asEnum, asFixedBinary, asFloat, asInteger, asJson, asLong, asMap, asNumber, asRecord, asString, asTimestamp, createArray, createBinary, createBoolean, createDouble, createEnum, createFixedBinary, createFloat, createInteger, createJsonNull, createLong, createMap, createNumber, createNumber, createNumber, createNumber, createNumber, createRecord, createString, createTimestamp, getDescription, getType, isAny, isAnyAtomic, isAnyJsonAtomic, isAnyRecord, isArray, isAtomic, isBinary, isBoolean, isComplex, isDouble, isEnum, isFixedBinary, isFloat, isInteger, isJson, isLong, isMap, isMRCounter, isNumber, isNumeric, isPrecise, isRecord, isString, isTimestamp, isType, isUUIDString, isValidIndexField, isValidKeyField`

- ## Field Details

  - ### DEFAULT_PATTERN

    static final String DEFAULT_PATTERN

    The default pattern of Timestamp string, it is the pattern used to format a TimestampValue to a string or parse TimestampValue from a string, the time zone for formatting and parsing is UTC zone.

    About the number of digits of fractional second:

    - When format a TimestampValue to a string, the number of digits is determined by the precision of TimestampDef.

            e.g. A table t1 contains 3 TIMESTAMP fields:
                CREATE TABLE t1(id INTEGER,
                                ts0 TIMESTAMP(0),
                                ts3 TIMESTAMP(3),
                                ts9 TIMESTAMP(9),
                                PRIMARY KEY(id));

            Table t1 = store.getTableAPI().getTable("t1");

            TimestampDef def0 = t1.getField("ts0").asTimestamp();
            TimestampDef def3 = t1.getField("ts3").asTimestamp();
            TimestampDef def9 = t1.getField("ts9").asTimestamp();

            /* Supposes local zone is UTC. */
            Timestamp ts = Timestamp.valueOf("2016-07-27 12:45:21.123456789");

            /* Converts the TimestampValue created with def0 to a string. */
            String str0 = def0.createTimestamp(ts).toString();
            System.out.println(str0);       // 2016-07-27T12:45:21

            /* Converts the TimestampValue created with def3 to a string. */
            String str3 = def3.createTimestamp(ts).toString();
            System.out.println(str3);       // 2016-07-27T12:45:21.123

            /* Converts the TimestampValue created with def9 to a string. */
            String str9 = def9.createTimestamp(ts).toString();
            System.out.println(str9);       // 2016-07-27T12:45:21.123456789

    - When parse a TimestampValue from a string, the fractional second part is optional, the number of digits can any value between 0 and 9.

            String str = "2016-07-27T12:45:21.987654321";
            /*
             * The value of tsv0 is "2016-07-27 12:45:22 UTC", the fractional
             * second is rounded up to 1 second.
             */
            TimestampValue tsv0 = def0.fromString(str);

            /*
             * The value of tsv3 is 2016-07-27 12:45:21.988 UTC, the fractional
             * second is rounded up to 988 with precision of 3.
             */
            TimestampValue tsv3 = def3.fromString(str);

            /* The value of tsv9 is 2016-07-27 12:45:21.987654321 UTC. */
            TimestampValue tsv9 = def9.fromString(str);

    See Also:
      - Constant Field Values

- ## Method Details

  - ### getPrecision

    int getPrecision()
    Returns:
      the precision of fractional second

  - ### clone

    TimestampDef clone()
    Description copied from interface: `FieldDef`
    Perform a deep copy of this FieldDef instance.
    Specified by:
      `clone` in interface `FieldDef`
    Returns:
      a deep copy of this object

  - ### fromString

    TimestampValue fromString(String timestampString)
    Creates a TimestampValue instance from a String, the string must be in the format of `DEFAULT_PATTERN` with UTC zone.
    Parameters:
      `timestampString` - a string in format of default pattern.
    Returns:
      a TimestampValue instance.
    Throws:
      `IllegalArgumentException` - if the string cannot be parsed with the default pattern correctly.

  - ### fromString

    TimestampValue fromString(String timestampString, String pattern, boolean withZoneUTC)
    Creates a TimestampValue instance from a String with specified pattern.
    Parameters:
      `timestampString` - a timestamp string in format of specified `pattern` or default pattern `DEFAULT_PATTERN` if `pattern` is null.
      `pattern` - the pattern for the timestampString. If null, then default pattern `DEFAULT_PATTERN` is used to parse the string. The symbols that can be used to specify a pattern are described in `DateTimeFormatter`.
      `withZoneUTC` - true if UTC time zone is used as default zone when parse from a timestamp string, otherwise local time zone is used as default zone. If the timestampString has zone information, then the zone will take precedence over the default zone.
    Returns:
      a TimestampValue instance
    Throws:
      `IllegalArgumentException` - if the string cannot be parsed with the the given pattern correctly.

  - ### currentTimestamp

    TimestampValue currentTimestamp()
    Creates a TimestampValue instant set to the current system millisecond time.
    Returns:
      a TimestampValue instance