Change outdated and/or deprecated data binding defaults for String, Instant and Duration

[nvamelichev]

Change outdated and/or deprecated data binding defaults, while supporting older defaults for backwards compatibility. 1-2 months after initial commit

• String <-> UTF8 (because a YDB STRING is actually a byte array)
• Instant <-> TIMESTAMP, Duration <-> INTERVAL.
• Mapping Instant <-> [U]INT64 should use MILLISECONDS qualifier by default, for maximum backwards compatibility (YOJ initially supported only milliseconds precision when storing Instants)

[nvamelichev]

@lavrukov @akorsukov Proposed plan of action:

• For String we have migration methods YqlPrimitiveType.changeStringDefaultTypeToUtf8() as a temporary measure. Will add a YqlPrimitiveType.useLegacyMappingForString(); method and ask all legacy-users to call it. After everyone migrates to explicit call, we can change the default mapping to UTF8.
• For Instant, we'll add a similar pair of functions to set the default, and gradually migrate, eventually making TIMESTAMP the default type. We should support microsecond precision, because that's what both Java 9+ and YDB support (https://ydb.tech/docs/en/yql/reference/types/primitive#datetime).
• For Duration, we can set default to INTERVAL right now, because previously there was NO default, and everyone has explicitly annotated their Duration fields, or used e.g. a two-field (seconds, nanos) composite value. Must ensure we support microsecond precision, because that's what both Java 9+ and YDB use (https://ydb.tech/docs/en/yql/reference/types/primitive#datetime).

[nvamelichev]

@lavrukov @akorsukov What's the position of Cloud Java on this? Will you be able to explicitly set legacy mapping defaults for your services in a YC-specific module, so that YOJ can use more sensible type mapping for Strings, Instants and Durations?

If that's OK, I'll first add explicit "set legacy mapping" methods that you can use.

[nvamelichev]

Added opt-in support for New Mapping in YOJ 2.1.0.

yoj-repository-ydb-v2 users are encouraged to call

YqlPrimitiveType.useLegacyMappingFor(STRING, ENUM, TIMESTAMP);

in legacy projects to keep the old mapping, and

YqlPrimitiveType.useRecommendedMappingFor(STRING, ENUM, TIMESTAMP);

in new projects to get the new mapping.

Note that yoj-repository-ydb-v1 has no such function because support for YDB SDK v1 is deprecated.

[nvamelichev]

⚠️ YOJ 2.2.x will use legacy YDB<-> Java type mapping, but THE DEFAULT WILL CHANGE IN YOJ 3.0.

What should you do?

• To continue using the legacy mapping safely, call

YqlPrimitiveType.useLegacyMappingFor(STRING, ENUM, TIMESTAMP);

before initializing YOJ, e.g., in a lifecycle method.

• In new projects, we recommend to the new mapping (which will become DEFAULT in YOJ 3.x). To do so, call:

YqlPrimitiveType.useLegacyMappingFor(STRING, ENUM, TIMESTAMP);

before initializing YOJ, e.g., in a lifecycle method.

---

👍 Using the NEW MAPPING is HIGHLY RECOMMENDED for new projects, when you have no existing table schema and/or data to migrate.

If you decide to use the new mapping in an OLD project, remember to annotate existing entities' columns with the column type used in the database:

• @Column(dbType=DbType.STRING) to retain the legacy mapping java.lang.String, java.lang.Enum<->YDB STRING (=byte array)
• @Column(dbType=DbType.INT64, qualifier=DbQualifier.MILLISECONDS) to retain the legacy mapping java.time.Instant<->YDB INT64 (millisecond accuracy).

[nvamelichev]

See also: #71 for more mapping improvements.