[Task] Implement more commonly used converter classes

[delei]

Motivation

During usage, we may need to convert read or written data into specific formats. Apache Fesod (Incubating) provides a flexible converter mechanism that allows users to define custom data conversion rules to meet various business requirements. Many converter classes are already built in, but some are still missing.

How to complete

Please link this issue in the description of the PR.

This will be a long-term task, allowing all the volunteers to divide it into multiple PRs for completion. Each PR can contain one or more converters, and each converter needs to provide the corresponding unit test code.

Only classes compatible with JDK 8 are supported. Each converter must implement the org.apache.fesod.sheet.converters.Converter interface, and please leave a comment outlining your specific implementation proposal.

Task List

The following are some conversions that are currently required

• java.sql.Timestamp @SyedIshmumAhnaf
• java.sql.Clob @AhmedYoussef98
• java.time.ZonedDateTime @alexsmolya
• java.time.LocalTime @leehaut
• java.time.OffsetDateTime @Mikkey-f

Please feel free to suggest any type converters you require, and please leave a comment in this issue.

The new proposal needs to be published for at least 24 hours. If there are no objections during this period, please feel free to submit your PR at any time. These will be added to the task list and assigned to volunteers later.

[alexsmolya]

Here is an implementation proposal for java.time.ZonedDateTime converters, following the established LocalDateTime / LocalDate pattern:

1. Proposed Converter Family (org.apache.fesod.sheet.converters.zoneddatetime)

• ZonedDateTimeDateConverter (Write -> Excel DATE cell):
  • Emits WriteCellData(value.toLocalDateTime()) with default date format (yyyy-MM-dd HH:mm:ss).
• ZonedDateTimeNumberConverter (Bidirectional Excel NUMBER serial):
  • Read: Parses Excel numeric serial to LocalDateTime (respecting use1904windowing), then assigns ZoneId.systemDefault() (localDateTime.atZone(ZoneId.systemDefault())).
  • Write: Converts value.toLocalDateTime() to numeric serial via DateUtil.getExcelDate(value.toLocalDateTime(), use1904).
• ZonedDateTimeStringConverter (Bidirectional Excel STRING cell):
  • Read: Parses according to @DateTimeFormat if specified, or standard DateUtils patterns, attaching ZoneId.systemDefault() when no zone/offset is present in the input string.
  • Write: Formats date-time using @DateTimeFormat (default yyyy-MM-dd HH:mm:ss) and configured Locale.

2. Timezone & Lossiness Semantics

• Numeric & Date cells: Native Excel sheets store temporal values as zone-less numbers/dates. Writing ZonedDateTime necessarily preserves the local wall-clock time (zonedDateTime.toLocalDateTime()) while omitting the ZoneId/offset in the Excel file.
• Reading numeric cells: Converts to LocalDateTime and attaches ZoneId.systemDefault(), matching the convention used across existing Date / LocalDateTime conversions.
• String cells: When explicit zone/offset patterns (e.g. yyyy-MM-dd'T'HH:mm:ssXXX) are used via @DateTimeFormat, the offset/zone can be parsed or emitted verbatim.

3. Registration & Test Coverage

• Register ZonedDateTimeNumberConverter and ZonedDateTimeStringConverter in DefaultConverterLoader.initAllConverter().
• Register ZonedDateTimeDateConverter and ZonedDateTimeStringConverter in DefaultConverterLoader.initDefaultWriteConverter().
• Add unit tests in ConverterTest (supportJavaTypeKey, supportExcelTypeKey, read/write assertions for Date, Number, String).
• Add round-trip integration coverage in ConverterDataTest across all supported formats (XLSX, XLS, CSV, etc.).
• Validate immutability in DefaultConverterLoaderTest.

Feedback and thoughts from the community are welcome!

[delei]

Here is an implementation proposal for java.time.ZonedDateTime converters, following the established LocalDateTime / LocalDate pattern

Hi, @alexsmolya , welcome !

SGTM, +1.

BTW, the unit test class can be independently added to the org.apache.fesod.sheet.converter package. For example, add a ZonedDateTimeConverterTest class.

Welcome, the proposal is to be published for 24 hours, if no objections are raised, the task will be assigned to you.

[SyedIshmumAhnaf]

I’d like to work on the java.sql.Timestamp converter support.

My proposed approach is to follow the existing Date / LocalDateTime converter pattern and add a dedicated Timestamp converter family under org.apache.fesod.sheet.converters:

• TimestampDateConverter
  • Default write path for Timestamp
  • Preserve the existing date-format handling used by the other temporal converters
• TimestampNumberConverter
  • Read Excel numeric date values into Timestamp
  • Write Timestamp values as Excel date serials
  • Reuse the existing date utilities and respect use1904windowing
• TimestampStringConverter
  • Read and write string values using the existing DateUtils formatting/parsing behavior
  • Respect @DateTimeFormat and the configured locale

For registration, I plan to follow the current LocalDateTime setup in DefaultConverterLoader:

• register the Number and String converters in initAllConverter()
• register the Date converter as the default write converter
• register the String converter for string-formatted writes

Since converter lookup is keyed by the declared Java class, the existing java.util.Date converters do not automatically cover fields declared as java.sql.Timestamp, so I would keep the change scoped to adding explicit Timestamp support rather than changing the converter lookup mechanism.

For tests, I plan to add a dedicated TimestampConverterTest covering the converter keys and read/write behavior, including the relevant date-format / 1904-windowing cases, plus the existing loader or round-trip coverage where appropriate.

I’ll keep the implementation JDK 8 compatible and limited to the Timestamp slice of this issue.

If this direction looks good, I’d be happy to take it.

[delei]

I’d like to work on the java.sql.Timestamp converter support.

Hi, @SyedIshmumAhnaf

SGTM, +1.

Welcome, the proposal is to be published for 24 hours, if no objections are raised, the task will be assigned to you.

[delei]

Here is an implementation proposal for java.time.ZonedDateTime converters, following the established LocalDateTime / LocalDate pattern

Hi, @alexsmolya , welcome !

SGTM, +1.

BTW, the unit test class can be independently added to the org.apache.fesod.sheet.converter package. For example, add a ZonedDateTimeConverterTest class.

Welcome, the proposal is to be published for 24 hours, if no objections are raised, the task will be assigned to you.

Hi, @alexsmolya

It has been assigned to you. Please refer to the code contribution guidelines and feel free to submit a PR at any time, and please link this issue in the description of the PR.

[delei]

I’d like to work on the java.sql.Timestamp converter support.

Hi, @SyedIshmumAhnaf

SGTM, +1.

Welcome, the proposal is to be published for 24 hours, if no objections are raised, the task will be assigned to you.

Hi, @SyedIshmumAhnaf

It has been assigned to you. Please refer to the code contribution guidelines and feel free to submit a PR at any time, and please link this issue in the description of the PR.

[AhmedYoussef98]

I'd like to work on the java.sql.Clob converter (still unassigned in the task list).

Proposed approach, following the existing String converter family (StringStringConverter, StringNumberConverter) under a new org.apache.fesod.sheet.converters.clob package:

• ClobStringConverter (bidirectional, Excel STRING cell)
  • Read: builds a java.sql.Clob from the cell's string value via javax.sql.rowset.serial.SerialClob (JDK 8 compatible, no external deps), i.e. new SerialClob(cellData.getStringValue().toCharArray()).
  • Write: extracts the full contents with clob.getSubString(1, (int) clob.length()) and wraps it in a WriteCellData<>(...), matching StringStringConverter's write path.

Registration: add to DefaultConverterLoader.initAllConverter() (as the String-keyed converters are), keyed on Clob.class / CellDataTypeEnum.STRING.

Tests: add a ClobConverterTest under org.apache.fesod.sheet.converter (same location as StringPathnameImageConverterTest/CustomConverterTest), covering supportJavaTypeKey/supportExcelTypeKey, round-trip read/write, and an empty-string edge case. SQLException from SerialClob construction will propagate per the Converter interface's throws Exception contract.

Scope is limited to this one converter — happy to take another (e.g. java.sql.Clob's counterpart on read-only numeric/boolean cells) as a follow-up if useful. Will link this issue in the PR per the contribution guide.

[delei]

I'd like to work on the java.sql.Clob converter (still unassigned in the task list).
...

• Write: extracts the full contents with clob.getSubString(1, (int) clob.length()) and wraps it in a WriteCellData<>(...), matching StringStringConverter's write path.

Hi, @AhmedYoussef98

SGTM, +1.

FYI, regarding string slicing, please note that the maximum text length in Excel cells is 32767. If possible, it is recommended to adhere to this limit and provide similar test cases in the unit tests.

Welcome, the proposal is to be published for 24 hours, if no objections are raised, the task will be assigned to you.